Prometheus + Grafana 实现 Java 应用数据监控系统

访问 http://localhost:9090 进入管理界面。

建议开启本地时间（不然时间可能少 8 个小时）。

Grafana

Grafana 是一个开源的数据可视化平台，专门用于创建监控看板。它可以连接多种数据源（包括 Prometheus、MySQL、PostgreSQL、Elasticsearch 等），并提供丰富的图表类型和可视化选项。

访问 Grafana 下载页面，根据操作系统选择对应的安装包。

按照对应系统的 安装文档 进行安装。

启动 Grafana，Windows 系统直接执行 grafana-server.exe。

访问 http://localhost:3000 查看看板，默认登录账号密码都是 admin，可以参考 起始文档 来学习如何使用 Grafana 构造看板。

Grafana 整合 Prometheus

添加 Prometheus 数据源。

配置 Prometheus 服务器地址。

测试连接。

点击导出。

进入看板页面，查看导入的看板。

查看看板详情，一个仪表板可以包含多个 Panel（图表面板）。

每个 Panel 都可以查看具体的数据、状态和查询语句。

右上角可以将整个仪表板导出为 JSON 格式，便于分享和备份。

同样也可以通过导入 JSON 快速创建仪表板。

开发实现

1.引入依赖

在 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>

1. spring-boot-starter-actuator：Actuator 提供生产就绪的监控基础设施，暴露各种管理和监控端点。它是应用与外部监控系统交互的窗口，但本身不负责指标数据的收集。

2. micrometer-core：Micrometer 是真正的指标收集引擎，负责收集 JVM、HTTP、数据库等各种指标数据。它提供统一的 API 让开发者可以创建自定义指标（类似于一个门面），是整个监控体系的数据生产者。

3. micrometer-registry-prometheus：Prometheus Registry 专门负责将 Micrometer 收集的指标数据转换为 Prometheus 格式。它创建 /actuator/prometheus 端点，让 Prometheus 服务器可以直接拉取标准格式的监控数据。

Prometheus 可以定期访问 /actuator/prometheus 端点拉取指标数据，实现对 Spring Boot 应用的持续监控和告警。

2.编写配置

在 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 默认提供的各种系统指标。

3.监控上下文

由于需要在监听器中获取业务维度信息（比如 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 响应内容并在完成后记录到对话历史
    StringBuilder aiResponseBuilder = new StringBuilder();
    return contentFlux
        .map(chunk -> {
            // 收集 AI 响应内容
            aiResponseBuilder.append(chunk);
            return chunk;
        })
        .doOnComplete(() -> {
            // 流式响应完成后，添加 AI 消息到对话历史
            String aiResponse = aiResponseBuilder.toString();
            if (StrUtil.isNotBlank(aiResponse)) {
                chatHistoryService.addChatMessage(appId, aiResponse, ChatHistoryMessageTypeEnum.AI.getValue(), loginUser.getId());
            }
        })
        .doOnError(error -> {
            // 如果 AI 回复失败，也要记录错误消息
            String errorMessage = "AI 回复失败：" + error.getMessage();
            chatHistoryService.addChatMessage(appId, errorMessage, ChatHistoryMessageTypeEnum.AI.getValue(), loginUser.getId());
        })
        .doFinally(signalType -> {
            // 流结束时清理（无论成功/失败/取消）
            MonitorContextHolder.clearContext();
        });
}

注意清理时机应该是在流结束时，而不是方法返回值之前，这样能确保整个请求周期内都能获取到上下文信息。

4.指标收集器

在 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();
    }

    /**
     * 记录错误
     */
    public void recordError(String userId, String appId, String modelName, String errorMessage) {
        String key = String.format("%s_%s_%s_%s", userId, appId, modelName, errorMessage);
        Counter counter = errorCountersCache.computeIfAbsent(key, k -> 
            Counter.builder("ai_model_errors_total")
                .description("AI 模型错误次数")
                .tag("user_id", userId)
                .tag("app_id", appId)
                .tag("model_name", modelName)
                .tag("error_message", errorMessage)
                .register(meterRegistry)
        );
        counter.increment();
    }

    /**
     * 记录 Token 消耗
     */
    public void recordTokenUsage(String userId, String appId, String modelName, String tokenType, long tokenCount) {
        String key = String.format("%s_%s_%s_%s", userId, appId, modelName, tokenType);
        Counter counter = tokenCountersCache.computeIfAbsent(key, k -> 
            Counter.builder("ai_model_tokens_total")
                .description("AI 模型 Token 消耗总数")
                .tag("user_id", userId)
                .tag("app_id", appId)
                .tag("model_name", modelName)
                .tag("token_type", tokenType)
                .register(meterRegistry)
        );
        counter.increment(tokenCount);
    }

    /**
     * 记录响应时间
     */
    public void recordResponseTime(String userId, String appId, String modelName, Duration duration) {
        String key = String.format("%s_%s_%s", userId, appId, modelName);
        Timer timer = responseTimersCache.computeIfAbsent(key, k -> 
            Timer.builder("ai_model_response_duration_seconds")
                .description("AI 模型响应时间")
                .tag("user_id", userId)
                .tag("app_id", appId)
                .tag("model_name", modelName)
                .register(meterRegistry)
        );
        timer.record(duration);
    }
}

这里的几个关键点：

1. 选择合适的指标类型：Counter 用于计数（请求次数、错误次数、Token 数量）；Timer 用于时间测量（AI 模型响应时间）。
2. 使用缓存避免统计对象重复注册：Micrometer 会为相同的维度组合创建唯一的指标，通过缓存可以重用同一个 Counter / Timer 对象，避免每次调用都执行 Counter.builder()...register() 操作。

5.AI 调用监听器

在 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();
        String modelName = requestContext.chatRequest().modelName();
        aiModelMetricsCollector.recordRequest(userId, appId, modelName, "started");
    }

    /**
     * 处理模型响应事件
     */
    @Override
    public void onResponse(ChatModelResponseContext responseContext) {
        // 从属性中获取监控信息（由 onRequest 方法存储）
        Map<Object, Object> attributes = responseContext.attributes();
        // 从监控上下文中获取信息
        MonitorContext context = (MonitorContext) attributes.get(MONITOR_CONTEXT_KEY);
        String userId = context.getUserId();
        String appId = context.getAppId();
        // 获取模型名称
        String modelName = responseContext.chatResponse().modelName();
        // 记录成功请求
        aiModelMetricsCollector.recordRequest(userId, appId, modelName, "success");
        // 记录响应时间
        recordResponseTime(attributes, userId, appId, modelName);
        // 记录 Token 使用情况
        recordTokenUsage(responseContext, userId, appId, modelName);
    }

    /**
     * 处理模型错误事件
     */
    @Override
    public void onError(ChatModelErrorContext errorContext) {
        // 从属性中获取监控信息（由 onRequest 方法存储）
        Map<Object, Object> attributes = errorContext.attributes();
        MonitorContext context = (MonitorContext) attributes.get(MONITOR_CONTEXT_KEY);
        if (context == null) {
            log.warn("监控上下文为空，跳过错误监控");
            return;
        }
        String userId = context.getUserId();
        String appId = context.getAppId();
        String modelName = errorContext.chatRequest().modelName();
        String errorMessage = errorContext.error().getMessage();
        aiModelMetricsCollector.recordRequest(userId, appId, modelName, "error");
        aiModelMetricsCollector.recordError(userId, appId, modelName, errorMessage);
        recordResponseTime(attributes, userId, appId, modelName);
    }

    /**
     * 记录响应时间
     */
    private void recordResponseTime(Map<Object, Object> attributes, String userId, String appId, String modelName) {
        Instant startTime = (Instant) attributes.get(REQUEST_START_TIME_KEY);
        Duration responseTime = Duration.between(startTime, Instant.now());
        aiModelMetricsCollector.recordResponseTime(userId, appId, modelName, responseTime);
    }

    /**
     * 记录 Token 使用情况
     */
    private void recordTokenUsage(ChatModelResponseContext responseContext, String userId, String appId, String modelName) {
        TokenUsage tokenUsage = responseContext.chatResponse().metadata().tokenUsage();
        if (tokenUsage != null) {
            aiModelMetricsCollector.recordTokenUsage(userId, appId, modelName, "input", tokenUsage.inputTokenCount());
            aiModelMetricsCollector.recordTokenUsage(userId, appId, modelName, "output", tokenUsage.outputTokenCount());
            aiModelMetricsCollector.recordTokenUsage(userId, appId, modelName, "total", tokenUsage.totalTokenCount());
        }
    }
}

有几个重要细节需要注意：

1. 线程切换问题：请求监听在主线程，但响应监听可能在另一个线程，所以要通过 AI context 的 attributes 传递参数。
2. 时间计算：在请求开始时记录时间戳，在响应完成时计算耗时。
3. 错误处理：即使发生错误也要记录响应时间，便于分析错误请求的特征。

6.注册监听器到 AI 模型中

需要将监听器注册到 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();
    }
}

7.测试验证

通过前端发起一次 AI 对话请求，触发请求监听，能够获取到上下文信息。

触发响应监听，能够获取到请求时间和上下文信息。

8.Prometheus 配置

现在需要配置 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 页面可以查看抓取状态。

测试查询我们自定义的指标。

9.Grafana 可视化监控配置

有了数据后，接下来在 Grafana 中创建可视化看板。

1）手动配置看板

创建仪表板。

手动配置图表，以应用 Token 消耗排行为例。

配置步骤：

1. 选择图表类型为 Bar Chart，设置基础信息。
2. 在查询编辑器中填写 PromQL 表达式：topk(10, sum(ai_model_tokens_total{token_type="total"}) by (app_id))。
3. 查询编辑器中，勾选 Instant 选项。这样只会返回当前时刻的值，而不是时间序列。
4. 查询编辑器中，修改面板类型，将面板类型从 Time series 改为 Table。

点击右上角保存看板。

2）通过 json 配置来导入看板

我们可以利用 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="deepseek-chat",token_type="total",user_id="302588523967918080"} 1840.0

进入 Dashboards 页面。

点击右上角，选择 import。

复制粘贴到下方的框框里即可，点击 load。

效果如图。

附：json 配置示例

生成的配置可直接用于导入 Grafana 看板。