« 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

在 v3.0.0 中将组件拆分为 type、subtype 和 action。

事务的类型。

有一种特殊类型称为 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 状态代码，或者例如后台任务的“成功”或“失败”。

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

添加于：v2.0.0

在 v3.0.0 中将 type 拆分为 type、subtype 和 action。

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

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

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

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

添加于：v0.1.0
在 v2.10.0 中已将 transaction.setTag() 重命名为 transaction.setLabel()。
在 v3.11.0 中添加了 stringify 参数。

  • 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
在 v3.11.0 中添加了 stringify 参数。

  • 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 状态代码，或者例如后台任务的“成功”或“失败”。
  • 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 跟踪上下文 traceparent 字符串。例如：transaction.addLink({ context: anotherSpan })。

transaction.addLinks([links])编辑

添加于：v4.7.0

将跨度链接添加到此事务。

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

« Agent API Span API »