Junco Metrics 指标说明
[TOC]
一、访问方式
启用 junco-web 后，Prometheus 可通过下面端点抓取指标。
GET /-/metrics
响应格式为 Prometheus text format。
Content-Type: text/plain; version=0.0.4; charset=utf-8
二、基础配置
metrics:
enabled: true
jvm:
enabled: true
tags:
application: ${app.name}
env: test
配置含义：
metrics.enabled：是否开放/-/metrics端点。关闭后端点返回 404。metrics.jvm.enabled：是否注册 JVM、系统、进程指标。metrics.tags.*：公共标签，会作用到 JVM 指标和 Junco 自定义指标。
公共标签建议：
application：应用名，建议和部署服务名一致。env：环境，例如dev、test、staging、prod。cluster：集群名，可选。namespace：Kubernetes namespace，可选。
三、Spring Boot 兼容指标
Junco 使用 Micrometer Prometheus registry 暴露 JVM、系统、HTTP 指标，尽量兼容 Spring Boot Actuator 常见 Grafana 看板。
| 指标 | 类型 | 说明 |
|---|---|---|
jvm_memory_used_bytes |
Gauge | JVM 已使用内存，包含 area、id 等标签 |
jvm_memory_committed_bytes |
Gauge | JVM committed 内存 |
jvm_memory_max_bytes |
Gauge | JVM 最大内存 |
jvm_threads_live_threads |
Gauge | JVM live 线程数 |
jvm_threads_daemon_threads |
Gauge | JVM daemon 线程数 |
jvm_gc_pause_seconds_* |
Timer | GC 暂停耗时 |
process_cpu_usage |
Gauge | 当前进程 CPU 使用率 |
system_cpu_usage |
Gauge | 系统 CPU 使用率 |
process_uptime_seconds |
Gauge | 进程运行时长 |
logback_events_total |
Counter | Logback 日志事件数，带 level 标签 |
四、HTTP 服务端指标
| 指标 | 类型 | 说明 |
|---|---|---|
http_server_requests_seconds_count |
Timer count | HTTP 请求次数 |
http_server_requests_seconds_sum |
Timer sum | HTTP 请求总耗时 |
http_server_requests_seconds_max |
Timer max | 最近窗口最大请求耗时 |
低基数标签：
method：HTTP 方法。route：路由模板，例如/api/users/{id}。status：HTTP 状态码。
历史 junco_http* 指标已移除，统一使用 Micrometer 的 http_server_requests_seconds_* 命名。
RPC Provider 的内部入口 /__rpc/invoke 不计入 HTTP 服务端次数和耗时，避免 RPC 流量混入 Web 业务接口的状态码统计。RPC 请求仍会反映在 Web 忙线程、排队和拒绝指标中，因为它们实际使用同一个 Web 执行资源。
五、Junco Web 线程指标
| 指标 | 类型 | 说明 |
|---|---|---|
junco_web_threads_busy |
Gauge | 当前正在处理请求的线程数 |
junco_web_threads_current |
Gauge | 当前 Web worker 线程数 |
junco_web_threads_config_max |
Gauge | 配置的 Web worker 最大线程数 |
junco_web_requests_queued |
Gauge | 当前业务线程池等待队列中的请求数 |
junco_web_requests_rejected_total |
Counter | 业务线程池过载后拒绝的请求总数 |
这些指标用于替代 Jetty 看板中的 jetty_threads_busy、jetty_threads_current、jetty_threads_config_max，看板迁移时可把前缀替换为 junco_web。
六、进程内存指标
| 指标 | 类型 | 说明 |
|---|---|---|
process_memory_vss_bytes |
Gauge | 进程虚拟内存 |
process_memory_rss_bytes |
Gauge | 进程常驻内存 |
process_memory_swap_bytes |
Gauge | 进程 swap 使用量 |
Linux 环境优先读取 /proc/self/status。非 Linux 或无法读取时仍保留指标名，但值可能为 0，用于保证看板查询稳定。
七、Junco 自定义指标
| 指标 | 类型 | 说明 |
|---|---|---|
junco_rpc_client_requests_total |
Counter | RPC 客户端逻辑请求数，每次调用最终只记录一次 |
junco_rpc_client_attempts_total |
Counter | RPC 客户端实际网络尝试次数，包含重试 |
junco_rpc_client_request_duration_seconds_* |
Timer | RPC 客户端耗时 |
junco_rpc_server_requests_total |
Counter | RPC Provider 请求数 |
junco_rpc_server_request_duration_seconds_* |
Timer | RPC Provider 处理耗时 |
junco_gateway_requests_total |
Counter | Gateway 转发请求数 |
junco_gateway_request_duration_seconds_* |
Timer | Gateway 转发耗时 |
junco_jdbc_requests_total |
Counter | JDBC 操作次数 |
junco_jdbc_request_duration_seconds_* |
Timer | JDBC 操作耗时 |
junco_cache_requests_total |
Counter | 缓存读请求数 |
junco_cache_load_total |
Counter | 缓存回源次数 |
junco_cache_write_total |
Counter | 缓存写操作次数 |
标签必须保持低基数，例如服务名、方法名、状态、缓存名、provider、操作类型。不要把业务 ID、用户 ID、请求参数写入标签。
RPC Provider 指标包含 service、method、result 标签。result 取值为：
SUCCESS：调用成功。BUSINESS_ERROR：Provider 异常被RpcErrorEncoder转换为业务错误。FRAMEWORK_ERROR：服务不存在、方法不存在、请求格式错误等框架错误。INTERNAL_ERROR：未转换的 Provider 异常或其他内部错误。
八、NATS 消费指标
启用 junco-nats 并配置 JetStream 消费后，以下指标自动注册。
积压与线程
| 指标 | 类型 | 说明 |
|---|---|---|
| junco_nats_consumer_active_threads | Gauge | 当前活跃消费线程数 |
| junco_nats_consumer_queue_size | Gauge | 消费队列待处理任务数（高水位说明背压） |
| junco_nats_consumer_inflight | Gauge | 已提交但未完成的消息数 |
消息结果
| 指标 | 类型 | 标签 | 说明 |
|---|---|---|---|
| junco_nats_messages_total | Counter | outcome="ack" | 成功确认数 |
| junco_nats_messages_total | Counter | outcome="nak" | 等待重投递数 |
| junco_nats_messages_total | Counter | outcome="term" | 终止（丢弃）数 |
| junco_nats_messages_total | Counter | outcome="dlq" | 进入死信数 |
| junco_nats_messages_total | Counter | outcome="timeout" | 处理超时数 |
| junco_nats_messages_total | Counter | outcome="reject" | 背压拒绝数 |
Grafana 示例
消费成功率： sum(rate(junco_nats_messages_total{outcome="ack"}[1m])) / sum(rate(junco_nats_messages_total[1m]))
死信速率（告警阈值）： rate(junco_nats_messages_total{outcome="dlq"}[1m])
消费队列积压： junco_nats_consumer_queue_size
九、Schedule 定时任务指标
启用 junco-schedule 后，以下指标自动注册。
运行状态
| 指标 | 类型 | 标签 | 说明 |
|---|---|---|---|
| junco_schedule_running | Gauge | task | 任务是否运行中（1/0） |
执行结果
| 指标 | 类型 | 标签 | 说明 |
|---|---|---|---|
| junco_schedule_executions_total | Counter | task, status | 执行计数，status=SUCCESS/FAILED/TIMEOUT/SKIPPED |
| junco_schedule_duration_seconds | Timer | task | 单次执行耗时分布 |
SKIPPED 出现的原因：并发保护（上次未执行完）、分布式锁未抢到。
Grafana 示例
任务成功率： sum(rate(junco_schedule_executions_total{status="SUCCESS"}[5m])) / sum(rate(junco_schedule_executions_total[5m]))
跳过率（频繁跳过说明任务耗时过长或锁竞争激烈）： rate(junco_schedule_executions_total{status="SKIPPED"}[5m])
单任务耗时 p99： histogram_quantile(0.99, rate(junco_schedule_duration_seconds_bucket{task="dailyReconcile"}[5m]))
十、Prometheus 示例
scrape_configs:
- job_name: junco
metrics_path: /-/metrics
static_configs:
- targets:
- 127.0.0.1:9090
Kubernetes 环境可以使用 ServiceMonitor 或 Pod annotation，核心要求是抓取路径固定为 /-/metrics。
十一、Grafana 看板迁移建议
已有 Spring Boot 看板通常可以复用以下查询。
sum(rate(http_server_requests_seconds_count{application="$application"}[1m])) by (route, method, status)
sum(jvm_memory_used_bytes{application="$application"}) by (area, id)
process_cpu_usage{application="$application"}
Jetty 线程面板需要替换为 Junco Web 线程指标。
junco_web_threads_busy{application="$application"}