OTLP 注入概览

本文档介绍了如何使用实现了 OpenTelemetry 协议的 Telemetry (OTLP) API (telemetry.googleapis.com)。借助 Telemetry API，您可以将 OTLP 格式的日志、指标和跟踪记录数据注入到 Google Cloud Observability 中：

  • OTLP 日志记录会转换为日志条目，然后进行路由和存储。如需了解转换过程，请参阅本文档的 OTLP 日志提取部分。
  • 指标数据会注入到 Cloud Monitoring 中。如需了解指标和标签名称以及注入限制，请参阅本文档的 OTLP 指标注入部分。
  • 跟踪数据以通常与 OTLP 一致的格式存储。如需了解详情，请参阅 OTLP 轨迹注入。

您可以从使用 SDK 的应用向 Telemetry API 发送遥测数据，也可以从 OpenTelemetry 收集器导出遥测数据。

如果您使用的是 Google Kubernetes Engine，则可以使用 GKE 的受管 OpenTelemetry，而无需手动部署和配置使用 Telemetry API 的 OpenTelemetry 收集器。

协议支持

OTLP 端点支持所有 OTLP 传输和序列化协议，包括 http/protobuf、http/json 和 grpc。如果直接从使用 SDK 的应用导出数据，我们建议使用 gRPC OTLP 导出器，而不是 HTTP 导出器，因为大多数 SDK 导出器不支持动态令牌刷新。

身份验证

您必须使用必要的凭据配置导出器，才能将数据发送到您的 Google Cloud 项目。例如，当您使用收集器时，通常会使用 googleclientauth 扩展程序通过 Google 凭据进行身份验证。

如需查看使用直接导出轨迹数据时的身份验证示例，请参阅配置身份验证。 此示例展示了如何使用 Google Cloud 应用默认凭证 (ADC) 配置导出器，以及如何向应用添加特定于语言的 Google Auth 库。

如需使用 Telemetry API 将遥测数据发送到您的 Google Cloud 项目，您还必须执行以下操作：

  • 配置配额项目。如需了解详情，请参阅设置配额项目。

  • 向用户或应用使用的服务账号授予以下 Identity and Access Management (IAM) 角色：

    • 配额项目的 Service Usage Consumer 角色 (roles/serviceusage.serviceUsageConsumer)。
    • 项目的 Cloud Telemetry Writer 角色 (roles/telemetry.writer)。此角色可让您的应用写入日志、指标和跟踪记录数据。

OTLP 提取

本部分介绍了如何将日志、指标和跟踪记录数据从 OTLP 转换为 Google Cloud Observability 数据结构。

日志数据注入

使用 Telemetry API 注入 OTLP 格式的日志时，您的日志数据会转换为 Cloud Logging 日志条目。采用 JSON 格式的传入 OTLP 日志请求具有以下一般结构：

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
]

每个 logRecords 数组中的每个项都会成为单个 Cloud Logging 日志条目。resource 属性决定了生成的 LogEntry 中的受监控的资源。如需详细了解注入 OTLP 格式的日志需要哪些属性，请参阅 OTLP 属性到资源类型的映射。

为了支持提取 OTLP 格式的日志，Cloud Logging LogEntry 结构包含一个额外的字段 otel。由于 OTLP 和 Cloud Logging 数据模型在结构上有所不同，因此 otel 字段会保留传入 OTLP 请求中的资源、范围和实体元数据的副本。

例如，如果您向 Telemetry API 发送如下所示的 OTLP resourceLogs 载荷，则每个生成的日志条目都包含一个 resource 字段（用于受监控的资源）和一个 otel 字段，如其他标签页所示：

resourceLogs 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

由于 Cloud Logging 日志条目是自包含的，并且不链接到外部资源架构，因此所有 OTLP 资源、范围和实体元数据都会复制到每个日志条目中。

指标数据注入

只有在使用 OpenTelemetry 收集器版本 0.140.0 或更高版本时，OTLP for Prometheus 指标才能正常运行。

当使用 OpenTelemetry 收集器和 otlphttp 导出器将指标注入到 Cloud Monitoring 中时，或者使用 OpenTelemetry SDK 直接发送指标时，OTLP 指标会映射到 Cloud Monitoring 指标结构。如需了解这些映射，请参阅以下内容：

Google Cloud Observability 会将指标转换为 Prometheus 时间序列格式。指标名称不得包含网域，或者必须包含网域 prometheus.googleapis.com。转换后，指标名称会包含 prometheus.googleapis.com 前缀，以及基于 OTLP 点类型的其他后缀。生成的 Cloud Monitoring 指标具有以下结构：

prometheus.googleapis.com/{metric_name}/{suffix}

此外，对于每个唯一的 OpenTelemetry 资源，转换会添加一个 target_info 指标，其中包含除 service.name、service.instance.id 和 service.namespace 之外的所有资源属性。

由于 Cloud Monitoring 中的指标名称和标签键不支持完整的 UTF-8，因此可能会拒绝指标数据：

  • 不符合正则表达式 [a-zA-Z][a-zA-Z0-9_:./-]* 的指标名称会被拒绝。指标名称中允许使用的特殊字符仅限于 _:./- 中的字符。
  • 包含不符合正则表达式 [a-zA-Z_][a-zA-Z0-9_.]* 的属性（即标签键）的数据点会被拒绝。标签键中允许使用的特殊字符仅限于 _. 中的字符。标签值中允许使用所有特殊字符。

为避免因这些原因导致指标被拒绝，请使用 replace_pattern 函数转换指标名称和属性。

跟踪记录数据注入

无论您是使用 Telemetry API 还是 Cloud Trace API，传入的跟踪记录数据都会以与 OTLP 一致的格式存储。不过，我们建议您使用 Telemetry API，因为该 API 提供的提取配额高于 Cloud Trace API。

以下示例展示了应用可能会发送到您的 Google Cloud 项目的跟踪记录数据：

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

每个 scopeSpans.spans 数组中的每一项都会成为一个存储的跨度：

  • 每个 span 的 resource 字段都包含 resourceSpans.resource.attributes 数据的副本。
  • 每个 span 的 instrumentation_scope 字段都包含 scopeSpans.scope 数据的副本。
  • 每个 span 都对应于 scopeSpans.spans 数组中的一个条目。traceId、spanId 和 kind 等字段会映射到轨迹架构中名称相似的字段。

有关详情，请参阅以下文档：

结算

使用 Telemetry API 提取的日志、指标和轨迹数据的结算方式取决于遥测信号。如需了解完整信息，请参阅“结算”页面。

日志数据结算

如果您使用 Telemetry API 注入日志，则可能会因日志量发生变化而看到 Cloud Logging 存储空间和结算价值发生变化。

如果同时满足以下两个条件，则 Google Cloud 项目的存储和结算会发生最大变化：

  • resource 字段包含高基数属性或大量属性。这些资源属性决定了生成的 LogEntry 中的受监控的资源。
  • scopeLogs 字段包含 logRecords 数组中的大量项。scopeLogs.scope 字段会复制到每个单独的日志条目的 otel 字段中。

由于此资源和范围元数据会复制到每个单独的日志条目中，因此存储的日志量可能会增加。

为最大限度减少存储卷，我们建议您执行以下操作：

  • 使用 OpenTelemetry 收集器处理器（例如 transform 处理器）在导出数据之前舍弃不必要的资源或范围属性。
  • 如果您不需要在 otel 字段中保留其他元数据，请使用旧版映射选项 gcp.use_legacy_mapping，该选项可防止 otel 字段被填充。

指标数据结算

OTLP 指标的结算费用计入“Prometheus 样本注入”SKU 下，该 SKU 与 Google Cloud Managed Service for Prometheus 的指标所用的 SKU 相同。

跟踪数据结算

您用于将跟踪记录数据发送到项目的 API 不会影响该数据的费用计算方式。

查询日志、指标和跟踪记录数据

您可以使用探索器页面（Logs Explorer、Metrics Explorer 和 Trace Explorer）查询日志、指标和跟踪记录数据。您还可以使用 Observability Analytics 页面通过 SQL 分析日志和轨迹数据。

使用 Metrics Explorer 查询指标数据时，以下提示可能会有所帮助：

  • 重要提示：如果指标名称和标签键包含冒号 (:) 和下划线 (_) 以外的特殊字符，则您必须根据 PromQL 的 UTF-8 规范将它们用花括号 ({}) 和引号 (") 括起来。例如，以下查询是有效的：

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • 查询指数直方图时保留 le 标签可能会返回意外结果。预计更常见的 histogram_quantile(.99, sum by (le) (metric)) 查询将正常运行。

  • 在某些情况下（例如增量非常稀疏），增量指标可能无法正确查询。

限制和配额

Telemetry API 限制适用于所有信号类型。

以下配额和限制也适用：

  • 日志数据：适用 Cloud Logging API 配额和限制。

  • 指标数据：受 Cloud Monitoring API 配额和限制约束。 例如，指标的标签数量不能超过 200 个。

    Telemetry API 提取的指标的默认配额为每分钟 60,000 个请求。如果每个请求的批次大小上限为 200 个数据点，则此配额相当于每秒 20 万个样本的有效默认配额。您可以申请增加配额。

  • 轨迹数据：没有其他适用的配额或限制。

后续步骤