Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

将收集器迁移为使用 OTLP 导出器

Telemetry (OTLP) API 是 OpenTelemetry 协议的一种实现。对 OTLP 的支持让您能够将通用 otlphttp 和 otlp_grpc/otlp_logs 导出器添加到收集器配置中，从而避免使用特定于供应商的导出器。应用可以将日志、指标和跟踪记录数据发送到 Telemetry API。

如果您的收集器配置使用 googlecloud 导出器或 googlemanagedprometheus 导出器，则本指南适用于您：

日志数据：从 googlecloud 导出器迁移到 otlp_grpc/otlp_logs 导出器。
指标数据：从 googlemanagedprometheus 导出器迁移到 otlphttp 导出器。
轨迹数据：从 googlecloud 导出器迁移到 otlphttp 导出器。

如需迁移到 OTLP 出口，请执行以下步骤：

启用 Telemetry API
授权收集器服务账号
设置 GOOGLE_CLOUD_PROJECT 环境变量
添加 googleclientauth 扩展程序
添加 otlphttp 和 otlp_grpc/otlp_logs 导出器
添加处理器
更新服务流水线
验证配置
迁移信息中心和提醒政策
移除特定于供应商的导出器

启用 Telemetry API

OTLP 导出器会写入 Telemetry API，因此必须在项目中启用该 API。如需启用 Telemetry API，请运行以下命令：

gcloud services enable telemetry.googleapis.com

向收集器服务账号授权

收集器使用其运行环境的身份针对 Google Cloud API 进行身份验证。运行收集器的服务账号必须具有使用 Telemetry API 写入日志、指标和跟踪记录数据的权限。此外，由于 Telemetry API 是使用方 API，因此您必须明确指定 Google Cloud 通过 API 调用消耗配额的项目，并向服务账号授予消耗该项目配额所需的权限。

所需的角色

<0x

为确保运行收集器的服务账号具有发送日志、指标和跟踪记录数据所需的权限，请让管理员为您的项目中运行收集器的服务账号授予以下 IAM 角色：

Cloud Telemetry Writer (roles/telemetry.writer)
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

这些预定义角色包含发送日志、指标和轨迹数据所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您必须拥有以下权限才能发送日志、指标和跟踪记录数据：

logging.logEntries.create
monitoring.timeSeries.create
telemetry.traces.write
serviceusage.services.use

Kubernetes 服务账号

如果您使用适用于 GKE 的工作负载身份联合在 Google Kubernetes Engine (GKE) 上部署收集器，请向您的 Kubernetes 服务账号授予所需角色。

如果您的 API 配额是从与 Telemetry API 调用目标项目相同的 Google Cloud 项目中提取的，您可以使用以下命令授予所需角色。在运行命令之前，请将 PROJECT_ID 替换为您的项目 ID。不过，如果您使用单独的配额项目，请将第二个命令中的 PROJECT_ID 替换为配额项目的 ID：

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/telemetry.writer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/serviceusage.serviceUsageConsumer \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

适用于 Workload Identity Federation for GKE 的服务账号

如果您为 Workload Identity Federation for GKE 配置了服务账号，则可以使用 Google Cloud Managed Service for Prometheus 文档中的命令来授权该服务账号，但需进行以下更改：

将 gmp-test-sa 替换为您的服务账号的名称。
运行该命令以授予写入日志、指标和跟踪记录数据所需的角色。

其他服务账号

如果您在 Compute Engine 虚拟机或 GKE 外部运行收集器，请向部署所用的 Google Cloud 服务账号授予所需角色。

设置 `GOOGLE_CLOUD_PROJECT` 环境变量

在收集器部署中设置 GOOGLE_CLOUD_PROJECT 环境变量。结果类似于：

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

添加 `googleclientauth` 扩展程序

将 googleclientauth 扩展程序添加到收集器配置中。 Telemetry API 是一种消费者 API，需要您同时指定 Google Cloud 项目和配额项目。结果类似于以下内容：

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

添加 `otlphttp` 和 `otlp_grpc/otlp_logs` 导出器

使用 otlphttp 导出器将 OTLP 格式的指标和跟踪记录数据发送到您的项目，并使用 otlp_grpc/otlp_logs 导出器发送日志数据。请务必使用 googleclientauth 扩展程序配置这两个导出器。

结果类似于以下内容：

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

对于 otlp_grpc/otlp_logs 指标导出器，必须使用 host:port 格式指定 endpoint 字段。

添加处理器

本部分列出了需要添加到收集器的处理器。您可能还想使用其他处理器。例如，Google 构建的 OpenTelemetry 收集器配置通常包含 memory_limiter 处理器和一个用于转换指标数据的处理器。如需查看示例，请参阅 GKE 上的 Google 构建的 OpenTelemetry 收集器。

添加 `resource/gcp_project_id` 处理器

添加一个 resource 处理器，用于捕获有关Google Cloud 项目的信息。

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

添加 `resourcedetection` 处理器

如果您使用的是 Google Cloud，请考虑添加 resourcedetection 处理器。此处理器可以自动发现有关您架构的信息。

以下配置会查找标准的 OpenTelemetry 环境变量，然后查询 Google Cloud 元数据服务器以收集有关您基础设施的信息：

  resourcedetection:
    detectors: ["env", "gcp"]

添加 `batch` 处理器

为了更高效地将遥测数据发送到您的 Google Cloud 项目，我们建议您使用 batch 处理器。

例如，Google 构建的 OpenTelemetry 收集器对批处理器的配置如下：

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

添加 `metricstarttime` 处理器

将 metricstarttime 处理器添加到配置中。此处理器可确保累计指标同时包含开始时间和观测时间。默认情况下，Prometheus 指标仅包含当前时间。因此，如果您省略此处理器，而您的应用会生成 Prometheus 指标，则您的指标数据可能会被拒绝，或者您可能会看到数据峰值。

如果您的收集器接收 Prometheus 指标，则必须添加此处理器。

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

添加转换处理器

如需在日志数据中保留插桩来源和版本，请添加以下 transform 处理器：

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

更新服务流水线

接下来，更新收集器的流水线以使用 otlp_grpc/otlp_logs 和 otlphttp 出口。对于日志和轨迹数据，这些说明会将您当前的导出器替换为相应的 OTLP 导出器。对于指标数据，这些说明会导致双重写入。通过这种方法，您可以验证 OTLP 导出器是否正在将指标数据发送到您的 Google Cloud 项目。您还可以在关闭原始导出器的数据流之前更新图表和提醒政策。

对收集器的流水线配置进行以下更改：

将 googleclientauth 扩展名添加到 service 条目。
对于您的日志流水线，请将 googlecloud/logging 替换为 otlp_grpc/otlp_logs，然后将以下处理器添加到流水线的处理器列表中：
- resource/gcp_project_id
- transform/otlp_grpc/preserve_instrumentation_source_version
- resourcedetection（如果您添加了此处理器）
- batch
此配置会执行日志数据的单次写入。 如果您想双重写入日志数据，请将 otlp_grpc/otlp_logs exporter 添加到导出器列表中。
对于指标流水线，请将 otlphttp 导出器添加到流水线的导出器列表（与 googlemanagedprometheus 导出器一起），然后添加以下处理器：
- resource/gcp_project_id
- metricstarttime
- resourcedetection（如果您添加了此处理器）
- batch
此配置会对指标数据执行双重写入。验证指标数据流并更新图表和提醒政策后，移除 Prometheus 导出器。
对于您的轨迹流水线，请将当前导出器替换为 otlphttp 导出器，然后添加以下处理器：
- resource/gcp_project_id
- resourcedetection（如果您添加了此处理器）
- batch
此配置会执行一次性写入轨迹数据。

这些更改的结果类似于以下内容：

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

上述代码段使用 OTLP 接收器来接收日志、指标和轨迹数据。您的收集器配置可能有所不同。例如，如果您有一个写入结构化日志数据的应用，则 filelog 接收器是合适的。

验证您的配置

重启部署，然后验证 otlphttp 和 otlp_grpc/otlp_logs 导出器是否正在将数据发送到您的 Google Cloud 项目。如需验证配置，请执行以下操作：

查询日志条目，查找与写入遥测数据相关的错误。
查看 Cloud Logging API、Cloud Monitoring API 和 Telemetry API 的错误率。
使用 Metrics Explorer 查看时序。

迁移信息中心和提醒政策

按如下所示更新图表和信息中心：

如果您使用图表或提醒政策监控 Cloud Logging API 或 Cloud Monitoring API 的使用情况，请创建其他图表或提醒政策来监控 Telemetry API 的使用情况。
如果指标接收器包含 otlp 接收器，或者您的收集器抓取包含 UTF-8 字符的 Prometheus 指标，请更新图表和信息中心。otlphttp 导出器生成的指标与 googlemanagedprometheus 导出器生成的指标不同。如需了解详情，请参阅导出指标的格式差异。

如果您的收集器仅接收 Prometheus 指标数据，则无需更新图表和信息中心。
如果您的指标流水线包含 prometheus 接收器，则由 otlphttp 和 googlemanagedprometheus 导出工具生成的指标之间会发生数据流冲突。如需解决这些冲突，请移除 googlemanagedprometheus 指标导出器。

导出指标的格式差异

由于 OTLP 和 googlemanagedprometheus 指标导出器导出的指标存在以下差异，因此需要更新基于指标的图表和提醒政策：

Telemetry API 允许在指标名称中使用英文句点 (.) 和斜杠 (/) 字符。googlemanagedprometheus 导出器会将所有这些字符的实例转换为下划线 (_) 字符。例如，一个名为 prometheus.googleapis.com/foo.bar/gauge 的 OTLP 指标由 OTLP 导出器原封不动地导出，但由 googlemanagedprometheus 导出器导出为 prometheus.googleapis.com/foo_bar/gauge。

当指标被注入时，Cloud Monitoring 会根据名称创建指标描述符。由于注入途径处理句点 (.) 和斜杠 (/) 字符的方式不同，因此使用 googlemanagedprometheus 指标导出器注入的指标与使用 otlphttp 指标导出器注入的指标的指标描述符会有所不同。如果您同时使用这两种提取路径，则会有两组指标；在查询时，为了获得完整的结果，您必须手动合并 Prometheus 和 OTLP 版本的指标的结果。
如果指标具有单位，Telemetry API 不会将单位附加到指标名称，也不会将 _total 后缀附加到计数器。因此，使用 Telemetry API 导出为 prometheus.googleapis.com/foo/counter 的指标会通过 googlemanagedprometheus 导出器导出为 prometheus.googleapis.com/foo_seconds_total/counter。这种差异也适用于 _total 和 _ratio 后缀。

如需详细了解指标之间的差异，请参阅googlemanagedprometheus 指标导出器与 Telemetry API 之间的差异。

转换规则不适用于包含 UTF-8 字符的指标。因此，您必须重写信息中心和提醒政策，以使用新指标名称或使用将旧指标名称和新指标名称相结合的查询。我们不建议编写处理器规则来重新创建这些转换，以便继续写入 UTF-8 指标，就好像它们是由 googlemanagedprometheus 导出器收集的一样。这样做可以保持向后兼容性，但会牺牲向前兼容性，并且您将无法使用引用 UTF-8 指标名称的开源资源。

移除特定于供应商的导出器

验证新数据流并更新信息中心和提醒政策后，从收集器配置中移除 googlecloud/logging 和 googlemanagedprometheus 指标导出器。您可能还需要移除仅供已从配置中移除的导出器使用的处理器。

您需要同时更新导出器列表和服务流水线。

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

问题排查

本部分介绍了如何解决迁移收集器配置时可能发生的故障。

指标数据缺失或出现峰值

如果您的指标数据缺失或包含尖峰，请验证您是否已将 metricstarttime 处理器添加到收集器的配置中。如需了解详情，请参阅添加 metricstarttime 处理器。

您还可以查看收集器日志、系统日志和 Monitoring 的数据访问审核日志。例如，如果对时序的写入失败，系统会生成包含失败原因的数据访问审核日志。

有关写入时序的错误消息

当尝试将数据写入时序失败时，系统会生成错误消息。您可以根据这些消息了解写入失败的原因以及如何解决相应问题。

指示值不匹配的错误消息：
```
"One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."
```
如果您之前发送了 INT64 target_info 指标，就会发生此错误，因为 Telemetry API 将所有指标的值类型都设置为 DOUBLE。从长远来看，最佳解决方案是删除 INT64 target_info 指标的指标描述符。如需从指标范围内删除此描述符，请使用此 Golang 脚本。
指示多个来源正在写入时序数据的错误消息：
```
"One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."
```
如需解决此问题，请从收集器的配置中移除 googlemanagedprometheus 导出器。如需了解详情，请参阅移除特定于供应商的导出器。

后续步骤

基于收集器的插桩示例概览是指您可以下载和安装的示例应用。每个示例应用都包含一个完整的收集器，该收集器使用 Telemetry API 导出指标和跟踪记录数据。
在 Google Kubernetes Engine 上部署 Google 构建的 OpenTelemetry 收集器包含完整的收集器配置。