如何通过Prometheus采集Redis指标并暴露Lettuce的监控接口？

本文共计1043个文字，预计阅读时间需要5分钟。

直接暴露 Lettuce 的指标给 Prometheus 不可行——它本身不提供 HTTP metrics 端点，也不内置 Actuator 风格的监控接口。必须通过 Spring Boot + Micrometer + Actuator 桥接，再配合自定义指标注册逻辑，才能使 Redis 连接行为（如超时、连接数、命令延迟等）转化为 Prometheus 可捕获的时序数据。

为什么不能直接用 lettuce-core 暴露 /actuator/prometheus

Lettuce 是纯客户端库，没有 Web 层、不启动 HTTP 服务、也不自动注册 Micrometer 指标。即使你引入了 micrometer-registry-prometheus，若没显式配置并绑定指标到 MetricsMeterRegistry，Prometheus 抓到的 /actuator/prometheus 里根本不会出现任何 Redis 相关指标。

• 常见错误现象：curl localhost:8080/actuator/prometheus | grep redis 返回空
• 根本原因：Lettuce 默认关闭所有指标采集，且不参与 Spring Boot AutoConfiguration 的 MeterBinder 自动装配
• 关键动作：必须手动启用 Lettuce 的 Micrometer 支持，并将 RedisClient 或 StatefulRedisConnection 关联到全局 MeterRegistry

启用 lettuce-core 的 Micrometer 指标采集

在创建 RedisClient 实例时，需传入带 Micrometer 配置的 ClientOptions，否则所有连接池、命令、延迟等维度的指标都不会产生。

• 必须使用 ClientOptions.builder().metricCollector(...) 显式注入 MicrometerMetricCollector
• Spring Boot 3.x 中推荐方式是通过 @Bean 定义 RedisClient，并在构造时注入 MeterRegistry
• 示例代码片段：

@Bean public RedisClient redisClient(MeterRegistry meterRegistry) { ClientOptions options = ClientOptions.builder() .metricCollector(new MicrometerMetricCollector(meterRegistry)) .build(); RedisURI uri = RedisURI.create("redis://localhost:6379"); return RedisClient.create(ClientResources.create(), uri, options); }

• 注意：MicrometerMetricCollector 来自 io.lettuce.core.metrics.micrometer 包，需额外引入 lettuce-core 6.2+（低版本无此类）
• 漏掉 ClientResources.create() 可能导致连接池未被监控——该对象承载连接生命周期管理，指标依赖其内部事件发布机制

确保 /actuator/prometheus 能暴露 Redis 指标

即使指标已注册，若 Actuator 配置或包扫描有误，依然无法在端点中看到它们。这不是 Lettuce 的问题，而是 Spring Boot 的暴露控制逻辑。

• 检查 application.yml 是否包含：

management: endpoints: web: exposure: include: health,info,metrics,prometheus endpoint: prometheus: show-details: when_authorized

• 确认项目已引入 spring-boot-starter-actuator 和 micrometer-registry-prometheus
• 验证指标是否注册成功（非端点）：curl localhost:8080/actuator/metrics | jq '.names[] | select(contains("redis"))' —— 若返回空，说明指标压根没注册进去
• 常见陷阱：多个 RedisClient Bean 导致指标重复注册或覆盖；或 @Primary 缺失引发自动配置 fallback 到默认无监控的 client

抓取不到数据？先查 Prometheus targets 页面

Prometheus 抓取失败往往不是 Lettuce 配置问题，而是网络、路径或权限卡住。别急着改 Java 代码，先看 targets。

• 访问 http://<prometheus>/targets，确认你的应用实例状态为 UP，且抓取路径是 /actuator/prometheus（不是 /prometheus 或 /metrics）
• 如果显示 context deadline exceeded，优先检查应用是否监听在 0.0.0.0（而非 localhost），以及防火墙/ServiceMesh 是否拦截了 8080 端口
• 如果指标名是 redis.command.latency 但无标签，大概率是 ClientOptions 里没传 tags ——Lettuce 默认只打基础标签（如 command, result），业务维度（如 cluster, env）得自己加

真正容易被忽略的是：Lettuce 的指标只有在**实际发生 Redis 命令调用后**才会首次上报。空跑 client 不会产生任何样本值，Prometheus 里会显示 “no data” 而不是报错——这点和 JVM 或 Nginx Exporter 完全不同。