v1.metrics 概览

本文档介绍了如何将使用 Telemetry (OTLP) API 发送到您的 Google Cloud 项目 的指标数据映射到 Cloud Monitoring 结构。此 API 实现了 OpenTelemetry OTLP 协议。当您使用 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 导出器的 OpenTelemetry 库将遥测数据发送到 Telemetry API。 如需了解如何直接导出跟踪记录数据，请参阅 Cloud Trace 导出器到 OTLP 端点。

身份验证

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

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

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 指标需要使用受监控的资源类型 prometheus_target。

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

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

下表显示了标签的值来源（按优先级顺序）：

prometheus-target 标签 使用的值（按优先级顺序）
location（必需）
  • location 属性
  • cloud.availability_zone 属性
  • cloud.region 属性
  • 如果为空，则拒绝该点
cluster
  • cluster 属性
  • k8s.cluster.name 属性
  • 如果 cloud.platform 属性为 gcp_compute_engine，则为 __gce__
  • 如果 cloud.platform 属性为 gcp_cloud_run，则为 __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 Gauge 映射到 Cloud Monitoring gauge。
  • OTLP 总和映射如下：
    • 当 is_monotonic 设置为 false 时，映射到 Cloud Monitoring 衡量指标 。
    • 映射到 Cloud Monitoring 累计指标 当 aggregation_temporality 设置为 AGGREGATION_TEMPORALITY_CUMULATIVE时。
    • 映射到 Cloud Monitoring 增量指标 当 aggregation_temporality 设置为 AGGREGATION_TEMPORALITY_DELTA时。
  • OTLP 直方图映射到 Cloud Monitoring 分布，指标种类为 累计或增量，具体取决于 aggregation_temporality的值。
  • OTLP 摘要指标会针对每个组件展开为单独的时序：count、sum 和每个 quantile。

下表总结了指标映射：

OTLP 点种类 Monitoring 指标种类 Monitoring 值类型 后缀 备注
GAUGE GAUGE DOUBLE /gauge  
仪表盘 (metric.metadata["prometheus.type"]="unknown") GAUGE DOUBLE /unknown OpenTelemetry 收集器会将 Prometheus Unknowns 拆分为计数器和衡量指标。
SUM（monotonic，CUMULATIVE） CUMULATIVE DOUBLE /counter  
SUM（monotonic，CUMULATIVE， metric.metadata["prometheus.type"]="unknown"） CUMULATIVE DOUBLE /unknown:counter OpenTelemetry 收集器会将 Prometheus Unknowns 拆分为计数器和衡量指标。
SUM（monotonic，DELTA） DELTA DOUBLE /delta  
SUM（non-monotonic，CUMULATIVE） GAUGE DOUBLE /gauge  
SUM（non-monotonic，DELTA） 不支持 不支持增量时态 UpDownCounters。
HISTOGRAM (CUMULATIVE) CUMULATIVE 具有 显式分桶的 DISTRIBUTION /histogram  
EXPONENTIAL HISTOGRAM (CUMULATIVE) CUMULATIVE 具有 指数分桶的 DISTRIBUTION /histogram  
HISTOGRAM (DELTA) DELTA 具有 显式分桶的 DISTRIBUTION /histogram:delta  
EXPONENTIAL HISTOGRAM (DELTA) DELTA 具有 指数分桶的 DISTRIBUTION /histogram:delta  
SUMMARY
(总和、
计数、
分位数)
CUMULATIVE
CUMULATIVE
仪表盘
DOUBLE
DOUBLE
DOUBLE		  
_sum/summary:counter
_count/summary
/summary		 摘要数据点以多个时序的形式写入，一个用于 计数，一个用于总和，一个用于每个计算的分位数。还会生成带有 quantile 标签的分位数指标。

googlemanagedprometheus 导出器与 Telemetry API 之间的差异

Telemetry API (telemetry.googleapis.com) 处理指标的方式与 googlemanagedprometheus 导出器不同 ：

  • Telemetry API 允许在指标名称中使用英文句点 (.) 和斜线 (/) 字符 。googlemanagedprometheus 导出器会将所有此类字符实例转换为下划线 (_) 字符。例如，OTLP 导出器会按原样导出名为 prometheus.googleapis.com/foo.bar/gauge 的 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 创建图表。