迁移到 OTLP 导出器

本文档介绍了如何修改使用现有导出器（在本例中为 googlemanagedprometheus 导出器）的 OpenTelemetry 收集器配置，以使用 otlphttp 导出器和 Telemetry (OTLP) API (telemetry.googleapis.com)。

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

启用 Telemetry API

otlphttp 指标导出器会写入 Telemetry API，因此您必须在项目中启用该 API。运行以下命令以启用 Telemetry API：

gcloud services enable telemetry.googleapis.com

授权 Kubernetes 服务账号

Kubernetes 服务账号必须有权使用 Telemetry API。以下命令会向 Kubernetes 服务账号授予必要的 Identity and Access Management (IAM) 角色。这些命令假设您使用的是适用于 GKE 的工作负载身份联合：

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

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

将 PROJECT_ID 变量替换为您的 Google Cloud 项目的 ID。

如果您的服务账号采用其他格式，则可以使用 Google Cloud Managed Service for Prometheus 文档中的命令来授权服务账号，但需进行以下更改：

  • 将服务账号名称 gmp-test-sa 替换为您的服务账号。
  • 运行命令以授予 roles/telemetry.metricsWriter 角色。

设置 PROJECT_ID 环境变量

在收集器部署中设置 PROJECT_ID 环境变量。结果如下所示：

env:
- name: PROJECT_ID
  value: PROJECT_ID

找到要替换的导出器

在配置文件中，找到导出器和使用该导出器的服务：

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

为 otlphttp exporter 添加配置

在此步骤中，您需要将 otlphttp 导出器和 metricstarttime 处理器添加到配置中。此额外的导出器会导致收集器将指标写入两次。

  • 如果您使用的是 OTLP 原生指标，则双重写入不会造成任何问题，因为这两种方法创建的指标描述符的结构不同。这是两个不同的指标。
  • 如果您使用的是 Prometheus 指标，那么在移除 googlemanagedpromethus 导出器之前，您会看到冲突。

更新后的配置如下所示：

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

对指标进行双重写入后，更新信息中心和提醒政策，以使用 otlphttp 指标导出器生成的新指标名称。otlphttp 导出器不会将指标重命名为“Prometheus 风格”，而是使用下划线替换。

移除之前导出工具的配置

更新信息中心和提醒以引用 otlphttp 导出的指标后，从配置中移除旧的导出工具（在本例中为 googlemanagedprometheus）。修改后的配置如下所示：

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

根据需要迁移信息中心和提醒政策

如果您之前仅使用 googlemanagedprometheus 导出器来导出 Prometheus 指标数据，那么在改用 OTLP 导出器后，您现有的信息中心和提醒政策将继续正常运行。

不过，如果您使用 googlemanagedprometheus 指标导出器收集并发送最初使用 OTLP 发出的数据，或者抓取包含 UTF-8 字符的 Prometheus 指标，则需要更新您的信息中心和提醒，以使用 UTF-8 指标名称。

这是因为使用 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 指标名称的开源资源。