Spring Boot 3.5+Micrometer通过Pushgateway推送Prometheus指标失败排查

一、排查当前Prometheus注册表推送失败问题 #

1. 核对Pushgateway配置 #

确保Spring Boot配置文件中Prometheus Pushgateway的参数正确：

management:
  metrics:
    export:
      prometheus:
        pushgateway:
          enabled: true
          base-url: http://your-pushgateway:9091
          username: your-auth-user
          password: your-auth-pass
          push-rate: 10s
          job: spring-boot-app-demo

重点确认enabled: true、地址及认证信息无误，job字段必须设置。

2. 检查自定义指标注册逻辑 #

自定义指标需正确绑定到PrometheusMeterRegistry，示例代码：

@Bean
public MeterRegistryCustomizer<PrometheusMeterRegistry> prometheusTagConfig() {
    return registry -> registry.config().commonTags("app", "your-app-id");
}

@Bean
public Counter requestCounter(MeterRegistry meterRegistry) {
    return Counter.builder("http_requests_total")
        .description("Total HTTP requests processed")
        .register(meterRegistry);
}

避免将指标误注册到OTLP注册表。

3. 开启调试日志定位错误 #

添加日志配置查看推送细节：

logging:
  level:
    io.micrometer: DEBUG
    io.micrometer.prometheus: DEBUG

从日志中排查连接失败、认证错误或指标格式问题。

二、无需额外组件直接推送至Prometheus #

Prometheus原生支持Remote Write接收，可跳过Pushgateway直接推送：

1. 配置Prometheus开启Remote Write接收 #

在prometheus.yml中启用Remote Write端点（确保Prometheus版本≥2.0）：

remote_write:
  - url: "http://your-prometheus:9090/api/v1/write"
    # 按需添加认证
    basic_auth:
      username: prom-admin
      password: prom-secret

默认情况下api/v1/write端点已开启，需确保防火墙允许Spring Boot访问该地址。

2. 配置Spring Boot使用Remote Write推送 #

引入micrometer-registry-prometheus依赖后，在配置文件中添加：

management:
  metrics:
    export:
      prometheus:
        remote-write:
          enabled: true
          url: http://your-prometheus:9090/api/v1/write
          username: prom-admin
          password: prom-secret
          batch-size: 1000
          connect-timeout: 5s
          read-timeout: 10s

配置完成后，Spring Boot会直接将指标推送到Prometheus的Remote Write API。

3. 验证推送结果 #

在Prometheus查询界面搜索自定义指标（如http_requests_total），确认数据已接收。同时检查Spring Boot日志，确保无推送错误。

三、常见问题处理 #

• 若Remote Write失败，确认Prometheus的web.enable-admin-api未被禁用（默认开启）。
• 检查网络连通性：Spring Boot需能访问Prometheus的9090端口，无防火墙拦截。
• 确保指标名称符合Prometheus规范：仅包含字母、数字、下划线和冒号。

内容的提问来源于stack exchange，提问作者PatPanda