🚀快速接入
版本支持：v2.16.1+
下面六步，跑完你就能在 Grafana 看到 LiteFlow 的实时曲线。
# Step 1：让应用产出指标
除了 LiteFlow starter，再加 spring-boot-starter-actuator（提供 HTTP 出口）和一个具体的 registry（这里用 Prometheus 的）：
<!-- 1) LiteFlow starter（已含 liteflow-metrics） -->
<dependency>
<groupId>com.yomahub</groupId>
<artifactId>liteflow-spring-boot-starter</artifactId>
<version>2.16.1</version>
</dependency>
<!-- 2) Actuator：提供 /actuator/* 端点 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- 3) Prometheus registry：指标按 Prometheus 格式吐出 -->
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
Gradle 写法：
implementation 'com.yomahub:liteflow-spring-boot-starter:2.16.1'
implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'io.micrometer:micrometer-registry-prometheus'
Spring Boot 4 项目把第 1 个换成 liteflow-spring-boot4-starter 即可，其余依赖完全一致。
提示
liteflow-metrics 把 micrometer-core、spring-boot-actuator* 都标记为 optional，不污染你的依赖树；你引入哪个 registry，LiteFlow 就把指标写到哪个 registry。没有引入任何 registry 就不会有任何指标行为。
# Step 2：打开端点，确认指标已经在吐
加一行配置，把要用的端点对 HTTP 开放（默认只开放 health，其余都不暴露）：
management.endpoints.web.exposure.include=liteflow,prometheus
启动应用，验证出口已通（默认端口 8080，按你的 server.port 改）：
curl http://localhost:8080/actuator/prometheus | grep liteflow_
只要看到 liteflow_... 开头的行，就说明指标已经在产生并暴露了。此时还没有任何图——因为没人来抓、没人来画。
看不到 liteflow_ 行？大概率是端点没暴露（返回 404）或还没跑过任何 chain，排查见开关与端点暴露。
# Step 3：一键起 Prometheus + Grafana
LiteFlow 源码仓库的 docs/metrics-integration/ 目录备好了一份开箱即用的配置。把它拷到你机器上任意位置，进入该目录执行：
docker compose up -d
这会起两个容器：
- Prometheus（http://localhost:9090）：已配置好，每 5 秒抓一次你的应用
- Grafana（http://localhost:3000）：已自动挂好 Prometheus 数据源、并自动导入名为「LiteFlow 概览」的仪表盘（已开匿名访问，免登录）
集成资产清单：
| 文件 | 作用 |
|---|---|
docker-compose.yml | 一键起 Prometheus + Grafana 两个容器 |
prometheus.yml | 抓取配置（改 targets 指向你的应用） |
grafana/provisioning/datasources/datasource.yml | 启动时自动挂好 Prometheus 数据源 |
grafana/provisioning/dashboards/dashboards.yml | 启动时自动导入仪表盘的 provider 配置 |
grafana/dashboards/liteflow-dashboard.json | 「LiteFlow 概览」仪表盘本体（也可单独导入已有 Grafana） |
README.md | 该目录的独立使用说明 |
这套配置为演示用
匿名访问、弱口令、5s 抓取间隔，请勿直接用于生产。生产请自行加固认证、调整抓取间隔、并按性能影响与基数控制评估基数。
# Step 4：确认 Prometheus 抓到了你的应用
抓取目标默认是 host.docker.internal:8080（容器内访问"宿主机上的应用"的写法，Mac/Windows/Linux 都已适配）。
- 如果你的应用不在 8080，编辑
prometheus.yml里的targets改成你的host:port，然后docker compose restart prometheus。 - 打开 http://localhost:9090/targets ，看到
liteflow-app这个 target 状态为 UP 就对了。
# Step 5：打开 Grafana 看板
浏览器开 http://localhost:3000 ，左侧 Dashboards 里点开「LiteFlow 概览」。
这块板自带 6 个面板：Chain QPS、Chain 平均耗时、Chain 错误率、Chain 在途执行数、Node 平均耗时、Slot 占用 vs 容量。顶部还有个 chain 下拉，可只看某条链路。
# Step 6：打点流量，看曲线动起来
调用几次你的业务接口（让 chain 真正执行），等几秒钟（抓取间隔 + Grafana 刷新），面板上的曲线就会动起来。到这里整条链路就跑通了：
你的接口被调用 → chain 执行、LiteFlow 记录指标 → /actuator/prometheus 暴露
→ Prometheus 抓走 → Grafana 查询 → 你看到的曲线
# 快速核对清单
- [ ] 已引入
liteflow-spring-boot-starter（或 Boot4 版）+spring-boot-starter-actuator+ 一个 registry - [ ]
management.endpoints.web.exposure.include包含liteflow,prometheus - [ ]
curl /actuator/prometheus | grep liteflow_能看到liteflow_开头的行 - [ ]
docs/metrics-integration/下docker compose up -d起好 Prometheus + Grafana - [ ] Prometheus
/targets里liteflow-app状态为 UP - [ ] Grafana「LiteFlow 概览」仪表盘打点流量后曲线有变化
- [ ] （可选）开启直方图以支持 P95 / P99，见分位与直方图
# 非 Spring / Solon 项目
liteflow-metrics 本身框架无关，但钩子不会被自动发现。
在 Spring / Solon 下，ChainMetricsLifeCycle / NodeMetricsLifeCycle 是作为 LifeCycle 类型的 Bean 被框架扫描后注册进 LifeCycleHolder 的；非 Spring 环境没有这个扫描过程，也没有 SPI 自动加载，只 new 出实例不会产生任何指标。
你需要显式引入 liteflow-metrics，然后手动完成两步注册：
MeterRegistry registry = ...; // 你自己的 MeterRegistry（如 PrometheusMeterRegistry）
LiteflowConfig config = ...; // 你的 LiteflowConfig
// 1. 把两个执行钩子注册进 LiteFlow，否则它们永远不会被回调
LifeCycleHolder.addLifeCycle(new ChainMetricsLifeCycle(registry));
LifeCycleHolder.addLifeCycle(new NodeMetricsLifeCycle(registry));
// 2. 注册表 / slot 池的 Gauge 需要手动 bindTo
new LiteflowMeterBinder(config).bindTo(registry);
完成后，chain / node 指标与全局 Gauge 都会写入你的 registry。结构端点 /actuator/liteflow 是 Spring Actuator 的能力，在非 Spring 环境不可用，但指标依然照常采集。