一、 核心概念

1. Micrometer

一个类似于 SLF4J 的应用程序指标门面库。它提供了一套通用的API，让你的代码可以与各种监控系统（Prometheus, Datadog, New Relic等）对接，而无需修改代码。你只需要依赖Micrometer的接口。

2. Micrometer Registry Prometheus

一个具体的实现，负责将Micrometer收集的指标转换为Prometheus能够拉取的格式（即暴露一个 /metrics 端点）。

3.Prometheus

监控系统，它会定期来拉取（scrape）你的应用暴露的 /metrics 端点。

二、 依赖配置 (Maven)

在你的 pom.xml 中添加以下依赖：

<!-- Micrometer 核心门面 -->
<dependency><groupId>io.micrometer</groupId><artifactId>micrometer-core</artifactId><version>1.10.6</version> <!-- 请使用最新版本 -->
</dependency><!-- Micrometer 对 Prometheus 的实现 -->
<dependency><groupId>io.micrometer</groupId><artifactId>micrometer-registry-prometheus</artifactId><version>1.10.6</version>
</dependency><!-- 如果你使用 Spring Boot Actuator -->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

说明：

• 如果你用的是 Spring Boot，它已经内置了对Micrometer的完美支持，你只需要添加 micrometer-registry-prometheus 依赖即可。Actuator会自动配置好一切。
• 如果你用的是普通Java项目（如Spark-Java, Quarkus等）或Spring MVC，你需要手动配置。

三、 集成步骤与代码示例

场景一：在 Spring Boot 应用中集成（最简单）

Spring Boot的Actuator模块自动化了绝大部分工作。

1. 添加依赖（如上所示）。

配置 application.yml/application.properties:

2. 配置 application.yml/application.properties:

management:endpoints:web:exposure:include: health, info, metrics, prometheus # 暴露 prometheus 端点metrics:tags:application: my-connector-service # 为所有指标添加一个公共标签

3. 注入 MeterRegistry 并记录指标:

现在你可以在任何Spring管理的Bean（如@Service, @RestController）中注入 MeterRegistry 来创建和记录自定义指标。

import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.stereotype.Service;
import java.util.concurrent.TimeUnit;@Service
public class DataService {// 计数器：用于记录发生次数的事件，如错误、请求数private final Counter dataRequestCounter;// 计时器：用于记录耗时操作的持续时间private final Timer dataRequestTimer;// 通过构造函数注入 MeterRegistrypublic DataService(MeterRegistry registry) {// 创建并注册一个计数器dataRequestCounter = Counter.builder("connector.data.requests").description("Total number of data requests received").tag("type", "sql") // 添加自定义标签，用于细分指标.register(registry);// 创建并注册一个计时器dataRequestTimer = Timer.builder("connector.data.processing.time").description("Time taken to process a data request").register(registry);}public String fetchData(String query) {// 方法一开始就启动计时器采样Timer.Sample sample = Timer.start();dataRequestCounter.increment(); // 计数器+1String result;try {// 模拟业务逻辑result = executeQuery(query);} finally {// 无论成功失败，都记录耗时// stop() 方法将耗时记录到计时器sample.stop(dataRequestTimer);}return result;}private String executeQuery(String query) {// 模拟一个耗时操作try {Thread.sleep((long) (Math.random() * 1000));} catch (InterruptedException e) {Thread.currentThread().interrupt();}return "Result for: " + query;}
}

4. 访问指标端点:

启动应用后，访问：http://localhost:8080/actuator/prometheus
你会看到Prometheus格式的指标数据：

# HELP connector_data_requests_total Total number of data requests received
# TYPE connector_data_requests_total counter
connector_data_requests_total{application="my-connector-service", type="sql",} 12.0# HELP connector_data_processing_time_seconds Time taken to process a data request
# TYPE connector_data_processing_time_seconds summary
connector_data_processing_time_seconds_count{application="my-connector-service",} 12.0
connector_data_processing_time_seconds_sum{application="my-connector-service",} 6.234

场景二：在普通 Java Web 应用中手动集成

以使用 Spark-Java 框架为例。

1. 添加依赖（同上，无需Spring Boot Actuator）。

2. 创建并配置 Prometheus Registry:

import io.micrometer.prometheus.PrometheusConfig;
import io.micrometer.prometheus.PrometheusMeterRegistry;public class MonitoringRegistry {private static final PrometheusMeterRegistry registry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);public static PrometheusMeterRegistry getRegistry() {return registry;}
}

3. 创建 /metrics 端点:

import static spark.Spark.get;public class Main {public static void main(String[] args) {// 设置一个HTTP端点来暴露指标get("/metrics", (req, res) -> {res.type("text/plain; version=0.0.4");return MonitoringRegistry.getRegistry().scrape(); // 返回Prometheus格式的数据});// 你的其他路由...get("/data", (req, res) -> {// 使用全局的registry创建计数器Counter.builder("my_custom_requests").register(MonitoringRegistry.getRegistry()).increment();return "Hello World";});}
}

4. 在代码中使用:

和你可以在任何地方通过 MonitoringRegistry.getRegistry() 获取注册表，然后使用Micrometer API创建指标，如场景一所示。

四、 常用指标类型及用法

类型	Micrometer类	用途	示例
计数器	Counter	记录只增不减的值，如请求数、错误数。	.increment()
计时器	Timer	记录短时操作的耗时和频率。	timer.record(() -> {…}) 或 Timer.Sample
计量仪	Gauge	记录一个瞬时值，如当前内存使用、队列大小。	Gauge.builder(“queue.size”, queue, Collection::size).register(registry)
摘要	DistributionSummary	记录事件的分布情况，如响应体大小。	summary.record(responseBytes)

五、 最佳实践

1. 标签（Tags）是关键: 使用标签来维度化指标（如 method=“GET”, status=“200”, uri=“/api/data”）。避免将变量值作为指标名称（如 my_metric_/api/data）。
2. 指标命名: 使用 . 分隔单词，如 http.server.requests。保持命名一致性。
3. 不要过度测量: 监控核心业务逻辑和关键性能路径，避免产生太多无用的指标，增加存储和查询负担。
4. 利用自动配置: 在Spring Boot中，无需手动配置HTTP请求的计时器，spring-boot-starter-actuator 已经为你做好了。你只需要暴露端点即可。

通过以上步骤，你就可以轻松地在Java连接器代码中集成强大的监控能力，为后续的Prometheus抓取和Grafana可视化打下坚实的基础。