Pushgw Proxy Remote Write API

Nightingale pushgw 提供一个纯转发的 remote_write 接口：客户端把 Prometheus remote_write 数据推给 pushgw，pushgw 不解析 body、不进队列，直接将原始字节按配置文件中的 Writers 列表逐个转发给后端（Prometheus / VictoriaMetrics / Mimir / 其他兼容 remote_write 协议的存储）。

相比 /prometheus/v1/write 走内存队列 + relabel + sharding 的完整链路，/proxy/v1/write 更接近一个"带认证和并发保护的 L7 反向代理"，适用于：

• pushgw 本身只想做一层接入网关，写入聚合交给后端集群；
• 多机房 / 多副本 fan-out，需要把同一份数据复制到多个后端；
• 想要原样保留客户端 header（Content-Encoding、X-Prometheus-Remote-Write-Version 等），不希望被 pushgw 重新打包。

接口定义

POST /proxy/v1/write

• 请求 body：标准 Prometheus remote_write，即 protobuf + snappy 压缩。
• pushgw 不会解析 body，原样转发；query string 也会原样附加到每个 writer 的 URL 上。
• 是否需要认证由 pushgw 配置决定（见下文 BasicAuth）。

认证方式

是否启用认证由 pushgw.yaml 中的 HTTP.APIForAgent.BasicAuth / HTTP.APIForService.BasicAuth 决定：

• 任一 map 非空 → 启用 HTTP Basic Auth，需在请求头携带 Authorization: Basic <base64(user:pass)>；
• 两者均为空 → 不需要认证。

示例：

curl -u myuser:mypass \
  -H 'Content-Type: application/x-protobuf' \
  -H 'Content-Encoding: snappy' \
  -H 'X-Prometheus-Remote-Write-Version: 0.1.0' \
  --data-binary @payload.snappy \
  "http://pushgw:17000/proxy/v1/write"

请求头透传规则

下列请求头会被 pushgw 透传到后端 writer；缺省时使用默认值：

其他请求头不会主动透传。后端 writer 自身的 BasicAuthUser / BasicAuthPass / Headers 在转发时单独设置（在配置文件里配，详见下文）。

Query String 透传

请求 URL 的 query string 会原样拼接到每个 writer 的 URL 后面。例如：

• writer 配置：http://vminsert:8480/insert/0/prometheus/api/v1/write
• 客户端请求：POST /proxy/v1/write?extra_label=cluster%3Dcn-bj
• 实际转发：POST http://vminsert:8480/insert/0/prometheus/api/v1/write?extra_label=cluster%3Dcn-bj

若 writer URL 本身已带 ?，则用 & 续接。

响应

成功

HTTP/1.1 200 OK

注意：只要 pushgw 收到并准备好转发，就立即返回 200。后端 writer 是否成功（含 4xx/5xx、超时、连接失败）只会反映在日志和 metrics 中，不会回写到客户端响应。这是 fan-out + 多 writer 设计的必然结果——任意一个 writer 慢/挂都不应该影响整个请求。

失败

429 是背压信号，配合 remote_write 客户端原生的 WAL + 退避重试机制，客户端会自动重试，无需上层处理。

背压与限流

/proxy/v1/write 通过两个全局参数控制内存上限：

pushgw.yaml 示例：

Pushgw:
  ProxyInflightMax: 2000
  ProxyMaxBodyBytes: 67108864   # 64 MiB

  Writers:
    - Url: http://victoriametrics-1:8428/api/v1/write
      Timeout: 10000
      DialTimeout: 3000
      MaxIdleConns: 100
      MaxIdleConnsPerHost: 100
      IdleConnTimeout: 90000
      Headers:
        - X-Scope-OrgID
        - n9e
    - Url: http://victoriametrics-2:8428/api/v1/write
      BasicAuthUser: writer
      BasicAuthPass: secret
      Timeout: 10000

内存占用上限约为 ProxyInflightMax × ProxyMaxBodyBytes，按 1000 × 32 MiB ≈ 32 GiB 估算，实际峰值远小于此（多数 remote_write 批次在 64–256 KiB）。

Writers 配置说明

注意：/proxy/v1/write 不使用 WriteRelabels（不解析 body 自然没法 relabel）。relabel 只在 /prometheus/v1/write 路径上生效。

监控指标

pushgw 在 /metrics 接口暴露以下指标（namespace n9e_pushgw）：

推荐告警：

• n9e_pushgw_proxy_remote_write_inflight 长期接近 ProxyInflightMax → 扩容或调高阈值；
• rate(n9e_pushgw_proxy_remote_write_over_limit_total[5m]) > 0 持续触发 → 后端写入慢，客户端可能丢数据；
• rate(n9e_pushgw_proxy_forward_error_total[5m]) > 0 按 url / reason 切片排障。

客户端配置示例

Prometheus

remote_write:
  - url: http://pushgw:17000/proxy/v1/write
    basic_auth:
      username: myuser
      password: mypass
    queue_config:
      capacity: 10000
      max_shards: 50
      max_samples_per_send: 2000

vmagent

vmagent \
  -remoteWrite.url=http://pushgw:17000/proxy/v1/write \
  -remoteWrite.basicAuth.username=myuser \
  -remoteWrite.basicAuth.password=mypass

Grafana Alloy / OpenTelemetry Collector

任何兼容 Prometheus remote_write 协议的客户端都可直接对接。

与 /prometheus/v1/write 的对比

简单原则：需要 relabel、target 心跳、kafka 旁路 → 用 /prometheus/v1/write；单纯透明转发到 remote_write 后端 → 用 /proxy/v1/write。