Google Cloud Observability 中的 OTLP 支持

您可以使用 Telemetry (OTLP) API 将 OTLP 格式的日志、指标和跟踪记录数据注入 Google Cloud Observability，该 API 实现了 OpenTelemetry 协议。借助此 API，您可以从 OpenTelemetry SDK 和收集器中收集与供应商无关的遥测数据，而无需使用自定义 Google Cloud 导出器。

当您使用 Telemetry API 将遥测数据发送到项目时，Google Cloud Observability 会按如下方式处理每个信号：

  • 日志数据：将 OTLP 日志记录转换为日志条目，并将其路由到存储位置。
  • 指标数据：将指标数据映射到 Cloud Monitoring 中的 Prometheus 时序。
  • 跟踪记录数据：以通常与 OTLP 一致的格式存储分布式跟踪记录。

如果您在 Google Kubernetes Engine 上运行工作负载，则可以使用适用于 GKE 的代管式 OpenTelemetry，而无需手动部署和管理 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 日志条目。传入的 OTLP 格式 JSON 日志请求具有以下常规结构：

"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 或更高版本时，适用于 Prometheus 指标的 OTLP 才能正常运行。

使用 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，因为其提供的注入配额高于 Cloud Trace API。

以下是可能从应用发送到 Google Cloud 项目的跟踪记录数据示例：

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

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

  • 每个 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 相同。

Trace 数据结算

您用于将跟踪记录数据发送到项目的 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 个点，则此配额的有效默认配额为每秒 200,000 个样本。您可以申请增加配额。

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

后续步骤