v1.metrics 概览

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

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

Cloud Monitoring 中的 OTLP 指标

当使用 OpenTelemetry 收集器和 otlphttp 导出器将指标注入到 Cloud Monitoring 中，或者使用 OpenTelemetry SDK 直接发送指标时，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 值最常见的后果是，您最终会遇到只能通过删除指标来解决的冲突。

Prometheus 指标映射

指标类型对应关系如下：

  • OTLP 衡量指标会映射到 Cloud Monitoring 衡量指标。
  • OTLP Sum 映射如下：
    • 当 is_monotonic 设置为 false 时，Cloud Monitoring gauge。
    • 当 aggregation_temporality 设置为 AGGREGATION_TEMPORALITY_CUMULATIVE 时，向 Cloud Monitoring 报告累积。
    • 当 aggregation_temporality 设置为 AGGREGATION_TEMPORALITY_DELTA 时，到 Cloud Monitoring 的 delta。
  • 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  
直方图（累计） 累计 具有显式分桶的分布 /histogram  
指数直方图（累计） 累计 具有指数分桶的分布 /histogram  
直方图（增量） DELTA 具有显式分桶的分布 /histogram:delta  
指数直方图 (DELTA) DELTA 具有指数分桶的分布 /histogram:delta  
摘要
（总和、数量、分位数）

  
累计
累计
测量
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 不会设置这些标签。

在何处查看注入的数据

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