收集 OpenTelemetry 协议 (OTLP) 指标和跟踪记录

本文档介绍如何使用 Ops Agent 和 OpenTelemetry 协议 (OTLP) 接收器从使用 OpenTelemetry 插桩且在 Compute Engine 上运行的应用中收集用户定义的指标和跟踪记录。

本文档的结构如下：

• 介绍 OTLP 接收器的应用场景的概览。
• 使用 OTLP 接收器的前提条件。
• 配置代理以使用 OTLP 接收器。
• 使用接收器收集指标。本部分介绍如何在 Cloud Monitoring 中查询 OpenTelemetry 指标。
• 使用接收器收集跟踪记录。本部分介绍如何授权服务账号向 Cloud Trace 写入数据。

OTLP 接收器的使用概览

使用 Ops Agent OTLP 接收器，您可以执行以下操作：

• 使用 OpenTelemetry 的某一语言特定 SDK 对您的应用进行插桩处理。如需了解支持的语言，请参阅 OpenTelemetry 插桩。OpenTelemetry SDK 和 Ops Agent 的组合可为您执行以下操作：
  • 从您的应用收集 OTLP 指标，然后将这些指标发送到 Cloud Monitoring 进行分析。
  • 从您的应用收集 OTLP span（跟踪记录数据），然后将这些 span 发送到 Cloud Trace 进行分析。
• 从内置 OTLP 支持的第三方应用或具有此类支持的插件（如 Nginx）收集跟踪记录。Ops Agent 中的 OTLP 接收器可以收集这些跟踪记录。如需查看示例，请参阅 OpenTelemetry nginx 模块。
• 使用 OpenTelemetry 自定义插桩。
• 使用 OpenTelemetry 自动插桩。

您可以使用接收器来收集指标和/或跟踪记录。Ops Agent 收集指标后，您可以使用 Cloud Monitoring 的功能（包括图表、信息中心和提醒政策）来监控指标。如果您的应用还会发送跟踪数据，您可以使用 Cloud Trace 来分析这些数据。

优势

在 Ops Agent 的 OTLP 插件推出之前，用于对应用进行插桩以收集用户定义的指标和跟踪记录的主要方法包括：

• 使用实现 Monitoring API 或 Trace API 的客户端库。
• 使用旧版 OpenCensus 库。

与这些方法相比，将 OpenTelemetry 与 OTLP 接收器搭配使用具有多项优势，包括：

• OpenTelemetry 取代了 OpenCensus。OpenCensus 项目正在归档。如需了解详情，请参阅“什么是 OpenTelemetry？”。
• 注入在代理级别进行控制，因此如果代理配置更改，您无需重新部署应用。
• 您的应用无需设置 Google Cloud 凭据；全部授权都在代理级层处理。
• 您的应用代码不包含特定于 Google Cloud 的监控或跟踪代码。您不必直接使用 Monitoring API 或 Trace API。
• 您的应用会将数据推送到 Ops Agent，如果您的应用发生崩溃，Ops Agent 收集的任何数据都不会丢失。

限制

Ops Agent 接收器公开的 OTLP 监听器支持 gRPC 传输。不支持主要用于 JavaScript 客户端的 HTTP。如需详细了解 OpenTelemetry 协议，请参阅协议详细信息。

OTLP 接收器不会收集日志。您可以使用 Ops Agent 和其他接收器收集日志，也可以在 OTLP span 中包含日志信息，但 OTLP 接收器不支持直接收集日志。如需了解如何使用 Ops Agent 收集日志，请参阅日志记录配置。

前提条件

如需使用 OTLP 接收器和 Ops Agent 收集 OTLP 指标和跟踪记录，您必须安装 Ops Agent 2.37.0 版或更高版本。

本文档假定您已经有一个使用 OpenTelemetry SDK 编写的基于 OpenTelemetry 的应用。本文档未介绍如何使用 OpenTelemetry SDK。如需了解 SDK 和支持的语言，请参阅 OpenTelemetry 插桩。

配置 Ops Agent

如需将 Ops Agent 配置为使用 OTLP 接收器，请执行以下操作：

1. 修改 Ops Agent 的用户配置文件，以包含 OTLP 接收器。
2. 重启 Ops Agent。

以下部分介绍了各个步骤。

修改 Ops Agent 用户配置文件

将 OTLP 接收器的配置元素添加到 Ops Agent 的用户配置文件：

• 对于 Linux：/etc/google-cloud-ops-agent/config.yaml
• 对于 Windows：C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

如需了解如何配置代理的一般信息，请参阅配置模型。

OTLP 接收器引入了 Ops Agent 的 combined 配置部分。使用接收器时，您需要为指标和跟踪记录配置服务，即使您没有同时使用这两者。

以下部分介绍了 OTLP 接收器的配置步骤。

添加 combined 接收器部分

请将 OTLP 指标和跟踪记录的接收器放在 combined 部分中。combined 部分不允许添加任何处理器或服务。您不得配置任何其他与 combined 部分中的接收器同名的接收器。以下示例使用 otlp 作为接收器的名称。

OTLP 的最低 combined 配置如下所示：

combined:
  receivers:
    otlp:
      type: otlp

otlp 接收器具有以下配置选项：

• type：必填。必须为 otlp
• grpc_endpoint：可选。OTLP 接收器监听的 gRPC 端点。默认值为 0.0.0.0:4317。

• metrics_mode：可选。默认为 googlemanagedprometheus，这意味着接收器使用 Managed Service for Prometheus 也会使用的 Prometheus API 将 OTLP 指标作为 Prometheus 格式的指标发送。

  如需改为使用 Monitoring API 将指标作为 Cloud Monitoring 自定义指标发送，请将 metrics_mode 选项设置为值 googlecloudmonitoring。

  您的选择会影响指标的注入方式以及计费方式。如需详细了解指标格式，请参阅 OTLP 指标的注入格式。

将 OTLP 流水线添加到您的服务

OTLP 接收器可以收集指标和跟踪记录，因此您必须为指标和跟踪记录定义服务。如果您不收集指标或轨迹，可以创建空服务。如果您已有包含其他流水线的服务，则可以向这些服务添加 OTLP 流水线。

下面展示了流水线中包含 OTLP 接收器的 metrics 和 traces 服务：

combined:
  receivers:
    otlp:
      type: otlp
metrics:
  service:
    pipelines:
      otlp:
        receivers: [otlp]
traces:
  service:
    pipelines:
      otlp:
        receivers: [otlp]

如果您不想使用 metrics 或 traces 服务收集 OTLP 数据，请将 OTLP 接收器从服务的流水线中移除。该服务必须存在，即使没有任何流水线也是如此。如果您的应用发送指定类型的数据，并且不存在包含接收器的相应流水线，则 Ops Agent 会舍弃该数据。

重启 Ops Agent

如需应用配置更改，您必须重启 Ops Agent。

收集 OTLP 指标

当您使用 OTLP 接收器从 OpenTelemetry 应用收集指标时，接收器的主要配置是您要用于注入指标的 API。

您可以通过更改 otlp 接收器配置中的 metrics_mode 选项或使用默认值来进行此选择。该选择会影响 OTLP 指标注入到 Cloud Monitoring 的方式以及该数据用于结算的方式。

metrics_mode 选择不会影响您在 Monitoring 中创建图表、信息中心和提醒政策的能力。

• 如需了解如何创建图表和信息中心，请参阅信息中心和图表概览。
• 如需了解提醒政策，请参阅提醒概览。

以下部分介绍了指标模式使用的格式差异，以及如何查询注入的数据以便在 Monitoring 中使用。

OTLP 指标的注入格式

OTLP 接收器提供 metrics_mode 选项，该选项指定用于注入指标数据的 API。默认情况下，接收器使用 Prometheus API；metrics_mode 选项的默认值为 googlemanagedprometheus。系统会使用 Managed Service for Prometheus 所使用的 API 来注入指标。

您可以改为将接收器配置为将指标数据发送到 Cloud Monitoring API。如需将数据发送到 Monitoring API，请将 metrics_mode 选项的值设置为 googlecloudmonitoring，如以下示例所示：

combined:
  receivers:
    otlp:
      type: otlp
      metrics_mode: googlecloudmonitoring

您使用的注入格式决定了 OTLP 指标如何映射到 Cloud Monitoring。您可以在 Monitoring 中为任一指标格式的指标创建图表、信息中心和提醒政策，但您在查询中以不同方式引用指标。

注入格式还决定了数据注入所用的价格模式。

以下部分介绍了价格、Prometheus API 注入的指标与 Monitoring API 注入的相同指标之间的结构差异，以及如何在查询中引用这些指标。

价格和配额

您使用的注入格式决定了 OTLP 指标的计费方式：

• Prometheus API：当您使用 Prometheus API 注入应用的指标时，数据会按照基于样本的价格收费，就像指标是使用 Managed Service for Prometheus 注入的一样。

  • 如需了解当前价格，请参阅 Cloud Monitoring 价格摘要。
  • 如需详细了解如何计算样本数量和估算费用，请参阅基于样本注入数量的价格示例。

• Monitoring API：当您使用 Monitoring API 注入应用的指标时，数据将按基于量的价格计费，就像来自与 Ops Agent 的其他集成的数据一样。

  • 如需了解当前价格，请参阅 Cloud Monitoring 价格摘要。
  • 如需详细了解注入量和估算费用，请参阅基于注入的字节数的价格示例。

使用 OTLP 接收器注入的指标在注入到 Cloud Monitoring 时被视为“自定义”指标类型，并且受自定义指标的配额和限制的约束。

指标结构

Cloud Monitoring 使用称为指标描述符的架构来描述指标数据的格式。指标描述符包含指标的名称、指标值的数据类型、每个值与之前值的关系，以及与这些值关联的任何标签。如果您使用 Prometheus API 将 OTLP 接收器配置为注入指标，则创建的指标描述符与使用 Monitoring API 时创建的指标描述符不同。

Prometheus API：当您使用 Prometheus API 注入应用的指标时，每个指标都会使用标准 OpenTelemetry-Prometheus 转换进行转换并映射到 Cloud Monitoring 受监控的资源类型。

• 转换包括以下更改：
  • OTLP 指标名称具有前缀 prometheus.googleapis.com/。
  • OTLP 指标名称中的任何非字母数字字符（如句点 [.]）都将替换为下划线 (_)。
  • OTLP 指标名称以指示指标类型的字符串为后缀，例如 /gauge 或 /counter。
• 以下标签（填充了 OTLP 资源中的值）会添加到指标中：
  • instance_name：host.name 资源属性的值。
  • machine_type：host.type 资源属性的值。

• 随指标测量结果记录的受监控的资源为通用 prometheus_target 类型。生成的 Prometheus 时序包括 prometheus_target 资源中的以下标签，并填充了 OTLP 资源中的值：

  • location：cloud.availability_zone 资源属性的值。
  • namespace：host.id 资源属性的值。

  prometheus_target 资源类型还包含以下标签：

  • project_id：Ops Agent 在其中运行的 Google Cloud 项目的标识符，例如 my-project。
  • cluster：当 Ops Agent 收集指标时，值始终为 __gce__。

如果传入的 OTLP 数据缺少用于标签值的资源属性，则这些值将来自运行 Ops Agent 的虚拟机的相关信息。此行为意味着没有这些资源属性的 OTLP 数据与 Ops Agent Prometheus 接收器收集的数据具有相同的标签。

Monitoring API：当您使用 Monitoring API 注入应用的指标时，每个指标的处理方式如下：

• OTLP 指标名称具有前缀 workload.googleapis.com/（除非 OTLP 指标名称已包含此字符串或其他有效的指标网域，例如 custom.googleapis.com）。我们建议使用“workload”网域。
• 随指标测量结果记录的受监控的资源为 Compute Engine 虚拟机类型 gce_instance。

以下示例展示了一对 OpenTelemetry 指标的指标描述符。这些指标由使用 Go OpenTelemetry 指标库的应用创建。Prometheus API 标签页会显示 OTLP 接收器使用默认 Prometheus 指标模式时创建的指标描述符。Monitoring API 标签页会显示 OTLP 接收器使用 googlecloudmonitoring 指标模式时创建的指标描述符。

创建指标的应用不会发生任何变化；唯一的变化是 OTLP 接收器使用的指标模式。

应用会创建一个 OTLP 衡量指标 otlp.test.gauge，用于记录 64 位浮点值。以下标签页显示了每个注入 API 创建的指标描述符：

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_gauge/gauge",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_gauge/gauge",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.gauge",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.gauge",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

应用会创建一个 OTLP 计数器指标 otlp.test.cumulative，用于记录不断增加的 64 位浮点值。以下标签页显示了每个注入 API 创建的指标描述符：

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_cumulative/counter",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_cumulative/counter",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.cumulative",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.cumulative",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

下表总结了用于注入 OTLP 指标的 API 施加的一些格式差异：

注入格式和查询

OTLP 接收器中使用的指标模式会影响您在构建图表、信息中心和提醒政策时在 Cloud Monitoring 中查询生成的指标的方式。

在 Cloud Monitoring 中配置图表、信息中心或提醒政策时，配置中会包含一个查询，用于查询图表、信息中心或提醒政策所依据的数据。

Cloud Monitoring 支持使用以下工具来查询指标数据：

• 内置于 Metrics Explorer、信息中心构建器界面和提醒政策配置界面等工具中的基于查询构建器的界面。
• Monitoring Query Language (MQL)：特定于 Cloud Monitoring 的文本查询语言。
• Prometheus 查询语言 (PromQL)：开源 Prometheus 使用的基于文本的查询语言。

如需了解如何使用这些工具查询 OTLP 指标，请参阅以下内容：

• 查询使用 Prometheus API 注入的 OTLP 指标
• 查询使用 Monitoring API 注入的 OTLP 指标

查询使用 Prometheus API 注入的 OTLP 指标

本部分介绍如何查询使用 Prometheus API 注入的 OTLP 指标（这是 OTLP 接收器的默认指标模式）。

这些查询基于指标结构中所述的 OTLP 指标：

• otlp.test.gauge：记录 64 位浮点值的 OTLP 衡量指标。
• otlp.test.cumlative：记录不断增加的 64 位浮点值的 OTLP 计数器指标。

这些指标使用以下指标类型注入到 Cloud Monitoring 中，充当名称：

• prometheus.googleapis.com/otlp_test_gauge/gauge
• prometheus.googleapis.com/otlp_test_cumulative/counter

使用 Prometheus API 注入的指标是针对受监控的资源类型 prometheus_target 编写的。

该标签页显示了使用 Google Cloud 控制台查询指标时的基本查询。这些示例使用 Metrics Explorer，但信息中心和提醒政策的原则相同。

查询使用 Monitoring API 注入的 OTLP 指标

本部分介绍如何查询使用 Monitoring API 注入的 OTLP 指标。您可以通过将 OTLP 接收器的 metrics_mode 字段设置为值 googlecloudmonitoring 来选择 Cloud Monitoring API。

这些查询基于指标结构中所述的 OTLP 指标：

• otlp.test.gauge：记录 64 位浮点值的 OTLP 衡量指标。
• otlp.test.cumlative：记录不断增加的 64 位浮点值的 OTLP 计数器指标。

这些指标使用以下指标类型注入到 Cloud Monitoring 中，充当名称：

• workload.googleapis.com/otlp.test.gauge
• workload.googleapis.com/otlp.test.cumulative

使用 Monitoring API 注入的指标是针对受监控的资源类型 gce_instance 编写的。

该标签页显示了使用 Google Cloud 控制台查询指标时的基本查询。这些示例使用 Metrics Explorer，但信息中心和提醒政策的原则相同。

在 Cloud Monitoring 中查看指标使用情况和诊断信息

Cloud Monitoring 指标管理页面提供的信息可帮助您控制在收费指标上支出的金额，而不会影响可观测性。指标管理页面报告以下信息：

• 针对指标网域中基于字节和基于样本的结算以及各个指标的注入量。
• 有关标签和指标基数的数据。
• 每个指标的读取次数。
• 指标在提醒政策和自定义信息中心内的使用。
• 指标写入错误率。

您还可以使用指标管理来排除不需要的指标，从而降低提取这些指标的费用。

如需查看指标管理页面，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 query_stats 指标管理页面：

   进入指标管理

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 在工具栏中，选择时间窗口。默认情况下，指标管理页面会显示有关前一天收集的指标的信息。

如需详细了解指标管理页面，请参阅查看和管理指标使用情况。

收集 OTLP 跟踪记录

如果您已将 Ops Agent 配置为收集跟踪记录，但在运行应用时未在 Cloud Trace 中获得任何跟踪记录，则可能需要向代理使用的 Compute Engine 服务账号授予其他角色。默认情况下，服务账号会获得写入指标和日志所需的角色，但无法写入跟踪记录。

以下部分介绍了如何为服务账号授予必要的 Cloud Trace 授权。

确定授予服务账号的角色

如需查看向服务账号授予的角色，请运行以下 gcloud projects get-iam-policy 命令：

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

您可能会看到如下所示的输出：

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

如果输出包含 roles/cloudtrace.agent 或 roles/cloudtrace.admin，则表示服务账号拥有足够的权限来写入跟踪记录。如需向服务账号授予其中一个角色，请参阅以下部分。

为服务账号授予 Cloud Trace 角色

对于服务账号，通常适合使用 Cloud Trace Agent 角色 roles/cloudtrace.agent。如需向服务账号授予此角色，请运行以下 gcloud projects add-iam-policy-binding 命令：

gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudtrace.agent"

然后，您可以运行 gcloud projects get-iam-policy 命令来验证更改是否已完成：

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

输出现在包含 roles/cloudtrace.agent：

ROLE
roles/cloudtrace.agent
roles/logging.logWriter
roles/monitoring.metricWriter

如需详细了解如何管理 IAM 角色，请参阅管理对项目、文件夹和组织的访问权限。

授权 Ops Agent 使用的服务账号向 Cloud Trace 写入数据后，当您运行基于 OpenTelemetry 的应用时，跟踪记录会显示在 Cloud Trace 中：

停用 OTLP 接收器

如果您要使用 Ops Agent 同时收集 OTLP 指标和跟踪记录，并且想要停用指标或跟踪记录收集功能（但不能同时停用），请执行以下操作：

1. 对用户配置文件 config.yaml 进行以下某项更改，以停用指标或跟踪记录收集功能：

   • 从 metrics 服务中移除 otlp 流水线。
   • 从 traces 服务中移除 otlp 流水线。

2. 重启 Ops Agent。

如需停用 Ops Agent 收集 OTLP 指标和跟踪记录的功能，请执行以下操作：

1. 从用户配置文件中移除 OTLP 配置：

   • 删除整个 combined 部分，其中包括 otlp 接收器。
   • 从 metrics 服务中移除 otlp 流水线。
   • 删除整个 traces 服务。

2. 重启 Ops Agent。

后续步骤

注入应用指标和跟踪记录后，您可以使用 Google Cloud 控制台来监控和分析数据。

• 如需了解信息中心以及您可以创建的图表类型，请参阅信息中心和图表。
• 如需了解提醒政策，请参阅使用提醒政策。
• 如需了解如何分析跟踪记录数据，请参阅查找和探索跟踪记录。