Spring Boot Actuator监控实战指南

文档摘要

Spring Boot Actuator监控实战指南 Actuator概览 Spring Boot Actuator是Spring Boot提供的生产级监控和管理功能模块，它通过HTTP端点或JMX（Java Management Extensions）暴露应用的运行时信息，包括健康状态、指标、环境信息、日志等。在微服务架构中，Actuator是实现应用可观测性的重要组件。添加Actuator依赖 Maven配置 Gradle配置配置Actuator端点 application.

Spring Boot Actuator监控实战指南

Actuator概览

Spring Boot Actuator是Spring Boot提供的生产级监控和管理功能模块，它通过HTTP端点或JMX（Java Management Extensions）暴露应用的运行时信息，包括健康状态、指标、环境信息、日志等。在微服务架构中，Actuator是实现应用可观测性的重要组件。

添加Actuator依赖

Maven配置


<dependencies>
    <!-- Actuator核心依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    
    <!-- 如果需要使用WebFlux（响应式） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    
    <!-- Micrometer Prometheus集成 -->
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-registry-prometheus</artifactId>
    </dependency>
</dependencies>

Gradle配置


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'io.micrometer:micrometer-registry-prometheus'
}

配置Actuator端点

application.yml配置


management:
  # 启用所有端点
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,loggers,env,beans,threaddump,heapdump
      base-path: /actuator
  
  # 健康检查配置
  endpoint:
    health:
      enabled: true
      show-details: always  # 显示详细健康信息
      show-components: always
    info:
      enabled: true
    metrics:
      enabled: true
    prometheus:
      enabled: true
  
  # 健康指示器配置
  health:
    redis:
      enabled: true
    db:
      enabled: true
    diskspace:
      enabled: true
      threshold: 10MB  # 磁盘空间阈值
  
  # 指标配置
  metrics:
    export:
      prometheus:
        enabled: true
    tags:
      application: ${spring.application.name}
      environment: ${spring.profiles.active:dev}
  
  # 应用信息
  info:
    app:
      name: @project.name@
      description: @project.description@
      version: @project.version@
    java:
      version: ${java.version}
    build:
      artifact: @project.artifactId@
      group: @project.groupId@

核心端点详解

1. Health端点

访问地址：GET /actuator/health

响应示例：


{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 500000000000,
        "free": 250000000000,
        "threshold": 10485760,
        "path": "/",
        "exists": true
      }
    },
    "ping": {
      "status": "UP"
    },
    "db": {
      "status": "UP",
      "details": {
        "database": "MySQL",
        "validationQuery": "isValid()"
      }
    },
    "redis": {
      "status": "UP",
      "details": {
        "version": "7.2"
      }
    }
  }
}

2. Metrics端点

访问地址：GET /actuator/metrics

查看特定指标：GET /actuator/metrics/jvm.memory.used

响应示例：


{
  "name": "jvm.memory.used",
  "description": "The amount of used memory",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 123456789
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": ["heap", "nonheap"]
    },
    {
      "tag": "id",
      "values": ["G1 Eden Space", "G1 Old Gen"]
    }
  ]
}

3. Prometheus端点

访问地址：GET /actuator/prometheus

响应示例（Prometheus格式）：


# HELP jvm_memory_used_bytes The amount of used memory
# TYPE jvm_memory_used_bytes gauge
jvm_memory_used_bytes{area="heap",id="G1 Eden Space",} 1.23456789E8
jvm_memory_used_bytes{area="heap",id="G1 Old Gen",} 5.67890123E7

# HELP system_cpu_usage The recent cpu usage for the whole system
# TYPE system_cpu_usage gauge
system_cpu_usage 0.45

# HELP http_server_requests_seconds Timer of the HTTP server
# TYPE http_server_requests_seconds_summary summary
http_server_requests_seconds_sum{exception="none",method="GET",outcome="SUCCESS",status="200",uri="/api/users",} 0.123
http_server_requests_seconds_count{exception="none",method="GET",outcome="SUCCESS",status="200",uri="/api/users",} 1000.0

4. Info端点

访问地址：GET /actuator/info

自定义Info贡献者：


@Component
public class CustomInfoContributor implements InfoContributor {
    
    @Override
    public void contribute(Info.Builder builder) {
        Map<String, Object> gitDetails = new HashMap<>();
        gitDetails.put("branch", "main");
        gitDetails.put("commit", "abc123");
        
        builder.withDetail("git", gitDetails)
               .withDetail("custom", Map.of(
                   "author", "John Doe",
                   "email", "john@example.com"
               ));
    }
}

自定义健康指示器

创建自定义健康指示器


@Component
public class ExternalServiceHealthIndicator implements HealthIndicator {
    
    private final RestTemplate restTemplate;
    
    public ExternalServiceHealthIndicator(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    @Override
    public Health health() {
        try {
            // 调用外部服务
            ResponseEntity<String> response = restTemplate.getForEntity(
                "https://api.example.com/health", 
                String.class
            );
            
            if (response.getStatusCode().is2xxSuccessful()) {
                return Health.up()
                    .withDetail("status", "Service is available")
                    .withDetail("responseTime", "100ms")
                    .build();
            }
            
            return Health.down()
                .withDetail("status", "Service returned error")
                .withDetail("statusCode", response.getStatusCode())
                .build();
            
        } catch (Exception e) {
            return Health.down()
                .withDetail("error", e.getMessage())
                .withDetail("timestamp", System.currentTimeMillis())
                .build();
        }
    }
}

自定义Metrics

使用Micrometer自定义指标


@Service
public class OrderService {
    
    private final MeterRegistry meterRegistry;
    private final Counter orderCounter;
    private final Timer orderTimer;
    
    public OrderService(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        
        // 创建计数器
        this.orderCounter = Counter.builder("orders.created")
            .description("Total orders created")
            .tag("type", "online")
            .register(meterRegistry);
        
        // 创建计时器
        this.orderTimer = Timer.builder("order.processing.time")
            .description("Order processing time")
            .register(meterRegistry);
    }
    
    public void createOrder(Order order) {
        // 记录订单创建
        orderCounter.increment();
        
        // 记录处理时间
        orderTimer.record(() -> {
            // 处理订单逻辑
            processOrder(order);
        });
    }
    
    private void processOrder(Order order) {
        // 业务逻辑
    }
}

自定义Gauge


@Component
public class CacheSizeGauge {
    
    private final Cache<String, Object> cache;
    
    public CacheSizeGauge(MeterRegistry meterRegistry, Cache cache) {
        this.cache = cache;
        
        // 注册Gauge
        Gauge.builder("cache.size", cache, Cache::size)
            .description("Cache size")
            .tags("cache", "userCache")
            .register(meterRegistry);
    }
}

安全配置

端点安全保护


@Configuration
public class ActuatorSecurityConfig {
    
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers("/actuator/info").permitAll()
                .requestMatchers("/actuator/prometheus").hasRole("MONITORING")
                .requestMatchers("/actuator/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .httpBasic(withDefaults());
        
        return http.build();
    }
}

使用Spring Security保护端点


management:
  server:
    port: 8081  # 使用独立端口
  endpoints:
    web:
      exposure:
        include: '*'
  security:
    enabled: true

spring:
  security:
    user:
      name: admin
      password: admin123
      roles: ACTUATOR

集成Prometheus + Grafana

1. 配置Prometheus拉取指标

prometheus.yml：


scrape_configs:
  - job_name: 'spring-boot-app'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['localhost:8080']
        labels:
          application: 'my-spring-app'
          environment: 'production'
    scrape_interval: 15s

2. 创建Grafana仪表板

推荐使用的指标：

JVM内存使用率：jvm_memory_used_bytes / jvm_memory_max_bytes
GC时间：jvm_gc_pause_seconds_sum
HTTP请求QPS：rate(http_server_requests_seconds_count[1m])
HTTP请求延迟：rate(http_server_requests_seconds_sum[5m]) / rate(http_server_requests_seconds_count[5m])
线程数：jvm_threads_live_threads
数据库连接池使用率：hikaricp_connections_active / hikaricp_connections_max

告警规则配置

Prometheus告警规则：


groups:
  - name: spring-boot-alerts
    rules:
      - alert: HighCPUsage
        expr: system_cpu_usage > 0.8
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High CPU usage detected"
          description: "CPU usage is above 80% for 5 minutes"
      
      - alert: HighMemoryUsage
        expr: jvm_memory_used_bytes{area="heap"} / jvm_memory_max_bytes{area="heap"} > 0.9
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "High memory usage detected"
          description: "Heap memory usage is above 90% for 5 minutes"
      
      - alert: HighErrorRate
        expr: rate(http_server_requests_seconds_count{status=~"5.."}[5m]) > 10
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "High error rate detected"
          description: "Error rate is above 10 req/s for 2 minutes"
      
      - alert: ServiceDown
        expr: up{job="spring-boot-app"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Service is down"
          description: "Spring Boot application has been down for 1 minute"

最佳实践

有选择地暴露端点：不要在生产环境暴露所有端点
使用独立端口：将Actuator端口与应用端口分离
启用安全性：保护敏感端点
定期检查：集成到监控平台
自定义指标：监控业务关键指标
日志关联：结合日志系统进行问题定位
性能测试：确保监控不会影响应用性能
版本控制：管理健康检查和指标版本

总结

Spring Boot Actuator提供了强大的监控能力，是构建生产级应用的重要组成部分。通过合理配置和自定义，可以实现对应用运行状态的全面监控，及时发现和解决问题。

在2026年的微服务架构中，可观测性已成为基本要求。掌握Actuator的使用，配合Prometheus、Grafana等工具，可以构建出完善的监控体系，为应用的稳定运行提供有力保障。

发布日期：2026年03月27日
主题：Spring Boot Actuator监控实战指南

作者与出处

原作者：灏天文库智能体

来源：Tikam02

原文： https://github.com/Tikam02/DevOps-Guide

许可证：MIT

整理：灏天文库整理

由灏天文库结构化整理，提供目录导航、全文检索与在线阅读，便于系统化学习