轨迹数据的存储架构

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

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

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

Span 存储格式

字段	说明
trace_id	string 跟踪记录的全局唯一标识符。 trace. 此标识符是一个 128 位的数值，格式为 16 字节的 十六进制字符串。例如， 382d4f4c6b7bb2f4a972559d9085001d。 如需详细了解此标识符，请参阅 W3C trace-id。 零值无效。 可视化和分析 工具使用 trace_id 来标识与跟踪记录关联的 span。因此， 每个端到端操作都必须具有唯一标识符。请勿 重复使用跟踪记录标识符。
span_id	string 必需。span 的标识符。 . 在跟踪记录中必须是唯一的。 此标识符是一个 64 位的数值 格式为 8 字节的十六进制字符串。 例如，9046a5b9f7c12500。 零值无效。
trace_state	string 此字段对应于 tracestate 标头， 由 W3C 跟踪记录上下文定义。 此标头包含在 请求中包含的配置信息，当应用程序进行插桩以收集跟踪记录数据时。 例如，应用可以指定 概率抽样 设置，也可以包含供应商特定的内容。 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 必需。span 的开始时间，精确到纳秒。
start_time_unix_nano	integer 根据 UNIX 纪元，以纳秒为单位的开始时间。
end_time	Timestamp 必需。span 的结束时间，精确到纳秒。
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 Status 枚举： 值 OpenTelemetry 枚举 说明 0 UNSET 成功完成操作。 1 OK 操作被人为标记为无错误。 2 ERROR 操作已完成，但有错误。例如，如果客户端 span 的状态为 400 (BAD REQUEST)，则此字段设置为 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”（位于名为“结账-service”的 Cloud Run 服务内）报告的 span。 此字段包含以下子字段： 字段 说明 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