OpenTelemetry 对接 Prometheus 后端:OTLP 直推的配置与数据模型避坑
配置 Prometheus 通过 OTLP/HTTP 接收 OpenTelemetry 指标,核对资源属性、标签基数、指标命名和 Delta/Cumulative 时间性,并区分 DataKit 的 OTLP 接入和 Prometheus 抓取路径。
OpenTelemetry 与 Prometheus 的组合逻辑是"用 OTel 统一埋点,用 Prometheus 存储查询"——埋点层厂商中立、一次接入多端导出,存储层继续沿用团队熟悉的 PromQL 与 Grafana 生态,两者各取所长。
核心要点速览
- 组合价值:标准化埋点 + 熟悉的存储查询 + 独立扩缩容 + 双社区背书;
- Prometheus 需显式开启 OTLP 接收端点(默认关闭);
- 数据模型关键差异:资源属性需"提升"为标签、Delta/Cumulative 时间性转换;
- 生产上警惕标签基数膨胀,提升属性务必克制。
为什么要把 OTel 指标送进 Prometheus?
五个现实理由:
- 埋点标准化:OTel 提供跨语言的中立 API/SDK,切换后端时可复用埋点,但仍需核对数据模型和查询;
- 存储查询强大:Prometheus 的时序库 + PromQL 是指标分析的事实标准;
- 部署灵活:埋点、管道、存储三层各自独立扩缩容;
- 社区双保险:两个 CNCF 顶级项目,长期演进有保障;
- 统一可观测:指标走 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 查询不等于所有看板与告警无需调整。
系列阅读
- 上一篇:《OpenTelemetry 最佳实践》
- 下一篇:《K8s 部署 OpenTelemetry Collector》
- 相关:《OpenTelemetry 与 Prometheus 对比》 · 《OpenTelemetry 指标 vs Prometheus 指标》 · 《返回索引》
[1]: 观测云文档《OpenTelemetry》https://docs.guance.com/integrations/opentelemetry/
[2]: 观测云文档《Prometheus 采集》https://docs.guance.com/integrations/prom/