轨迹数据的存储架构

本文档介绍了轨迹 span 的存储格式。数据的格式通常与 OpenTelemetry OTLP 协议定义的 proto 文件一致。不过，在存储之前，字段可能会从 OpenTelemetry 特定的数据类型转换为 JSON 数据类型。

Telemetry API 使用 OpenTelemetry OTLP 协议。此协议依赖于 trace_service.proto 和 trace.proto 文件。如需了解字段限制，请参阅 Telemetry API 限制。

Cloud Trace API 不使用 OpenTelemetry OTLP 协议，而是定义了一种专有数据格式。通过此 API 发送到您 Google Cloud 项目的跟踪记录数据会转换为本文档中所述的格式。不过，Cloud Trace API 的限额仍然适用。

Span 存储格式

字段	说明
trace_id	string 相应轨迹的全局唯一标识符。 此标识符是一个 128 位的数值，格式为 16 字节的十六进制字符串。例如 382d4f4c6b7bb2f4a972559d9085001d。如需详细了解此标识符，请参阅 W3C trace-id。 数值 0 无效。 可视化和分析工具使用 trace_id 来标识与轨迹关联的 span。因此，每个端到端操作都必须具有唯一标识符。请勿重复使用轨迹标识符。
span_id	string 必需。span 的标识符。 在轨迹中必须是唯一的。 此标识符是一个 64 位数值，格式为 8 字节的十六进制字符串。 例如 9046a5b9f7c12500。 数值 0 无效。
trace_state	string 此字段对应于 W3C 跟踪记录上下文定义的 tracestate 标头。 此标头包含配置信息，当应用经过检测以收集跟踪数据时，这些信息会包含在请求中。 例如，应用可以指定概率抽样设置，也可以包含特定于供应商的内容。 OpenTelemetry 库在生成 span 时会自动记录 tracestate 标头的值。
parent_span_id	string 可选。标识调用相应 span 的操作。 “根”span 的父 span ID 设置为 null。 可视化工具会使用 span 之间的父子关系来构建树结构。
name	string 必需。执行的操作的名称。 该名称可以是方法名称，也可以是其他每次调用时的网站名称。 对于同一可执行文件和同一端点，使用一致的名称可更轻松地关联跨轨迹 span。如需了解最佳实践，请参阅如何命名 span。 系统会对 span 名称进行清理，并在 Google Cloud 控制台中显示。
kind	integer 指定操作在系统中的发生位置。 该值对应于 OpenTelemetry：Span Kind 枚举： 值 OpenTelemetry 枚举 0 SPAN_KIND_UNSPECIFIED 1 SPAN_KIND_INTERNAL 2 SPAN_KIND_SERVER 3 SPAN_KIND_CLIENT 4 SPAN_KIND_PRODUCER 5 SPAN_KIND_CONSUMER
start_time	Timestamp 必需。跨度的开始时间，精确到纳秒。
start_time_unix_nano	integer 开始时间（以纳秒为单位，根据 UNIX 纪元计算）。
end_time	Timestamp 必需。时间段的结束时间，精确到纳秒。
end_time_unix_nano	integer 结束时间（以纳秒为单位，根据 UNIX 纪元计算）。
receive_time	Timestamp 必需。接收 span 的时间（精确到纳秒）。
receive_time_unix_nano	integer 结束时间（以纳秒为单位，根据 UNIX 纪元计算）。
duration_unix_nano	integer 时长（以纳秒为单位）。
attributes	JSON type 每个属性都是一个键值对。 可供您使用的属性取决于您的轨迹数据。属性的结构遵循 OpenTelemetry 标准。如需了解详情，请参阅 OpenTelemetry：属性。 OpenTelemetry 为属性指定了语义惯例。如需了解这些惯例，请参阅跟踪语义惯例。 以下是一些属性示例： "yourcompany.your.own.key": "your own value" "network.protocol.name": "http" "network.protocol.version": "1.1" "http.response.status_code": "200" "network.peer.address": "REDACTED"
dropped_attributes_count	integer 已舍弃的属性数量。 属性可能会因键过长或属性过多而被舍弃。如果此值为零，则表示未舍弃任何属性。 此值可能由客户端插桩或应用设置。该值可由服务器递增。
events	包含重复字段的 record 时间点事件。每个事件都包含以下字段。 字段 说明 time Timestamp time_unix_nano integer name string 必需。事件名称。 attributes JSON type 每个属性都是一个键值对。 可供您使用的属性取决于您的轨迹数据。属性的结构遵循 OpenTelemetry 标准。如需了解详情，请参阅 OpenTelemetry：属性。 dropped_attributes_count integer 已舍弃的属性数量。 属性可能会因键过长或属性过多而被舍弃。如果此值为零，则表示未舍弃任何属性。 此值可能由客户端插桩或应用设置。该值可由服务器递增。
dropped_events_count	integer 被舍弃的事件数。由于事件过多，可能会舍弃事件。如果此值为零，则表示未舍弃任何事件。
links	包含重复字段的 record 与 span 关联的链接。链接是指从相应 span 到同一或不同轨迹中另一个 span 的引用。 链接提供了一种机制，用于将一个轨迹中的 span 与另一个轨迹中的 span 相关联。例如，假设某项操作导致异步操作发生。在此场景中，有两个轨迹，一个用于原始操作，另一个用于异步操作。您可以使用链接来关联这些轨迹中的 span。 每个链接都包含以下字段。 字段 说明 trace_id string 必填。 span_id string 必填。 trace_state string attributes JSON type 每个属性都是一个键值对。 可供您使用的属性取决于您的轨迹数据。属性的结构遵循 OpenTelemetry 标准。如需了解详情，请参阅 OpenTelemetry：属性。 dropped_attributes_count integer 已舍弃的属性数量。 属性可能会因键过长或属性过多而被舍弃。如果此值为零，则表示未舍弃任何属性。 此值可能由客户端插桩或应用设置。该值可由服务器递增。
dropped_links_count	integer 已舍弃的链接数。链接可能会因数量过多而被舍弃。如果此值为零，则表示没有丢弃任何链接。
status	不含重复字段的 record 此字段会记录 span 的完成状态。 code 子字段的值对应于 OpenTelemetry：Span 状态枚举： 值 OpenTelemetry 枚举 说明 0 UNSET 成功完成操作。 1 OK 操作被人为标记为无错误。 2 ERROR 操作已完成，但有错误。例如，如果客户端 span 的状态为 400（错误请求），则此字段设置为 ERROR。 message 子字段（格式为字符串）包含错误信息。
resource	不含重复字段的 record 此字段用于标识遥测数据的收集来源或遥测数据所涉及的基础设施或托管系统。例如，假设某个应用在 Google Kubernetes Engine 上运行。此资源的属性可能包括进程名称和命名空间。 此字段包含以下子字段： 字段 说明 attributes JSON type 每个属性都是一个键值对。 可供您使用的属性取决于您的轨迹数据。属性的结构遵循 OpenTelemetry 标准。如需了解详情，请参阅 OpenTelemetry：属性。 以下是资源属性的示例： cloud.account.id: "my-project" cloud.platform: "gcp_kubernetes_engine" cloud.provider: "gcp" cloud.region: "us-central1" gcp.project_id: "my-project" host.id: "REDACTED" host.name: "gke-otel-demo" k8s.cluster.name: "otel-demo" k8s.deployment.name: "otel-demo-frontendproxy" dropped_attributes_count integer 已舍弃的属性数量。 属性可能会因键过长或属性过多而被舍弃。如果此值为零，则表示未舍弃任何属性。 此值可能由客户端插桩或应用设置。该值可由服务器递增。 如需了解详情，请参阅 OpenTelemetry：资源。
instrumentation_scope	不含重复字段的 record 此字段用于标识正在收集遥测数据的指定 resource 的库或应用组件。span 表示在资源内通过相应范围（即通过库或组件）的特定操作。 例如，假设应用“结账-service”已部署到 Cloud Run，这意味着 resource 是一个特定的 Cloud Run 实例。另假设该资源有多个检测范围，例如“request-authorization-library”和“payment-processor-library”。 客户端 span（例如“WritePaymentInfoToStripe”）可能是由“payment-processor-library”报告的 span，该库位于名为“结账-service”的 Cloud Run 服务中。 此字段包含以下子字段： 字段 说明 name string version string attributes JSON type 每个属性都是一个键值对。 可供您使用的属性取决于您的轨迹数据。属性的结构遵循 OpenTelemetry 标准。如需了解详情，请参阅 OpenTelemetry：属性。 dropped_attributes_count integer 已舍弃的属性数量。 属性可能会因键过长或属性过多而被舍弃。如果此值为零，则表示未舍弃任何属性。 此值可能由客户端插桩或应用设置。该值可由服务器递增。 如需了解详情，请参阅 OpenTelemetry：插桩范围。
resource_schema_link	string 这些字段必须是字符串格式的网址。 这些字段包含一个网址，该网址会返回资源的架构文件。 架构文件和数据的格式由 OpenTelemetry 定义。如需了解详情，请参阅 OpenTelemetry：架构。 只有在使用 Telemetry API 时才能设置这些字段。 该 API 不会验证数据是否符合声明的架构。
scope_schema_link	string 这些字段必须是字符串格式的网址。 这些字段包含一个网址，该网址会返回相应范围的架构文件。 架构文件和数据的格式由 OpenTelemetry 定义。如需了解详情，请参阅 OpenTelemetry：架构。 只有在使用 Telemetry API 时才能设置这些字段。 该 API 不会验证数据是否符合声明的架构。
apphub	不含重复字段的 record 当跟踪记录 span 由 App Hub 应用生成时，如果这些应用在受支持的基础设施上运行或已插桩，则可以使用应用特有的标签。 如需详细了解应用监控以及这些标签何时可用，请参阅应用监控概览。 此字段包含 application、service 和 workload 子字段。 应用子领域 说明 container string location string id string 服务/工作负载 子字段 说明 id string environment_type string criticality_type string