使用 Prometheus 作为您的 OpenTelemetry 后端

Prometheus 支持 OTLP(即“OpenTelemetry 协议”)通过 HTTP 摄取。

启用 OTLP 接收器

默认情况下,OTLP 接收器处于禁用状态,与远程写入接收器类似。这是因为 Prometheus 可以在没有任何身份验证的情况下工作,因此除非明确配置,否则接收传入流量是不安全的。

要启用此接收器,您需要切换 CLI 标志 --web.enable-otlp-receiver。这将使 Prometheus 在 HTTP /api/v1/otlp/v1/metrics 路径上提供 OTLP 指标接收服务。

$ prometheus --web.enable-otlp-receiver

将 OpenTelemetry 指标发送到 Prometheus 服务器

通常,您需要告知 OTLP 指标流量的来源 Prometheus 端点,以及应使用 OTLP 的 HTTP 模式(gRPC 通常是默认模式)的事实。

OpenTelemetry SDK 和仪表库通常可以通过标准环境变量进行配置。以下是将 OpenTelemetry 指标发送到本地 Prometheus 服务器所需的 OpenTelemetry 变量

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://:9090/api/v1/otlp/v1/metrics

关闭跟踪和日志

export OTEL_TRACES_EXPORTER=none
export OTEL_LOGS_EXPORTER=none

OpenTelemetry 指标的默认推送间隔为 60 秒。以下设置将使推送间隔为 15 秒

export OTEL_METRIC_EXPORT_INTERVAL=15000

如果您的仪表库未开箱即用地提供 service.nameservice.instance.id,强烈建议您设置它们。

export OTEL_SERVICE_NAME="my-example-service"
export OTEL_RESOURCE_ATTRIBUTES="service.instance.id=$(uuidgen)"

上述假设您的系统上安装了 uuidgen 命令。请确保 service.instance.id 对每个实例都是唯一的,并且每当资源属性发生变化时都会生成新的 service.instance.id建议的方式是在实例每次启动时生成新的 UUID。

配置 Prometheus

本节解释了 Prometheus 服务器的各种推荐配置方面,以启用和调整您的 OpenTelemetry 流。

请参阅我们将在下一节中使用的 Prometheus 配置示例文件

启用乱序摄取

您可能希望启用乱序摄取有多种原因。

例如,OpenTelemetry 收集器鼓励批处理,并且您可能有多个收集器副本向 Prometheus 发送数据。由于没有机制对这些样本进行排序,它们可能会出现乱序。

要启用乱序摄取,您需要用以下内容扩展 Prometheus 配置文件

storage:
  tsdb:
    out_of_order_time_window: 30m

30 分钟的乱序时间对于大多数情况来说已经足够,但请随时根据您的需求调整此值。

提升资源属性

根据经验和与社区的交流,我们发现,在所有常见的资源属性中,有些属性值得附加到您的所有 OTLP 指标上。

默认情况下,Prometheus 不会提升任何属性。如果您希望提升其中任何属性,可以在 Prometheus 配置文件的此部分进行操作。以下代码片段分享了最佳实践的属性提升集

otlp:
  # Recommended attributes to be promoted to labels.
  promote_resource_attributes:
    - service.instance.id
    - service.name
    - service.namespace
    - service.version
    - cloud.availability_zone
    - cloud.region
    - container.name
    - deployment.environment
    - deployment.environment.name
    - k8s.cluster.name
    - k8s.container.name
    - k8s.cronjob.name
    - k8s.daemonset.name
    - k8s.deployment.name
    - k8s.job.name
    - k8s.namespace.name
    - k8s.pod.name
    - k8s.replicaset.name
    - k8s.statefulset.name

查询时包含资源属性

所有未提升的、更详细或唯一的标签都附加到一个特殊的 target_info 上。

您可以使用此指标在查询时连接一些标签。

这样的查询示例如下所示

rate(http_server_request_duration_seconds_count[2m])
* on (job, instance) group_left (k8s_cluster_name)
target_info

此查询的作用是,rate(http_server_request_duration_seconds_count[2m]) 产生的时间序列会通过与 target_info 系列共享相同 jobinstance 标签的 target_info 系列中的 k8s_cluster_name 标签进行增强。换句话说,jobinstance 标签在 http_server_request_duration_seconds_counttarget_info 之间共享,类似于 SQL 外键。另一方面,k8s_cluster_name 标签对应于 OTel 资源属性 k8s.cluster.name(Prometheus 将点转换为下划线)。

那么,target_info 指标与 OTel 资源属性之间有什么关系?当 Prometheus 处理 OTLP 写入请求时,如果包含的资源包括 service.instance.id 和/或 service.name 属性,Prometheus 会为每个(OTel)资源生成信息指标 target_info。它为每个此类 target_info 系列添加标签 instance,其值为 service.instance.id 资源属性,并添加标签 job,其值为 service.name 资源属性。如果 service.namespace 资源属性存在,它将作为前缀添加到 job 标签值(即 <service.namespace>/<service.name>)。

默认情况下,service.nameservice.namespaceservice.instance.id 本身不会被添加到 target_info 中,因为它们被转换为 jobinstance。但是,可以启用以下配置参数,将其直接添加到 target_info 中(如果 otlp.translation_strategyUnderscoreEscapingWithSuffixes,则通过标准化将点替换为下划线),这是在转换为 jobinstance 之外的额外添加。

otlp:
  keep_identifying_resource_attributes: true

其余的资源属性也作为标签添加到 target_info 系列中,如果 otlp.translation_strategyUnderscoreEscapingWithSuffixes,则名称会转换为 Prometheus 格式(例如,点转换为下划线)。如果资源同时缺少 service.instance.idservice.name 属性,则不会生成相应的 target_info 系列。

对于资源的每个 OTel 指标,Prometheus 会将其转换为相应的 Prometheus 时间序列,并(如果生成了 target_info)添加正确的 instancejob 标签。

UTF-8

从 3.x 版本开始,Prometheus 支持指标名称和标签使用 UTF-8,因此可以省略 OpenTelemetry 的 Prometheus 规范化转换器包。请注意,当 Prometheus 通过内容协商宣布它允许 UTF-8 字符时,它不要求指标名称包含以前不支持的字符。OTLP 指标可能以几种不同的方式进行转换,具体取决于端点的配置。因此,虽然 Prometheus 存储和 UI 中默认启用 UTF-8,但您需要为 OTLP 指标接收器设置 translation_strategy,默认情况下它设置为旧的规范化 UnderscoreEscapingWithSuffixes

有四种可能的转换策略,其中两种要求在 Prometheus 中启用 UTF-8 支持

  • UnderscoreEscapingWithSuffixes,默认值。这会完全转义指标名称以实现经典 Prometheus 指标名称兼容性,并包含附加类型和单位后缀。
  • UnderscoreEscapingWithoutSuffixes。这会像 UnderscoreEscapingWithSuffixes 一样完全转义指标名称,但不会附加类型和单位后缀。从多个角度来看,此模式都是不可取的,用户应注意缺少后缀可能会导致指标名称冲突,并且只有在仔细测试后才能启用此模式。一些组织为了 OTel 对称性和有限字符支持之间的平衡而使用此模式。
  • NoUTF8EscapingWithSuffixes 将禁用将特殊字符更改为 _,从而允许本地使用 OpenTelemetry 指标格式,尤其是在使用语义约定方面。请注意,单位和计数器 _total 等特殊后缀将被附加,以防止多个同名指标具有不同类型或单位时可能发生的冲突。此模式需要启用 UTF-8。
  • NoTranslation。此策略绕过所有指标和标签名称转换,将其原样传递。此模式需要启用 UTF-8。请注意,如果没有后缀,当多个同名指标具有不同类型或单位时,可能会发生冲突。
otlp:
  # Ingest OTLP data keeping UTF-8 characters in metric/label names.
  translation_strategy: NoTranslation

Delta 暂时性

OpenTelemetry 规范指出,支持 Delta 暂时性和 Cumulative 暂时性。虽然 Delta 暂时性在 statsd 和 graphite 等系统中很常见,但累积暂时性是 Prometheus 中的默认设置。

如今,Prometheus 内嵌了来自 OpenTelemetry-Collector-contribdelta 到 cumulative 处理器,该处理器能够摄取 delta 指标并将其转换为等效的累积表示形式,然后存储在 Prometheus 的 TSDB 中。

此功能是***实验性***的,因此请在启用功能标志 otlp-deltatocumulative 的情况下启动 Prometheus 以使用它。

团队仍在研究更有效地处理 OTLP delta 的方法。

本页内容