把 Prometheus 指标接入 OBSERVE：remote_write 配置与三个坑

为什么要推到 OBSERVE

很多团队已经有 Prometheus 在采指标了，再搭一套 OBSERVE 的采集 Agent 属于重复建设。remote_write 是 Prometheus 原生的数据出口，配置几行就能把指标流式推送到 OBSERVE，老监控不停，新平台同步接上，风险最低。

OBSERVE 的指标接入端兼容 Prometheus remote_write 协议，也兼容 PromQL 查询，迁过来的团队几乎不用改仪表盘和告警规则。

基础配置

在 prometheus.yml 里加一段 remote_write 即可：

remote_write:
  - url: https://ob.jjhub.cn/api/prom/remote_write
    headers:
      Authorization: Bearer <token>
    remote_timeout: 30s
    write_relabel_configs:
      - source_labels: [__name__]
        regex: 'go_.*|process_.*'
        action: drop

OBSERVE 控制台里给项目生成一个专用的写入 token，别用管理员账号的 token 直接写，便于日后按项目回收权限。写完重启 Prometheus，OBSERVE 侧就能在指标页看到新数据源。

队列参数怎么调

remote_write 内部有一个 WAL（预写日志）加发送队列，参数没调好会出现两种典型故障：指标丢失、内存暴涨。三个关键参数：

• capacity：每个 shard 的内存队列长度，默认 2500。指标量大时 Prometheus 报 queue full，就往上加，比如 10000。
• max_shards：发送并发上限，默认 200。远端网络慢时提高它，但要盯着 CPU。
• max_samples_per_send：每次发送的样本数，默认 500。网络延迟高时调大到 2000 能显著提升吞吐。

一套适合中等规模（每分钟几百万样本）的保守配置：

queue_config:
  capacity: 10000
  max_shards: 50
  min_shards: 2
  max_samples_per_send: 2000
  batch_send_deadline: 10s
  min_backoff: 100ms
  max_backoff: 10s

调参的验证方式不是看文档，是看两个指标：prometheus_remote_storage_samples_failed_total（失败样本）和 prometheus_remote_storage_highest_timestamp_in_seconds（最新推送时间戳）。失败数持续增长说明队列配置不对，时间戳卡住说明通道断了。

三个坑

坑一：高基数指标写放大。 某个指标带上了用户 ID 或请求 ID 这类 label，导致序列数爆炸，一个指标就能拖垮整个通道。用 write_relabel_configs 在源头把高基数 label 删掉：

write_relabel_configs:
  - source_labels: [user_id, request_id]
    regex: '.+'
    action: labeldrop

坑二：远端临时不可用时的静默丢数据。 Prometheus 会把失败样本放进队列重试，但如果 OBSERVE 长时间不可用，WAL 也会满。监控 prometheus_remote_storage_shards_desired，它持续逼近 max_shards 说明远端跟不上，要扩容或降采样。

坑三：token 泄露。 remote_write 是明文 HTTP 头带 token，别把 prometheus.yml 提交到公共仓库。配置里用环境变量或 Secret 管理，OBSERVE 侧定期轮换 token。

验证清单

接入完成后按顺序检查：指标页能看到数据源 → 抽一条 PromQL 能查到 → 采样率与源端一致 → 失败样本数为 0 → 高基数告警没触发。五条都过，就可以把老监控的告警规则逐步迁过来了。