v1.metrics 概览

本文档介绍了使用遥测 (OTLP) API 发送到 Google Cloud 项目的指标数据如何映射到 Cloud Monitoring 结构。此 API 实现了 OpenTelemetry Line Protocol。当您使用 otlphttp 导出器和 OpenTelemetry 收集器对应用进行插桩时，或者当您使用 OpenTelemetry SDK 时，可以将数据发送到此 API。

OpenTelemetry 是一个受 Google Cloud支持的开源项目，配备 Google Cloud工程师来确保支持注入和直观呈现遥测数据。

最佳做法

在对应用进行插桩处理以将跟踪记录数据发送到Google Cloud 项目时，我们建议您使用将 OTLP 格式的数据写入收集器的导出器，收集器随后会将跟踪记录数据发送到 Telemetry API。在收集器中，仅指定根网址：

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry 会检测数据类型，并根据需要自动附加 /v1/traces、/v1/metrics 或 /v1/logs。如需了解详情，请参阅 OTLP/HTTP 请求。

如需查看将跟踪记录或指标数据导出到 Telemetry API 的示例，请参阅以下文档：

• 基于收集器的插桩示例概览。
• OTLP 指标注入概览。

如果无法使用收集器，您可以使用包含进程内 OTLP 导出器的 OpenTelemetry 库，以将遥测数据发送到 Telemetry API。如需了解如何直接导出轨迹数据，请参阅从 Cloud Trace 导出器迁移到 OTLP 端点。

身份验证

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

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

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

• 配置配额项目。如需了解详情，请参阅设置配额项目。
• 向应用使用的用户或服务账号授予相应配额项目的 Service Usage Consumer 角色 (roles/serviceusage.serviceUsageConsumer)。

• 为应用所使用的用户或服务账号授予项目中的以下角色：

  • Logs Writer (roles/logging.logWriter)
  • Monitoring Metric Writer (roles/monitoring.metricWriter)
  • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)

Cloud Monitoring 中的 OTLP 指标

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

当使用 OpenTelemetry 收集器和 otlphttp 导出器将指标注入到 Cloud Monitoring 中，或者使用 OpenTelemetry SDK 直接发送指标时，OTLP 指标会映射到 Cloud Monitoring 指标结构。本节介绍以下内容：

• OTLP 资源与 Cloud Monitoring 受监控资源之间的映射。
• OTLP 指标与 Cloud Monitoring 指标之间的映射。

受监控的资源映射

所有指标点都使用 Prometheus 映射，以 Google Cloud Managed Service for Prometheus 的格式写入。

Prometheus 映射

Prometheus 指标需要使用受监控的资源类型 prometheus_target。

prometheus_target 资源类型上的以下标签用于在 Monarch 中对数据进行架构化和高效存储。您为这些属性指定的值越精确，查询能力和可伸缩性就越好。

我们强烈建议您在为这些标签设置值时尽可能明确，不过我们已实现后备逻辑，以便在没有明确值的情况下使用。

下表按优先级顺序列出了标签的值来源：

prometheus-target 标签	使用的值（按优先级顺序）
location（必需）	location 特性 cloud.availability_zone 特性 cloud.region 特性 如果点为空，则拒绝
cluster	cluster 特性 k8s.cluster.name 特性 __gce__，如果 cloud.platform 属性为 gcp_compute_engine __run__，如果 cloud.platform 属性为 gcp_cloud_run 空字符串
namespace	namespace 特性 k8s.namespace.name 特性 service.namespace 特性 空字符串
job	job 特性 "service.namespace" + "/" + service.namespace 属性 service.name 特性 service.name 属性（如果不是 unknown_service:foo） faas.name 特性 k8s.deployment.name 特性 k8s.statefulset.name 特性 k8s.job.name 特性 k8s.cronjob.name 特性 service.name 属性（如果 unknown_service:foo） 空字符串
instance（必需）	instance 特性 service.instance.id 特性 faas.instance 特性 k8s.pod.name:k8s.container.name 特性 k8s.pod.name 属性（如果不存在容器名称） host.id 特性 如果点为空，则拒绝

指标映射

指标会转换为 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 之外的所有资源属性。

所有 OTLP INT64 指标都会转换为 Cloud Monitoring 中的 DOUBLE 值类型，即使收集器将值类型指定为 INT64 也是如此。做出此更改是因为，一旦时序进入 Monarch，您就无法更改值类型。支持 INT64 值最常见的后果是，您最终会遇到只能通过删除指标来解决的冲突。

注意： 我们预计可能会出现值类型冲突，尤其是如果您之前发送过 INT64 target_info 指标。如果您遇到冲突，从长远来看，最好的解决方案是删除 INT64 target_info 指标的指标描述符。如需从指标范围内删除此描述符，请使用此 Golang 脚本。

Prometheus 指标映射

指标类型对应关系如下：

• OTLP 衡量指标会映射到 Cloud Monitoring 衡量指标。
• OTLP Sum 映射如下：
  • 当 is_monotonic 设置为 false 时，Cloud Monitoring gauge。
  • 当 aggregation_temporality 设置为 AGGREGATION_TEMPORALITY_CUMULATIVE 时，向 Cloud Monitoring 报告累积值。
  • 当 aggregation_temporality 设置为 AGGREGATION_TEMPORALITY_DELTA 时，将 delta 导出到 Cloud Monitoring。
• OTLP 直方图会映射到 Cloud Monitoring 分布，其指标类型为累积或增量，具体取决于 aggregation_temporality 的值。
• OTLP 摘要指标会扩展为每个组成部分（count、sum 和每个 quantile）的各个时序。
  • 计数和总和指标的名称分别以 _count 或 _sum 为后缀，并以 Cloud Monitoring 累积指标的形式写入，类型为 DOUBLE。
  • 每个分位数都会成为自己的 gauge 时序（类型为 DOUBLE），并带有 quantile 标签。

下表总结了指标映射：

OTLP 点种类	监控 指标种类	监控 值类型	后缀	备注
仪表盘	仪表盘	DOUBLE	/gauge
GAUGE（metric.metadata["prometheus.type"]="unknown"）	仪表盘	DOUBLE	/unknown	Prometheus 未知项由 OpenTelemetry 收集器拆分为计数器和计量器。
SUM（单调递增，累计）	累计	DOUBLE	/counter
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown")	累计	DOUBLE	/unknown:counter	Prometheus 未知项由 OpenTelemetry 收集器拆分为计数器和计量器。
SUM（单调，DELTA）	DELTA	DOUBLE	/delta
SUM（非单调，累计）	仪表盘	DOUBLE	/gauge
SUM（非单调，DELTA）	不支持			不支持 delta-temporality UpDownCounter。
直方图（累计）	累计	具有显式分桶的分布	/histogram
指数直方图（累计）	累计	具有指数分桶的分布	/histogram
直方图（增量）	DELTA	具有显式分桶的分布	/histogram:delta
指数直方图 (DELTA)	DELTA	具有指数分桶的分布	/histogram:delta
SUMMARY （总和、数量、分位数）	累计 累计 指标	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	系统会将汇总数据点写入多个时序，一个用于计数，一个用于总和，其余用于每个计算出的分位数。分位数值指标也会生成一个 quantile 标签。

googlemanagedprometheus 出口程序与 Telemetry API 之间的区别

Telemetry API (telemetry.googleapis.com) 处理指标的方式与 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 后缀。

• 该 API 会为从指数直方图派生的分布值合成 sum_of_squared_deviation 值。googlemanagedprometheus 指标导出器不会为指数直方图设置此字段。

• 该 API 会将所有整数点值转换为 Prometheus 指标的双精度值。

• 如果 scope_version 或 scope_name 标签的值为空，则 API 不会设置这些标签。

Cloud Monitoring 和数据驻留

如需了解指标数据的存储方式，请参阅 Cloud Monitoring 的数据地区化。

在何处查看注入的数据

您可以使用 Metrics Explorer 页面查看通过 Telemetry API 注入的指标数据。如需了解如何查看指标数据并绘制图表，请参阅使用 Metrics Explorer 创建图表。