« Agent API Span API »
Elastic 文档 › ›API 参考

事务 API

编辑

Transaction API

编辑

一个事务将多个 span 在逻辑上分组在一起。

要启动一个事务，您需要调用 apm.startTransaction()。

要查看使用自定义事务的示例，请参阅自定义事务文章。

transaction.name

编辑
  • 类型: 字符串
  • 默认: Unknown

事务的名称。

可用于设置或覆盖事务的名称（在性能监控细分中可见）。

transaction.type

编辑
  • 类型: 字符串
  • 默认: custom

事务的类型。

transaction.timestamp

编辑
  • 类型: 字符串
  • 默认: undefined

事务的时间戳。如果未提供事务时间戳（默认行为），它将由 apm-server (v6.3+) 设置。但是，您可以在客户端上设置时间戳（使用 new Date().toISOString()），但您应该注意，时间戳将反映客户端的本地时间，这可能并不总是准确的。

transaction.startSpan([name][, type][, options])

编辑
const span = transaction.startSpan('My custom span')

启动并返回与此事务关联的新自定义 span。

参数

  • name - span 的名称（字符串）。默认为 unnamed
  • type - span 的类型（字符串）。默认为 custom

  • options - 支持以下选项

    • blocking - 阻止关联的事务在当前 span 结束之前结束。被阻止的 span 会自动创建一个内部任务。默认为 false。
    • parentId - 与新 span 关联的父 id。默认为当前事务 id
    • sync - 表示 span 是同步的还是异步的。

当一个 span 启动时，它将测量时间，直到 span.end() 被调用。在某些情况下，被阻止的 span 允许用户控制托管事务的提前关闭。

有关如何使用自定义 span 的详细信息，另请参阅 Span API 文档。

transaction.block(flag)

编辑
transaction.block(true)

阻止当前正在运行的自动检测或自定义事务在关联的 span 结束后自动关闭。

参数

  • flag - 布尔值。默认为 false。

大多数情况下，用户不需要阻止正在运行的事务，因为代理会尝试考虑所有异步网络活动并捕获所需的信息。当您认为自动检测的代码遗漏了重要活动并过早结束事务时，block API 非常有用。例如，可能存在一个包含许多无法自动检测的异步任务（如 web workers）的页面。

// get the current active autoinstrumented transaction (page-load, route-change, etc.)
const activeTransaction = apm.getCurrentTransaction()

if (activeTransaction) {
  activeTransaction.block(true)
}

// Perform some more async tasks and unblock it
activeTransaction.block(false)

也可以通过创建被阻止的 span 来实现类似的操作。查看托管事务指南以了解更多信息。

transaction.addLabels()

编辑
transaction.addLabels({ [name]: value })

在事务中添加多个标签。如果在事务期间发生错误，它也将被标记为相同的标签。

标签是 Elasticsearch 索引的键/值对，因此可以搜索（与通过 apm.setCustomContext() 设置的数据相反）。

在使用自定义标签之前，请确保您了解可用的不同类型的元数据。

参数

  • name - 任何字符串。所有句点 (.)、星号 (*) 和双引号 (") 都将被替换为下划线 (_)，因为这些字符在 Elasticsearch 中具有特殊含义。
  • value - 任何字符串、布尔值或数字。所有其他数据类型在发送到 APM 服务器之前都会转换为字符串。

避免定义太多用户指定的标签。在一个索引中定义太多唯一字段是一种可能导致映射爆炸的情况。

transaction.end()

编辑
transaction.end()

结束事务。在活动事务上调用 transaction.end 会结束所有底层 span，并将它们标记为 truncated。如果事务已经结束，则不会发生任何事情。

transaction.mark(key)

编辑
transaction.mark(key)

标记当前时间点相对于事务开始的时间。使用此方法标记在事务处于活动状态时发生的重大事件。

参数

  • key - 任何字符串。所有句点 (.)、星号 (*) 和双引号 (") 都将被替换为下划线 (_)，因为这些字符在 Elasticsearch 中具有特殊含义。
« Agent API Span API »