OpenTelemetry 对接 Prometheus 后端:OTLP 直推的配置与数据模型避坑

配置 Prometheus 通过 OTLP/HTTP 接收 OpenTelemetry 指标,核对资源属性、标签基数、指标命名和 Delta/Cumulative 时间性,并区分 DataKit 的 OTLP 接入和 Prometheus 抓取路径。

最佳实践
OpenTelemetry 对接 Prometheus 后端:OTLP 直推的配置与数据模型避坑封面

OpenTelemetry 与 Prometheus 的组合逻辑是"用 OTel 统一埋点,用 Prometheus 存储查询"——埋点层厂商中立、一次接入多端导出,存储层继续沿用团队熟悉的 PromQL 与 Grafana 生态,两者各取所长。

核心要点速览

  • 组合价值:标准化埋点 + 熟悉的存储查询 + 独立扩缩容 + 双社区背书;
  • Prometheus 需显式开启 OTLP 接收端点(默认关闭);
  • 数据模型关键差异:资源属性需"提升"为标签、Delta/Cumulative 时间性转换;
  • 生产上警惕标签基数膨胀,提升属性务必克制。

为什么要把 OTel 指标送进 Prometheus?

五个现实理由:

  1. 埋点标准化:OTel 提供跨语言的中立 API/SDK,切换后端时可复用埋点,但仍需核对数据模型和查询;
  2. 存储查询强大:Prometheus 的时序库 + PromQL 是指标分析的事实标准;
  3. 部署灵活:埋点、管道、存储三层各自独立扩缩容;
  4. 社区双保险:两个 CNCF 顶级项目,长期演进有保障;
  5. 统一可观测:指标走 Prometheus,链路日志走 OTel 生态,埋点层只有一套。

如何配置对接?

Prometheus 的 OTLP 接收默认关闭(安全考虑),需显式开启。本机示例先把下文的 Prometheus 配置保存为 prometheus.yml:

prometheus --web.enable-otlp-receiver --web.listen-address=127.0.0.1:9090 --config.file=prometheus.yml

Prometheus 接收的是 OTLP/HTTP 指标,路径为 /api/v1/otlp/v1/metrics。应用直推时,支持环境变量配置的 SDK 可设置 OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf 和 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://127.0.0.1:9090/api/v1/otlp/v1/metrics。通用端点变量 OTEL_EXPORTER_OTLP_ENDPOINT 则填写基础地址,导出器会按信号追加路径。链路和日志需要单独配置目的地。

经过 Collector 时,可在本机用以下最小配置(Collector 0.159.0):

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318
exporters:
  otlp_http:
    endpoint: http://127.0.0.1:9090/api/v1/otlp
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [otlp_http]

这里的 endpoint 会追加 /v1/metrics;若使用 metrics_endpoint,就填完整路径。旧版 Collector 可能使用 otlphttp 名称。跨主机部署时替换地址,并按部署环境配置访问控制和 TLS。Prometheus 接收指南 · Collector HTTP 导出器

数据模型的三个关键差异

1. 资源属性 → 标签:OTel 用资源属性描述数据产生者(service.name、Pod 名等),Prometheus 只有标签。两种对接方式:

  • 提升为标签:在 prometheus.yml 配置 otlp.promote_resource_attributes,把 service.name、k8s.pod.name 等直接变成可查询标签;
  • 走 target_info:以 Prometheus 3.16 为例,资源除了能生成 job 或 instance 的标识,还需包含至少一个非标识属性,才会生成对应的 target_info。属性变化仍可能产生新的 target_info 序列。3.16 转换器实现

service.name 与 service.instance.id 会映射为 job 与 instance。设置 service.namespace 时,job 形如 namespace/service。同一实例应保有稳定的标识,不同实例应能区分。以下配置会把资源已有的 deployment.environment.name 属性提升为 deployment_environment_name:

otlp:
  translation_strategy: UnderscoreEscapingWithSuffixes
  promote_resource_attributes:
    - deployment.environment.name

2. 基数红线:每一种实际出现的标签组合都对应一条独立时间序列。标签值若与已有维度高度相关,增长可能较小;Pod 等频繁变化的值仍可能增加序列流转和内存压力。用实际序列数、变化速率和实例资源定预算(参见《高基数问题》)。

3. 时间性与命名:OTel 指标有 Delta/Cumulative 两种聚合时间性(见《指标对比》)。已有查询若以累积计数器为输入,优先在 SDK 输出 Cumulative,或在 Collector 侧转换。Prometheus 3.2 新增实验性开关 otlp-deltatocumulative,3.4 新增实验性的原始 Delta 写入,两者不能同时开启。Prometheus 3.16 默认命名策略 UnderscoreEscapingWithSuffixes 会规范名称,并按类型和单位加后缀。切换策略前先用实际查询核对结果。版本变更记录 · 特性开关

生产注意事项

  • 给 OTLP 端点加认证:开启接收等于开了一个写入口,内网也要配 Basic Auth 或 mTLS;
  • 批量导出:应用侧或 Collector 侧务必配 batch,避免每指标一请求;
  • 乱序和长留存分开处理:多个 Collector 的批次可能乱序抵达;先检查同一序列是否被重复写入,再按实际延迟评估 storage.tsdb.out_of_order_time_window。Remote Write 可把数据发送到兼容的长期存储,但不会自动消除重复或修复同一序列的写入冲突;
  • 验证映射:上线前先推一条测试指标,确认标签映射与命名符合预期。

需要其他存储后端时

OTel 的导出层也可以连接其他后端。例如观测云 DataKit 的 OpenTelemetry 采集器接收 OTLP 数据 [1];已有 /metrics 端点则可由 prom 采集器抓取 [2]。两条路径分别复用 OTel 埋点和 Prometheus 格式的指标暴露,不要求先把所有应用改成同一种 SDK。

迁移存储后端仍需处理标签基数、指标命名与查询差异。保留一段双写窗口,对照请求计数和延迟分布,再迁移对应图表与告警。

常见问题(FAQ)

Q:Prometheus 2.x 能接 OTLP 吗? 2.47 已提供实验性 OTLP/HTTP 接收,使用 --enable-feature=otlp-write-receiver;3.x 用 --web.enable-otlp-receiver,应按部署版本核对参数。Collector 的 prometheusremotewrite 导出器对应另一种协议,需要目标端支持 Remote Write 接收。

Q:直推和经过 Collector 哪个好? 生产推荐经过 Collector(或 DataKit):批量、重试、属性处理都在管道层完成,应用侧保持轻量。

Q:资源属性全提升会怎样? 标签基数爆炸,Prometheus 内存飙升甚至 OOM。只提升查询确实需要的维度,其余留在 target_info。

Q:观测云支持 PromQL 吗? 支持。观测云指标分析提供 PromQL 查询模式,也提供 DQL 等查询方式。迁移时对照采集后的指标名称、标签与时间窗口,验证原有表达式的结果;支持 PromQL 查询不等于所有看板与告警无需调整。

系列阅读

[1]: 观测云文档《OpenTelemetry》https://docs.guance.com/integrations/opentelemetry/
[2]: 观测云文档《Prometheus 采集》https://docs.guance.com/integrations/prom/

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台