Skip to main content
 首页 » 编程设计

Spring Boot 2 Actuator监控系统

2022年07月19日143kuangbin

Spring Boot 2 Actuator监控系统

本文介绍Spring Boot2 Actuator,首先介绍基础概念,接着学习如何使用、配置、扩展这个监控工具。

1. 什么是 Actuator

Actuator提供产品级的功能特性,使得监控应用、收集指标和流量、数据库状态变得非常简单。该库的主要优势是能够获得产品级工具,无需自己实际实现。主要用于暴露正在运行系统的操作信息,包括健康状态、指标信息、系统及环境信息等。可以使用HTTP或JMX方式进行通信交互。

只要加入依赖,默认提供几个健康端点可用,对于大多数Spring模块,有多种方式很容易进行配置或扩展。

要启用Actuator,仅需加入下面依赖包:

<dependency> 
    <groupId>org.springframework.boot</groupId> 
    <artifactId>spring-boot-starter-actuator</artifactId> 
</dependency> 

注:无论Spring boot版本是什么,这都是有效的。但本文主要聚焦2.x版本。

2. Spring Boot2 Actuator

2.x版本Actouator在之前的基础上,简化模型,扩展其功能并加入更好的缺省能力。 首先该版本与技术无关,与系统合并安全功能简化模型。最后,在各种变化中,重要的是要记住,其中一些是破坏的。这包括HTTP请求和响应以及Java api。
此外,最新版本现在支持CRUD模型,而不是旧的读/写模型。

2.1 技术支持

当前主要版本与底层技术无关,而1.x版本依赖MVC,即Servlet API。2.x版本定义自己的模型,可插拔、可扩展,无需依赖MVC。因此使用新的模型,既可以使用MVC,也可以使用WebFlux作为底层web技术。而且还可以实现适配层支持未来技术。最后要说的是,仍然支持JMX暴露的端点,且无需额外代码。

2.2 重要变化

与之前版本不同的是,废弃了大多数Actuator端点,仅保留两个缺省的端点:/health 和 /info 。
如果想启用所有端点,可以设置 management.endpoints.web.exposure.include=*.,当然也可以列出仅启用部分的端点列表。

Actuator 现在与正常应用共享安全规则配置,因此其安全模型也非常简单。调整Actuator安全规则,仅增加/actuator/**

@Bean 
public SecurityWebFilterChain securityWebFilterChain( 
    ServerHttpSecurity http) { 
    return http.authorizeExchange() 
        .pathMatchers("/actuator/**").permitAll() 
        .anyExchange().authenticated() 
        .and().build(); 
} 

另外,Actuator的缺省端点是在 /actuator路径下。和前面版本一样,可以调整该路径,使用新的属性:management.endpoints.web.base-path

2.3 预定义的端点

下面看看常用端点,大多数之前版本都有。但还是有变动,增加、删除和重构了一些端点。

端点 描述
/auditevents 列出所有安全审计相关的事件,如用户登录、登出。同时也可以根据用户的字段进行过滤。
/beans 返回所有BeanFactory中有效bean,与/auditevents不同,其不支持过滤。
/conditions 之前是/autoconfig,返回自动配置中条件配置信息
/configprops 返回所有@ConfigurationProperties配置bean列表
/env 列出当前环境属性,另外也可以返回单个属性信息
/flyway 提供Flyway 数据库迁移信息
/health 返回应用的健康指标信息
/heapdump 返回应用使用的JVM中堆内存快照
/info 返回通用信息,包括自定义属性信息
/liquibase 提供Liquibase数据库迁移信息
/logfile 返回应用日志
/loggers 可以查询或修改应用日志级别
/metrics 应用的度量指标信息,包括通用及自定义的度量指标
/prometheus 和上面端点一样,返回所有度量指标信息,但兼容Prometheus server(开源监控系统)格式
/scheduledtasks 返回应用中所有的调度任务细节
/sessions 列出 HTTP sessions,如果我们使用Spring Session
/shutdown 执行应用程序优雅退出动作
/threaddump 返回底层JVM线程信息快照

2.4 Actuator 总入口点

Spring Boot 增加了一个总入口点可以获得所有有效actuator,利用总入口点可以获得Actuator入口及其相应url。

缺省总入口点访问地址为 /actuator,如果发送GET请求,返回所有不同的Actuator:

如果你自定义管理基础路径,那么应该使用你定义的路径作为url。举例,如果你设置management.endpoints.web.base-path=/mgmt,那么应该发送 /mgmt入口点请求。有趣的是,当设置基础路径为 / 时则禁用Actuator入口点,这是为了防止和其他映射冲突。

2.5 健康指标

和之前版本一样,可以很容易增加自定义指标。与其他API不同,创建自定义健康入口点的抽象没变,但增加了新的接口ReactiveHealthIndicator实现响应式健康检查。
下面看一个响应式健康检查示例:

@Component 
	public class DownstreamServiceHealthIndicator implements ReactiveHealthIndicator { 
	  
	    @Override 
	    public Mono<Health> health() { 
	        return checkDownstreamServiceHealth().onErrorResume( 
	          ex -> Mono.just(new Health.Builder().down(ex).build()) 
	        ); 
	    } 
	  
	    private Mono<Health> checkDownstreamServiceHealth() { 
	        // we could use WebClient to check health reactively 
	        return Mono.just(new Health.Builder().up().build()); 
	    } 
	} 

健康指标有一个很方便特性是可以聚集作为层次结构的一部分。因此对于前面的示例,可以将所有下流服务作为子分类,该分类可以作为嵌入服务。这块内容后续文章会更详细讲解。

2.6 健康指标分组

Spring Boot2.2 可以组织多个健康指标为组,对组成员使用相同指标进行配置。举例,创建分组 costom分组,application.properties配置如下:

management.endpoint.health.group.custom.include=diskSpace,ping 

上面配置定义了custom组,包括diskSpace,ping健康指标。现在如果访问/actuator/health端点,响应中包括了我们增加的分组:

{"status":"UP","groups":["custom"]} 

使用健康分组,可以看到多个健康指标的组合结果。在这种情况,如果发送/actuator/health/custom请求:

{"status":"UP"} 

现在可以增加配置显示分组内指标的详细信息:

management.endpoint.health.group.custom.show-components=always 
management.endpoint.health.group.custom.show-details=always 

现在访问/actuator/health/custom端点,返回内容包括:

{ 
  "status": "UP", 
  "components": { 
    "diskSpace": { 
      "status": "UP", 
      "details": { 
        "total": 214748360704, 
        "free": 112445571072, 
        "threshold": 10485760, 
        "exists": true 
      } 
    }, 
    "ping": { 
      "status": "UP" 
    } 
  } 
} 

也可以设置为仅针对授权用户才展示详细信息:

management.endpoint.health.group.custom.show-components=when_authorized 
management.endpoint.health.group.custom.show-details=when_authorized 

我们还增加自定义状态映射。举例,代替200响应码返回207状态码:

management.endpoint.health.group.custom.status.http-mapping.up=207 

该配置告诉Spring Boot,如果custom分组状态是UP则返回207状态码。

2.7 Spring Boot 2度量指标

Spring Boot2.0开始使用Micrometer实现内置度量,我们期望有较大改变。如果应用程序使用度量服务,则GaugeService或CounterService它们将不再可用。而是可以和Micrometer直接进行交互,Spring Boot2.0自动配置了MeterRegistry Bean。

另外,Micrometer现在是Actuator依赖的一部分,因此无需增加额外的依赖。访问/metrics可以看到新的响应内容:

{ 
	"names": [ 
		"hikaricp.connections", 
		"hikaricp.connections.acquire", 
		"hikaricp.connections.active", 
		"hikaricp.connections.creation", 
		"hikaricp.connections.idle", 
		"hikaricp.connections.max", 
		"hikaricp.connections.min", 
		"hikaricp.connections.pending", 
		"hikaricp.connections.timeout", 
		"hikaricp.connections.usage", 
		"jdbc.connections.active", 
		"jdbc.connections.idle", 
		"jdbc.connections.max", 
		"jdbc.connections.min", 
		"jvm.buffer.count", 
		"jvm.buffer.memory.used", 
		"jvm.buffer.total.capacity", 
		"jvm.classes.loaded", 
		"jvm.classes.unloaded", 
		"jvm.gc.live.data.size", 
		"jvm.gc.max.data.size", 
		"jvm.gc.memory.allocated", 
		"jvm.gc.memory.promoted", 
		"jvm.gc.pause", 
		"jvm.memory.committed", 
		"jvm.memory.max", 
		"jvm.memory.used", 
		"jvm.threads.daemon", 
		"jvm.threads.live", 
		"jvm.threads.peak", 
		"jvm.threads.states", 
		"logback.events", 
		"process.cpu.usage", 
		"process.start.time", 
		"process.uptime", 
		"system.cpu.count", 
		"system.cpu.usage", 
		// ... 
	] 
} 

如果需要查看特定度量的实际值,可以浏览对应度量指标,如:/actuator/metrics/jvm.gc.pause :

{ 
  "name": "jvm.gc.pause", 
  "description": "Time spent in GC pause", 
  "baseUnit": "seconds", 
  "measurements": [ 
    { 
      "statistic": "COUNT", 
      "value": 2 
    }, 
    { 
      "statistic": "TOTAL_TIME", 
      "value": 0.172 
    }, 
    { 
      "statistic": "MAX", 
      "value": 0 
    } 
  ], 
  "availableTags": [ 
    { 
      "tag": "cause", 
      "values": [ 
        "G1 Evacuation Pause", 
        "Metadata GC Threshold" 
      ] 
    }, 
    { 
      "tag": "action", 
      "values": [ 
        "end of minor GC" 
      ] 
    } 
  ] 
} 

如我们所看到的,显示的度量更加全面了。不仅包括不同的值,还包括一些相关的元数据。

2.8 创建自定义端点

前面提到可以创建自定义端点。Spring Boot2重新设计了该实现,支持技术无关模型。下面我们创建一个Actuator端点,用于查询、启用、禁用应用中的特征标志。

@Component 
@Endpoint(id = "features") 
public class FeaturesEndpoint { 
 
    private Map<String, Feature> features = new ConcurrentHashMap<>(); 
 
    public FeaturesEndpoint(){ 
        features.put("name", Feature.of(true)); // 增加示例内容 
    } 
 
    @ReadOperation 
    public Map<String, Feature> features() { 
        return features; 
    } 
 
    @ReadOperation 
    public Feature feature(@Selector String name) { 
        return features.get(name); 
    } 
 
    @WriteOperation 
    public void configureFeature(@Selector String name, Feature feature) { 
        features.put(name, feature); 
    } 
 
    @DeleteOperation 
    public void deleteFeature(@Selector String name) { 
        features.remove(name); 
    } 
 
    public static class Feature implements Serializable { 
        private Boolean enabled; 
 
        public Feature(Boolean enabled) { 
            this.enabled = enabled; 
        } 
 
        public static Feature of(Boolean flag){ 
            return new Feature(true); 
        } 
 
        public Boolean getEnabled(){ 
            return enabled; 
        } 
    } 
} 

定义端点需要定义bean,在上面的示例中我们在bean上使用@Component、@Endpoint两个注解。@Endpoint注解中的参数定义请求路由/actuator/features。定义好bean后,开始定义操作:

  • @ReadOperation – 映射 HTTP GET
  • @WriteOperation – 映射 HTTP POST
  • @DeleteOperation – 映射 HTTP DELETE

当我们启动应用时,Spring Boot会自动注册该bean。这里需要指出的是:

  • 定义端点并不依赖MVC,不再需要实现特定接口(1.x版本需要)
  • 可以通过@Endpoint注解第二个参数启用或禁用带端点;如:@Endpoint(id = “features”, enableByDefault = false)
  • 可以使用@DeleteOperation注解定义DELETE操作

我们可以通过/actuator/features/actuator/features/{name}进行验证结果。

2.9 启用所有端点

为了使用http方式访问Actuator端点,需要启用并暴露它们。缺省情况下除了/shutdown端点都启用,但仅 /health 和 /info 两个端点缺省被暴露。增加下面配置可以暴露所有端点:

management.endpoints.web.exposure.include=* 

显示启用特定端点:

management.endpoint.shutdown.enabled=true 

暴露所有启用端点除了某个:

management.endpoints.web.exposure.include=* 
management.endpoints.web.exposure.exclude=loggers 

3. 总结

本文详细介绍了Spring Boot2 Actuator,包括2.x版本新的变化、常用配置以及如何自定义扩展指标。


本文参考链接:https://blog.csdn.net/neweastsun/article/details/108932793