Span API

span 衡量单个事件的持续时间。创建 span 后，它将测量直到调用 span.end() 为止的时间。

要获取 Span 对象，您需要调用 apm.startSpan()。

有关使用自定义 span 的示例，请参阅Node.js 中的自定义 Span 文章。

添加于：v0.1.0

• 类型： Transaction

对父事务对象的引用。

所有 span 都属于一个事务。

添加于：v0.1.0

• <string> 默认值： unnamed

span 的名称。也可以通过 apm.startSpan() 设置。

添加于：v0.1.0

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

• <string> 默认值： custom

span 的类型。也可以通过 apm.startSpan() 设置。

类型用于将相似的 span 分组在一起。例如，所有 MySQL 查询的 span 都被赋予 db 类型，子类型为 mysql，动作为 query。

在上面的示例中，db 被视为类型。虽然对类型没有命名限制，但以下类型在所有 Elastic APM 代理中都是标准化的：app、db、cache、template 和 ext。

添加于：v0.1.0

• <string> 默认值： custom

span 的子类型。也可以通过 apm.startSpan() 设置。

子类型通常是模块或库的名称。例如，MySQL 查询的子类型为 mysql。

添加于：v0.1.0

• <string> 默认值： custom

span 的动作。也可以通过 apm.startSpan() 设置。

动作通常是特定的函数名称或特定功能的通用描述。例如，数据库查询的动作通常为 query。

添加于：v2.9.0

获取 span 的序列化 traceparent 字符串。

添加于：v2.1.0
从 span.setTag() 重命名为 span.setLabel()：v2.10.0
在 v3.11.0 中添加了 stringify 参数

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

span.setLabel('productId', 42, false);

在 span 上设置标签。您可以在同一个 span 上设置多个标签。

添加于：v2.1.0
从 span.addTags() 重命名为 span.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 Server 之前将其转换为字符串。

span.addLabels({productId: 42, productName: 'butter'}, false);

在 span 上添加多个标签。您可以多次添加标签。

添加于：v2.17.0

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

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

添加于：v0.1.0

• endTime <number> span 结束的时间。必须是一个 Unix 时间戳，表示自 1970 年 1 月 1 日 00:00:00 UTC 以来的毫秒数。可以使用小数实现亚毫秒精度。如果未提供，将使用当前时间

结束 span。如果 span 已经结束，则不会发生任何事情。

添加于：v3.12.0

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

• success：表示 span 的操作成功。
• failure：表示 span 的操作未成功。
• unknown：表示代理无法确定 span 的操作是否成功。unknown 结果将事务从错误率考虑中移除。

成功或失败的构成取决于 span 类型。

在一般情况下，如果 Node.js 代理在执行 span 所代表的工作期间捕获到错误，则 span 的结果将被视为失败。

但是，对于代表 HTTP 请求的退出 span，outcome 基于 HTTP 响应的状态码。状态码小于 400 被视为成功。状态码大于或等于 400 被视为失败。

添加于：v3.12.0

• outcome <string>

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

添加于：v3.39.0

• type <string> | null 目标服务类型，通常与 span.subtype 的值相同，例如 "mysql"。
• name <string> | null 目标服务名称，服务的可选作用域。对于数据库，通常是数据库名称。

手动设置标识下游服务的 service.target.type 和 service.target.name 字段。它们用于 Kibana APM 应用程序中的服务地图和依赖项。这些值仅用于“退出” span — 表示传出通信的 span，在创建 span 时标记为 exitSpan: true。

如果为 type 和 name 提供 false-y 值（例如 null），则 service.target 将明确从该 span 中排除。这可能会影响该服务的服务地图和其他 Kibana APM 应用程序报告。

如果不调用此方法，则服务目标值将从其他 span 字段推断（规范）。

APM Server v8.3 之前的版本会忽略 service.target.* 字段。

添加于：v4.7.0

• link {{type-link}}

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

添加于：v4.7.0

• links <Array> span 链接。

向此 span 添加 span 链接。

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