《Spring Boot Actuator详解与深入应用》预计包括三篇,第一篇重点讲Spring Boot Actuator 1.x的应用与定制端点;第二篇将会对比Spring Boot Actuator 2.x 与1.x的区别,以及应用和定制2.x的端点;第三篇将会介绍Actuator metric指标与Prometheus和Grafana的使用结合。这部分内容很常用,且较为入门,欢迎大家的关注。
本文系《Spring Boot Actuator详解与深入应用》中的第二篇。在上一篇文章:Spring Boot Actuator详解与深入应用(一):Actuator 1.x主要讲了Spring Boot Actuator 1.x的应用与定制端点。Spring Boot2.0的正式版已经发布有一段时间了,目前已经到了2.1.0.RELEASE
。关于Spring Boot2.x的特性,在此不详细叙述了,但是其流行的趋势是显而易见的。
本文将会对比Spring Boot Actuator 2.x 与1.x的区别,以及应用和定制2.x的端点。重点介绍最新的2.x版本的Actuator。
Actuator 2.x继续保持其基本功能,但简化其模型,扩展其功能并包含合适的默认值。首先,这个版本变得与特定框架解耦;此外,它通过将其与应用程序合并来简化其安全模型;最后,在各种变化中,有些变化是巨大的,这包括HTTP请求/响应以及提供的Java API。此外,最新版本支持CRUD模型,而不是旧的RW(读/写)模型。
在Actuator 1.x中,它与Spring MVC绑定,因此与Servlet API相关联。而在2.x中,Actuator定义了它的模型可插拔且可扩展,而不依赖于MVC。因此,通过这个新模型,我们可以像MVC一样使用WebFlux作为底层Web技术。此外,以后的框架可以通过实现特定的适配器来增加到这个模型中。在没有任何额外的代码的情况下,JMX仍然支持暴露端点。
引入如下的依赖:
1 <dependency>
2 <groupId>org.springframework.boot</groupId>
3 <artifactId>spring-boot-starter-actuator</artifactId>
4 </dependency>
和使用的Spring Boot Actuator 1.x并没有太大的区别。
不同于之前的Actuator 1.x,Actuator 2.x 的大多数端点默认被禁掉。 Actuator 2.x 中的默认端点增加了/actuator前缀。
默认暴露的两个端点为/actuator/health 和 /actuator/info。我们可以通过设置如下的属性:
1management.endpoints.web.exposure.include=*
可以使得所有的端点暴露出来。此外,我们也可以列出需要暴露的端点或者排除某些端点。如:
1management.endpoints.web.exposure.exclude=env,beans
下面我们看一下可用的端点,他们大部分在1.x中已经存在。尽管如此,有些端点新增,有些被删除,有些被重构。
@ConfigurationProperties
的bean对象Actuator端点是敏感的,必须防止未经授权的访问。 如果应用程序中存在Spring Security,则默认情况下使用基于表单的HTTP基本身份验证来保护端点。使用Spring Security保护Actuator的端点访问。
1<dependency>
2 <groupId>org.springframework.boot</groupId>
3 <artifactId>spring-boot-starter-security</artifactId>
4</dependency>
为了应用Actuator的安全规则,我们增加如下的配置:
1@Bean
2public SecurityWebFilterChain securityWebFilterChain(
3 ServerHttpSecurity http) {
4 return http.authorizeExchange()
5 .pathMatchers("/actuator/**").permitAll()
6 .anyExchange().authenticated()
7 .and().build();
8}
如上的配置使得所有访问/actuator开头的URL都必须是登录的状态。我们还可以使用更加细化的配置:
1@Configuration
2public class ActuatorSecurityConfig extends WebSecurityConfigurerAdapter {
3 @Override
4 protected void configure(HttpSecurity http) throws Exception {
5 http
6 .authorizeRequests()
7 .requestMatchers(EndpointRequest.to(ShutdownEndpoint.class))
8 .hasRole("ACTUATOR_ADMIN")
9 .requestMatchers(EndpointRequest.toAnyEndpoint())
10 .permitAll()
11 .requestMatchers(PathRequest.toStaticResources().atCommonLocations())
12 .permitAll()
13 .antMatchers("/")
14 .permitAll()
15 .antMatchers("/**")
16 .authenticated()
17 .and()
18 .httpBasic();
19 }
20}
如上的配置主要实现了:
为了能够使用HTTP基本身份验证测试上述配置,可以添加默认的spring安全性用户:
1spring:
2 security:
3 user:
4 name: actuator
5 password: actuator
6 roles: ACTUATOR_ADMIN
与以前的版本一样,我们可以轻松添加自定义指标。创建自定义健康端点的抽象保持不变。与Spring Boot 1.x不同,endpoints.<id> .sensitive
属性已被删除。/health端点公开的运行状况信息取决于:
1management.endpoint.health.show-details
该属性可以使用以下值之一进行配置:
management.endpoint.health.roles
配置。/health端点有很多自动配置的健康指示器:如redis、rabbitmq等组件。
当如上的组件有一个状态异常,应用服务的整体状态即为down。我们也可以通过配置禁用某个组件的健康监测
1management.health.mongo.enabled: false
或者禁用所有自动配置的健康指示器:
1management.health.defaults.enabled: false
除此之外,还添加了新的接口ReactiveHealthIndicator
以实现响应式运行状况检查。
1 <dependency>
2 <groupId>io.projectreactor</groupId>
3 <artifactId>reactor-core</artifactId>
4 </dependency>
1@Component
2public class DownstreamServiceHealthIndicator implements ReactiveHealthIndicator {
3
4 @Override
5 public Mono<Health> health() {
6 return checkDownstreamServiceHealth().onErrorResume(
7 ex -> Mono.just(new Health.Builder().down(ex).build())
8 );
9 }
10
11 private Mono<Health> checkDownstreamServiceHealth() {
12 // we could use WebClient to check health reactively
13 return Mono.just(new Health.Builder().up().build());
14 }
15}
健康指标的一个便利功能是我们可以将它们聚合为层次结构的一部分。 因此,按照上面的示例,我们可以将所有下游服务分组到下游服务类别下。只要每个嵌套服务都可以访问,此次访问就是健康的。
在Spring Boot 2.0中,有一个bean类型为MeterRegistry
将会被自动配置,并且MeterRegistry
已经包含在Actuator的依赖中。如下为我们获得的/metrics端点信息。
1{
2 "names": [
3 "jvm.gc.pause",
4 "jvm.buffer.memory.used",
5 "jvm.memory.used",
6 "jvm.buffer.count",
7 // ...
8 ]
9}
可以看到,不同于1.x,我们已经看不到具体的指标信息,只是展示了一个指标列表。为了获取到某个指标的详细信息,我们可以请求具体的指标信息,如/actuator/metrics/jvm.gc.pause
1{
2 "name": "jvm.gc.pause",
3 "description": "Time spent in GC pause",
4 "baseUnit": "seconds",
5 "measurements": [{
6 "statistic": "COUNT",
7 "value": 2.0
8 }, {
9 "statistic": "TOTAL_TIME",
10 "value": 0.07300000000000001
11 }, {
12 "statistic": "MAX",
13 "value": 0.0
14 }],
15 "availableTags": [{
16 "tag": "cause",
17 "values": ["Metadata GC Threshold"]
18 }, {
19 "tag": "action",
20 "values": ["end of minor GC", "end of major GC"]
21 }]
22}
我们可以看到,现在的指标要详细得多。不仅包括不同的值,还包括一些相关的元数据。
/info端点没有什么变化,我们可以通过maven或者gradle引入依赖,增加git的详细信息。
1<dependency>
2 <groupId>pl.project13.maven</groupId>
3 <artifactId>git-commit-id-plugin</artifactId>
4</dependency>
同样的,我们可以使用maven和gradle的插件,获取到构建的name,group和version(需要类路径下存在META-INF/build-info.properties文件)。
1<plugin>
2 <groupId>org.springframework.boot</groupId>
3 <artifactId>spring-boot-maven-plugin</artifactId>
4 <executions>
5 <execution>
6 <goals>
7 <goal>build-info</goal>
8 </goals>
9 </execution>
10 </executions>
11</plugin>
我们可以自定义端点,Spring Boot 2已经更新了自定义端点的方法,下面我们定义一个可以查询、开启或者关闭features标志位的端点。
1@Component
2@Endpoint(id = "features")
3public class FeaturesEndpoint {
4
5 private Map<String, Feature> features = new ConcurrentHashMap<>();
6
7 @ReadOperation
8 public Map<String, Feature> features() {
9 return features;
10 }
11
12 @ReadOperation
13 public Feature feature(@Selector String name) {
14 return features.get(name);
15 }
16
17 @WriteOperation
18 public void configureFeature(@Selector String name, Feature feature) {
19 features.put(name, feature);
20 }
21
22 @DeleteOperation
23 public void deleteFeature(@Selector String name) {
24 features.remove(name);
25 }
26
27 public static class Feature {
28 private Boolean enabled;
29
30 //...
31 }
32
33}
定义的端点路径由@Endpoint
中的id属性决定,在如上的例子中,请求的端点地址为/actuator/features
。并用如下的方法注解来定义操作:
启动应用,可以看到控制台多了如下的日志输出:
1[...].WebFluxEndpointHandlerMapping: Mapped "{[/actuator/features/{name}],
2 methods=[GET],
3 produces=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
4[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features],
5 methods=[GET],
6 produces=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
7[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features/{name}],
8 methods=[POST],
9 consumes=[application/vnd.spring-boot.actuator.v2+json || application/json]}"
10[...].WebFluxEndpointHandlerMapping : Mapped "{[/actuator/features/{name}],
11 methods=[DELETE]}"[...]
如上的日志展示了Webflux如何暴露我们的端点,至于切换到Spring MVC,我们只需要引入依赖即可,并不需要更改任何代码。
之前方法上的元数据信息(sensitive, enabled)都不在使用了,开启或禁用端点,使用@Endpoint(id = “features”, enableByDefault = false)
。相比于旧的读写模型,我们可以使用@DeleteOperation
定义DELETE操作。
我们还可以通过注解@EndpointExtension
扩展事先定义好的端点,更精确的注解为:@EndpointWebExtension
,@EndpointJmxExtension
。
1@Component
2@EndpointWebExtension(endpoint = InfoEndpoint.class)
3public class InfoWebEndpointExtension {
4
5 private InfoEndpoint delegate;
6
7 @Autowired
8 public InfoWebEndpointExtension(InfoEndpoint delegate) {
9 this.delegate = delegate;
10 }
11
12 @ReadOperation
13 public WebEndpointResponse<Map> info() {
14 Map<String, Object> info = this.delegate.info();
15 Integer status = getStatus(info);
16 return new WebEndpointResponse<>(info, status);
17 }
18
19 private Integer getStatus(Map<String, Object> info) {
20 // return 5xx if this is a snapshot
21 return 200;
22 }
23}
本文主要讲了Actuator 2.x相关特性和使用,对比了与Actuator 1.x 在使用上的区别。Actuator 2.x不依赖于某个框架组件(如Spring MVC),做到了易于插拔和扩展。当我们想要切换到Webflux时,通过Actuator 2.x中的适配器,不需要更改任何代码即可实现。
本文源码:https://github.com/keets2012/Spring-Boot-Samples/tree/master/spring-boot-actuator-2