如何使用 Prometheus 和 Grafana 搭建 Java 应用的数据监控系统。首先简述了可观测性概念，随后详细讲解了 Prometheus 和 Grafana 的安装与整合步骤。核心部分展示了如何在 Spring Boot 项目中集成 Actuator 和 Micrometer，通过自定义监控上下文、指标收集器和监听器来采集 AI 模型调用相关的业务指标（如请求次数、Token 消耗、响应时间）。最后提供了 Prometheus 配置及 Grafana 看板导入方法，实现了从数据采集到可视化的完整闭环。
**可观测（Observability）**作为现代运维理念，强调系统在运行时应具备全面的、深入的、可理解的状态获取能力。通过收集和分析系统的各种可观测数据，构建一个全方位、立体化的监控与分析体系，运维团队能够在复杂、动态的 IT 环境中实时了解系统内部的健康状况、性能表现以及故障原因，并基于这些信息做出准确的决策，实现快速问题定位、预防性维护以及持续优化。
Prometheus 是一个开源的监控系统，专门为时序数据的收集、存储和查询而设计。
Prometheus 的核心理念是将所有监控数据以 时间序列 的形式存储。根据它的 数据模型，每个时间序列都由指标名称和一组标签唯一标识。比如 http_requests_total{method="POST", handler="/api/xxx"} 就表示一个记录 POST 请求接口总数的时间序列。
这样一来，Prometheus 能够高效地处理监控场景中的时间范围查询，比如过去一小时内各个接口的平均响应时间、CPU 使用率超过 80% 的服务器列表等。
访问 Prometheus 下载页面，选择对应的操作系统和架构。
进入对应文件夹，双击 prometheus.exe 启动。
查看默认配置文件 prometheus.yml：
# 全局配置
global:
scrape_interval: 15s # 全局抓取间隔，默认每 15 秒抓取一次
evaluation_interval: 15s # 规则评估间隔
# 告警管理器配置（可选）
alerting:
alertmanagers:
- static_configs:
- targets:
# - alertmanager:9093
# 规则文件配置
rule_files:
# - "first_rules.yml"
# - "second_rules.yml"
# 抓取配置
scrape_configs:
# Prometheus 自身监控
- job_name: "prometheus"
static_configs:
- targets: ["localhost:9090"]
labels:
app: "prometheus"
访问 http://localhost:9090 进入管理界面。
建议开启本地时间（不然时间可能少 8 个小时）。
Grafana 是一个开源的数据可视化平台，专门用于创建监控看板。它可以连接多种数据源（包括 Prometheus、MySQL、PostgreSQL、Elasticsearch 等），并提供丰富的图表类型和可视化选项。
访问 Grafana 下载页面，根据操作系统选择对应的安装包。
按照对应系统的 安装文档 进行安装。
启动 Grafana，Windows 系统直接执行 grafana-server.exe。
访问 http://localhost:3000 查看看板，默认登录账号密码都是 admin，可以参考 起始文档 来学习如何使用 Grafana 构造看板。
添加 Prometheus 数据源。
配置 Prometheus 服务器地址。
测试连接。
点击导出。
进入看板页面，查看导入的看板。
查看看板详情，一个仪表板可以包含多个 Panel（图表面板）。
每个 Panel 都可以查看具体的数据、状态和查询语句。
右上角可以将整个仪表板导出为 JSON 格式，便于分享和备份。
同样也可以通过导入 JSON 快速创建仪表板。
在 pom.xml 中添加必要的依赖：
<!-- 应用监控端点，提供健康检查、指标收集等功能 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- Prometheus 监控支持，将应用指标暴露为 Prometheus 格式 -->
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
spring-boot-starter-actuator：Actuator 提供生产就绪的监控基础设施，暴露各种管理和监控端点。它是应用与外部监控系统交互的窗口，但本身不负责指标数据的收集。
micrometer-core：Micrometer 是真正的指标收集引擎，负责收集 JVM、HTTP、数据库等各种指标数据。它提供统一的 API 让开发者可以创建自定义指标（类似于一个门面），是整个监控体系的数据生产者。
micrometer-registry-prometheus：Prometheus Registry 专门负责将 Micrometer 收集的指标数据转换为 Prometheus 格式。它创建 /actuator/prometheus 端点，让 Prometheus 服务器可以直接拉取标准格式的监控数据。
Prometheus 可以定期访问 /actuator/prometheus 端点拉取指标数据，实现对 Spring Boot 应用的持续监控和告警。
在 application.yml 中添加 Actuator 配置，暴露监控端点：
# 应用监控端点配置
management:
endpoints:
web:
exposure:
include: health,info,prometheus # 暴露健康检查、应用信息、Prometheus 指标端点
endpoint:
health:
show-details: always # 显示健康检查详情
重启项目后，可以访问端点验证配置。比如健康检查端点：localhost:8126/api/actuator/health。
Prometheus 指标端点：localhost:8126/api/actuator/prometheus，可以看到 Spring Boot 默认提供的各种系统指标。
由于需要在监听器中获取业务维度信息（比如 appId、userId），我们可以通过 ThreadLocal 来传递这些参数。
新建 monitor 包，定义监控上下文类 MonitorContext：
/**
* 监控上下文类
* 用于在应用监控中传递上下文信息，如用户 ID、应用 ID 等
*/
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class MonitorContext implements Serializable {
/**
* 用户 ID
*/
private String userId;
/**
* 应用 ID
*/
private String appId;
@Serial
private static final long serialVersionUID = 1L;
}
监控上下文持有者类：
/**
* 监控上下文持有者类
* 用于在应用监控中传递上下文信息，如用户 ID、应用 ID 等
*/
@Slf4j
public class MonitorContextHolder {
/**
* 线程本地变量，用于存储当前线程的监控上下文
*/
private static final ThreadLocal<MonitorContext> CONTEXT_HOLDER = new ThreadLocal<>();
/**
* 设置监控上下文
*/
public static void setContext(MonitorContext context) {
CONTEXT_HOLDER.set(context);
}
/**
* 获取当前监控上下文
*/
public static MonitorContext getContext() {
return CONTEXT_HOLDER.get();
}
/**
* 清除监控上下文
*/
public static void clearContext() {
CONTEXT_HOLDER.remove();
}
}
在 AppServiceImpl 的 chatToGen 方法中设置上下文（这个方法是与 ai 对话的重要方法），并在 AI 调用流结束时清理：
@Override
public Flux<String> chatToGen(Long appId, String message, User loginUser) {
// 1. 参数校验
ThrowUtils.throwIf(appId == null || appId <= 0, ErrorCode.PARAMS_ERROR, "应用 ID 不能为空");
ThrowUtils.throwIf(StrUtil.isBlank(message), ErrorCode.PARAMS_ERROR, "用户消息不能为空");
// 2. 查询应用信息
App app = this.getById(appId);
ThrowUtils.throwIf(app == null, ErrorCode.NOT_FOUND_ERROR, "应用不存在");
// 3. 验证用户是否有权限访问该应用，仅本人可以生成对话
if (!app.getUserId().equals(loginUser.getId())) {
throw new BusinessException(ErrorCode.NO_AUTH_ERROR, "无权限访问该应用");
}
// 4. 获取应用的对话生成类型
String chatGenType = app.getChatGenType();
ChatTypeEnum chatTypeEnum = ChatTypeEnum.getEnumByValue(chatGenType);
if (chatTypeEnum == null) {
throw new BusinessException(ErrorCode.SYSTEM_ERROR, "不支持的对话类型");
}
// 5. 通过校验后，添加用户消息到对话历史
chatHistoryService.addChatMessage(appId, message, ChatHistoryMessageTypeEnum.USER.getValue(), loginUser.getId());
// 6. 设置监控上下文
MonitorContextHolder.setContext(
MonitorContext.builder()
.userId(loginUser.getId().toString())
.appId(appId.toString())
.build()
);
// 7. 调用 AI 生成回复
Flux<String> contentFlux = aiChatFacade.generateAndSaveStreamFacade(message, chatTypeEnum, appId);
// 8. 收集 AI 响应内容并在完成后记录到对话历史
();
contentFlux
.map(chunk -> {
aiResponseBuilder.append(chunk);
chunk;
})
.doOnComplete(() -> {
aiResponseBuilder.toString();
(StrUtil.isNotBlank(aiResponse)) {
chatHistoryService.addChatMessage(appId, aiResponse, ChatHistoryMessageTypeEnum.AI.getValue(), loginUser.getId());
}
})
.doOnError(error -> {
+ error.getMessage();
chatHistoryService.addChatMessage(appId, errorMessage, ChatHistoryMessageTypeEnum.AI.getValue(), loginUser.getId());
})
.doFinally(signalType -> {
MonitorContextHolder.clearContext();
});
}
注意清理时机应该是在流结束时，而不是方法返回值之前，这样能确保整个请求周期内都能获取到上下文信息。
在 monitor 包下编写指标收集器，负责收集业务数据并转换为 Prometheus 指标。
这一步不用想太多，尽量把 最细粒度的数据 按照维度分类统计就好。
指标收集器需要提供几个方法，分别统计请求信息、错误信息、Token 消耗、响应时间：
/**
* AI 模型指标收集器
* 负责收集业务数据并转换为 Prometheus 指标
*/
@Component
@Slf4j
public class AiModelMetricsCollector {
@Resource
private MeterRegistry meterRegistry;
// 缓存已创建的指标，避免重复创建（按指标类型分离缓存）
private final ConcurrentMap<String, Counter> requestCountersCache = new ConcurrentHashMap<>();
private final ConcurrentMap<String, Counter> errorCountersCache = new ConcurrentHashMap<>();
private final ConcurrentMap<String, Counter> tokenCountersCache = new ConcurrentHashMap<>();
private final ConcurrentMap<String, Timer> responseTimersCache = new ConcurrentHashMap<>();
/**
* 记录请求次数
*/
public void recordRequest(String userId, String appId, String modelName, String status) {
String key = String.format("%s_%s_%s_%s", userId, appId, modelName, status);
Counter counter = requestCountersCache.computeIfAbsent(key, k ->
Counter.builder("ai_model_requests_total")
.description("AI 模型总请求次数")
.tag("user_id", userId)
.tag("app_id", appId)
.tag("model_name", modelName)
.tag("status", status)
.register(meterRegistry)
);
counter.increment();
}
{
String.format(, userId, appId, modelName, errorMessage);
errorCountersCache.computeIfAbsent(key, k ->
Counter.builder()
.description()
.tag(, userId)
.tag(, appId)
.tag(, modelName)
.tag(, errorMessage)
.register(meterRegistry)
);
counter.increment();
}
{
String.format(, userId, appId, modelName, tokenType);
tokenCountersCache.computeIfAbsent(key, k ->
Counter.builder()
.description()
.tag(, userId)
.tag(, appId)
.tag(, modelName)
.tag(, tokenType)
.register(meterRegistry)
);
counter.increment(tokenCount);
}
{
String.format(, userId, appId, modelName);
responseTimersCache.computeIfAbsent(key, k ->
Timer.builder()
.description()
.tag(, userId)
.tag(, appId)
.tag(, modelName)
.register(meterRegistry)
);
timer.record(duration);
}
}
这里的几个关键点：
Counter.builder()...register() 操作。在 monitor 包下编写 AI 模型监控监听器，这是整个监控体系的核心：
/**
* AI 模型监控监听器
* 负责监听 AI 模型的请求和响应事件，收集指标并记录到 Prometheus
*/
@Component
@Slf4j
public class AiModelMonitorListener implements ChatModelListener {
// 用于存储请求开始时间的键
private static final String REQUEST_START_TIME_KEY = "request_start_time";
// 用于监控上下文传递（因为请求和响应事件的触发不是同一个线程）
private static final String MONITOR_CONTEXT_KEY = "monitor_context";
@Resource
private AiModelMetricsCollector aiModelMetricsCollector;
/**
* 处理模型请求事件
*/
@Override
public void onRequest(ChatModelRequestContext requestContext) {
requestContext.attributes().put(REQUEST_START_TIME_KEY, Instant.now());
MonitorContext context = MonitorContextHolder.getContext();
if (context == null) {
context = MonitorContext.builder()
.userId("unknown")
.appId("unknown")
.build();
}
requestContext.attributes().put(MONITOR_CONTEXT_KEY, context);
String userId = context.getUserId();
String appId = context.getAppId();
requestContext.chatRequest().modelName();
aiModelMetricsCollector.recordRequest(userId, appId, modelName, );
}
{
Map<Object, Object> attributes = responseContext.attributes();
(MonitorContext) attributes.get(MONITOR_CONTEXT_KEY);
context.getUserId();
context.getAppId();
responseContext.chatResponse().modelName();
aiModelMetricsCollector.recordRequest(userId, appId, modelName, );
recordResponseTime(attributes, userId, appId, modelName);
recordTokenUsage(responseContext, userId, appId, modelName);
}
{
Map<Object, Object> attributes = errorContext.attributes();
(MonitorContext) attributes.get(MONITOR_CONTEXT_KEY);
(context == ) {
log.warn();
;
}
context.getUserId();
context.getAppId();
errorContext.chatRequest().modelName();
errorContext.error().getMessage();
aiModelMetricsCollector.recordRequest(userId, appId, modelName, );
aiModelMetricsCollector.recordError(userId, appId, modelName, errorMessage);
recordResponseTime(attributes, userId, appId, modelName);
}
{
(Instant) attributes.get(REQUEST_START_TIME_KEY);
Duration.between(startTime, Instant.now());
aiModelMetricsCollector.recordResponseTime(userId, appId, modelName, responseTime);
}
{
responseContext.chatResponse().metadata().tokenUsage();
(tokenUsage != ) {
aiModelMetricsCollector.recordTokenUsage(userId, appId, modelName, , tokenUsage.inputTokenCount());
aiModelMetricsCollector.recordTokenUsage(userId, appId, modelName, , tokenUsage.outputTokenCount());
aiModelMetricsCollector.recordTokenUsage(userId, appId, modelName, , tokenUsage.totalTokenCount());
}
}
}
有几个重要细节需要注意：
需要将监听器注册到 AI 模型配置中才能生效。
在 config 包下新建 AiModelConfig 类：
/**
* AI 模型配置类
* 配置模型的 API 密钥、模型名称、最大令牌数、监听器（用于监控模型调用）等参数
*/
@Configuration
public class AiModelConfig {
@Resource
private AiModelMonitorListener aiModelMonitorListener;
@Value("${langchain4j.community.dashscope.streaming-chat-model.api-key}")
private String apiKey;
@Value("${langchain4j.community.dashscope.streaming-chat-model.model-name}")
private String modelName;
@Value("${langchain4j.community.dashscope.streaming-chat-model.max-tokens:8129}")
private Integer maxTokens;
@Bean
@Primary
public StreamingChatModel streamingChatModel() {
return QwenStreamingChatModel.builder()
.apiKey(apiKey)
.modelName(modelName)
.maxTokens(maxTokens)
.listeners(List.of(aiModelMonitorListener))
.build();
}
}
通过前端发起一次 AI 对话请求，触发请求监听，能够获取到上下文信息。
触发响应监听，能够获取到请求时间和上下文信息。
现在需要配置 Prometheus 定期从我们的应用拉取监控数据，可以通过修改 Prometheus 目录下的 prometheus.yml：
# Prometheus 配置文件
global:
scrape_interval: 15s # 全局抓取间隔
evaluation_interval: 15s # 规则评估间隔
# 告警管理器配置 (可选)
alerting:
alertmanagers:
- static_configs:
- targets:
# - alertmanager:9093
# 规则文件配置
rule_files:
# - "alert_rules.yml"
# 可以添加告警规则
# 抓取配置
scrape_configs:
# Prometheus 自身监控
- job_name: 'prometheus'
static_configs:
- targets: ['localhost:9090']
# Spring Boot 应用监控
- job_name: 'AlzAssistant'
metrics_path: '/api/actuator/prometheus' # Spring Boot Actuator 端点
static_configs:
- targets: ['localhost:8126'] # 应用服务器地址
scrape_interval: 10s # 每 10 秒抓取一次
scrape_timeout: 10s # 抓取超时时间
在 Prometheus 的 Status -> Target health 页面可以查看抓取状态。
测试查询我们自定义的指标。
有了数据后，接下来在 Grafana 中创建可视化看板。
创建仪表板。
手动配置图表，以应用 Token 消耗排行为例。
配置步骤：
topk(10, sum(ai_model_tokens_total{token_type="total"}) by (app_id))。Instant 选项。这样只会返回当前时刻的值，而不是时间序列。点击右上角保存看板。
我们可以利用 AI 生成 json 配置，提示词如下：
帮我根据分析需求、数据上报相关代码、示例从 Prometheus 收集到的数据，来生成 Grafana 看板的 JSON 导入代码，全部汇总到一个看板中。
相关的规范参考：https://grafana.com/docs/grafana/latest/dashboards/build-dashboards/view-dashboard-json-model/
## 需求
// ... 补充分析需求
## 数据上报相关代码
// ... 补充 AiModelMetricsCollector.java 的代码
## 示例收集到的数据
HELP ai_model_requests_total AI 模型总请求次数
TYPE ai_model_requests_total counter
ai_model_requests_total{app_id="313129227198590976",model_name="deepseek-chat",status="started",user_id="302588523967918080"} 2.0
ai_model_requests_total{app_id="313129227198590976",model_name="deepseek-chat",status="success",user_id="302588523967918080"} 2.0
HELP ai_model_response_duration_seconds AI 模型响应时间
TYPE ai_model_response_duration_seconds summary
ai_model_response_duration_seconds_count{app_id="313129227198590976",model_name="deepseek-chat",user_id="302588523967918080"} 2
ai_model_response_duration_seconds_sum{app_id="313129227198590976",model_name="deepseek-chat",user_id="302588523967918080"} 91.285863
HELP ai_model_tokens_total AI 模型 Token 消耗总数
TYPE ai_model_tokens_total counter
ai_model_tokens_total{app_id="313129227198590976",model_name="deepseek-chat",token_type="input",user_id="302588523967918080"} 1321.0
ai_model_tokens_total{app_id="313129227198590976",model_name="deepseek-chat",token_type="output",user_id="302588523967918080"} 519.0
ai_model_tokens_total{app_id="313129227198590976",model_name=,token_type=,user_id=}
进入 Dashboards 页面。
点击右上角，选择 import。
复制粘贴到下方的框框里即可，点击 load。
效果如图。
生成的配置可直接用于导入 Grafana 看板。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online