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

事务 API

编辑

Transaction API

编辑

一个事务将多个 Span 分组到一个逻辑组中。

要获取 Transaction 对象，您需要调用 apm.startTransaction()。

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

transaction.name

编辑

添加于：v0.1.0

事务的名称。

可用于设置或覆盖事务的名称（在性能监控分解中可见）。如果您无权访问当前事务，您还可以使用 apm.setTransactionName() 设置名称。

具有相同名称和 类型的事务将被分组在一起。

transaction.type

编辑

添加于：v0.1.0

在以下版本中将组件拆分为 type、subtype 和 action：v3.0.0

事务的类型。

有一个名为 request 的特殊类型，代理在检测到传入的 HTTP 请求时会自动创建事务。

transaction.subtype [v3.25.0] 在 v3.25.0 中已弃用。

编辑

添加于：v3.0.0
已弃用于：v3.25.0

事务的子类型。事务的 subtype 字段已弃用：它不使用，将在下一个主要版本中删除。

transaction.action [v3.25.0] 在 v3.25.0 中已弃用。

编辑

添加于：v3.0.0
已弃用于：v3.25.0

事务的操作。事务的 action 字段已弃用：它不使用，将在下一个主要版本中删除。

transaction.traceparent

编辑

添加于：v2.9.0

获取事务的序列化 traceparent 字符串。

transaction.result

编辑

添加于：v0.1.0

描述事务结果的字符串。这通常是 HTTP 状态代码，或者例如后台任务的“success”或“failure”。

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

编辑

添加于：v2.0.0

在以下版本中将 type 拆分为 type、subtype 和 action：v3.0.0

  • name <string> Span 的名称。您也可以通过 span.name 设置此项。默认值： unnamed
  • type <string> Span 的类型。您也可以通过 span.type 设置此项。
  • subtype <string> Span 的子类型。您也可以通过 span.subtype 设置此项。
  • action <string> Span 的操作。您也可以通过 span.action 设置此项。

  • options - 支持以下选项

    • startTime <number> Span 开始的时间。必须是 Unix 时间戳，表示自 1970 年 1 月 1 日 00:00:00 UTC 以来经过的毫秒数。可以使用小数来实现亚毫秒精度。如果未提供，则将使用当前时间。
    • exitSpan <boolean> 创建一个“出口 Span”。出口 Span 表示传出的通信。它们用于在 服务地图中创建一个节点，并在 依赖关系表中创建一个下游服务。提供的子类型将用作下游服务名称。
    • links <Array> Span 链接。一个 Span 可以引用零个或多个其他事务或 Span（与其父级分开）。Span 链接将显示在 Kibana APM 应用跟踪视图中。links 参数是一个对象数组，其中包含一个单独的 “context” 字段，该字段是 Transaction、Span 或 W3C trace-context traceparent 字符串。例如：transaction.startSpan('aName', { links: [{ context: anotherSpan }] })。

启动并返回与此事务关联的新自定义 Span。当启动 Span 时，它将测量时间，直到调用 span.end()。

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

transaction.setLabel(name, value[, stringify = true])

编辑

添加于：v0.1.0
从 transaction.setTag() 重命名为 transaction.setLabel()：v2.10.0
在以下版本中添加了 stringify 参数：v3.11.0

  • name <string> 任何句点 (.)、星号 (*) 或双引号 (") 都将替换为下划线 (_)，因为这些字符在 Elasticsearch 中具有特殊含义
  • value <string> | <number> | <boolean> 如果未提供 stringify 参数，或将其设置为 true，则给定的值将转换为字符串。
  • stringify <boolean> 为了向后兼容，此值默认为 true，但新用法通常需要 false。如果为 true，则给定非字符串 value 时，在发送到 APM 服务器之前会将其转换为字符串。
transaction.setLabel('productId', 42, false);

在事务上设置标签。您可以在同一事务上设置多个标签。如果在事务期间发生错误，它也会被标记上相同的标签。

标签是 Elasticsearch 索引的键/值对，因此是可搜索的（与通过 apm.setCustomContext() 设置的数据相反）。在使用自定义标签之前，请确保您了解可用的不同类型的元数据。

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

transaction.addLabels({ [name]: value }[, stringify = true])

编辑

添加于：v1.5.0
从 transaction.addTags() 重命名为 transaction.addLabels()：v2.10.0
在以下版本中添加了 stringify 参数：v3.11.0

  • labels <Object> 包含键/值对

    • name <string> 任何句点 (.)、星号 (*) 或双引号 (") 都将替换为下划线 (_)，因为这些字符在 Elasticsearch 中具有特殊含义
    • value <string> | <number> | <boolean> 如果未提供 stringify 参数，或将其设置为 true，则给定的值将转换为字符串。
  • stringify <boolean> 为了向后兼容，此值默认为 true，但新用法通常需要 false。如果为 true，则给定非字符串 value 时，在发送到 APM 服务器之前会将其转换为字符串。
transaction.addLabels({productId: 42, productName: 'butter'}, false);

在事务上添加多个标签。您可以多次添加标签。如果在事务期间发生错误，它也会被标记上相同的标签。

标签是 Elasticsearch 索引的键/值对，因此是可搜索的（与通过 apm.setCustomContext() 设置的数据相反）。在使用自定义标签之前，请确保您了解可用的不同类型的元数据。

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

transaction.ensureParentId()

编辑

添加于：v2.0.0

如果事务还没有父 ID，则调用此方法会生成一个新的父 ID，将其设置为此事务的父 ID，并将其作为 <string> 返回。

这使得可以将 JavaScript 真实用户监控 (RUM) 代理为初始页面加载创建的跨度与后端服务的事务相关联。如果您的后端服务动态生成 HTML 页面，则使用此方法的值初始化 JavaScript RUM 代理可以分析在浏览器中花费的时间与在后端服务中花费的时间。

要启用 JavaScript RUM 代理，请将类似于以下的代码片段添加到 HTML 页面的主体中，最好在其他 JavaScript 库之前添加：

elasticApm.init({
  serviceName: 'my-frontend-app', // Name of your frontend app
  serverUrl: 'https://example.com:8200', // APM Server host
  pageLoadTraceId: '${transaction.traceId}',
  pageLoadSpanId: '${transaction.ensureParentId()}',
  pageLoadSampled: ${transaction.sampled}
})

有关更多信息，请参阅 JavaScript RUM 代理文档。

transaction.ids

编辑

添加于：v2.17.0

生成一个包含 transaction.id 和 trace.id 的对象。这使得可以使用结构化日志记录器将日志与 APM 跟踪相关联。

{
  "trace.id": "abc123",
  "transaction.id": "abc123"
}

transaction.end([result][, endTime])

编辑

添加于：v0.1.0

  • result <string> 描述事务的结果。这通常是 HTTP 状态代码，例如，后台任务的 “success” 或 “failure”
  • endTime <number> 事务结束的时间。必须是一个 Unix 时间戳，表示自 1970 年 1 月 1 日 00:00:00 UTC 以来的毫秒数。可以使用小数来实现亚毫秒精度。如果未提供，将使用当前时间

结束事务。如果事务已结束，则不会发生任何操作。

或者，您可以调用 apm.endTransaction() 来结束活动事务。

transaction.outcome

编辑

添加于：v3.12.0

Node.js 代理会自动在事务上设置 outcome 属性。此属性将是以下三个值之一：

  • success：表示事务的操作成功。
  • failure：表示事务的操作不成功。
  • unknown：表示我们无法确定事务的操作是否成功。 unknown 结果将事务从错误率考虑中删除。

如果底层 HTTP 请求处理生成的响应的状态代码小于 500，则认为事务是成功的。状态代码为 500 或更大则被认为是失败。

非 HTTP 事务将以 unknown 的结果开始。

transaction.setOutcome(outcome)

编辑

添加于：v3.12.0

setOutcome 方法允许最终用户覆盖 Node.js 代理对事务的 outcome 属性的默认设置。setOutcome 方法接受 success、failure 或 unknown 的字符串，并将强制代理报告此特定跨度的值。

transaction.addLink(link)

编辑

添加于：v4.7.0

  • link {type-link}

一个事务可以引用零个或多个其他事务或跨度（与其父项分开）。跨度链接将显示在 Kibana APM 应用程序跟踪视图中。 link 参数是一个带有单个 “context” 字段的对象，该字段是 Transaction、Span、OpenTelemetry SpanContext 对象或 W3C trace-context traceparent 字符串。例如：transaction.addLink({ context: anotherSpan })。

transaction.addLinks([links])

编辑

添加于：v4.7.0

向此事务添加跨度链接。

一个事务可以引用零个或多个其他事务或跨度（与其父项分开）。跨度链接将显示在 Kibana APM 应用程序跟踪视图中。 link 参数是一个带有单个 “context” 字段的对象，该字段是 Transaction、Span、OpenTelemetry SpanContext 对象或 W3C trace-context traceparent 字符串。例如：transaction.addLinks([{ context: anotherSpan }])。

« Agent API Span API »