Spring Boot Actuator 和 Endpoints 端点介绍

2020-04-23 0 By admin

SpringBoot自带监控功能Actuator,可以帮助实现对程序内部运行情况监控,比如监控状况、Bean加载情况、环境变量、日志信息、线程信息等。我们可以通过JMX或者HTTP endpoints来获得。spring Boot Admin配合下可以进行页面展示,也和可以与其它外部应用系统系统整合。

一、Actuator 的使用方法

在Spring Boot应用中,要实现监控的功能,只需要依赖组件spring-boot-starter-actuator。它提供了很多监控和管理你的spring boot应用的HTTP或者JMX端点,并且你可以有选择地开启和关闭部分功能。当你的spring boot应用中引入依赖之后,将自动拥有审计、健康检查、Metrics监控功能。
官网文档: https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-enabling

1.1、Pom文件添加依赖

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

1.2、添加配置信息

management:
  endpoints:
    web:
      base-path: /actuator  # 访问根路径
#      exposure:
#        include: "*"

这里的配置项如果填写错误,则可能造成程序启动报错。比如自动注入失败等。

二、Endpoints 端点介绍

Actuator端点让你监视和与应用程序交互,Spring Boot包含许多内置的端点,并允许你添加自己的端点。例如,health端点提供基本的应用程序健康信息。
可以启用或禁用每个单独的端点,这将控制端点是否被创建,以及它的bean是否存在于应用程序上下文中,要实现远程访问,端点还必须通过JMX或HTTP公开,大多数应用程序选择HTTP,将端点的ID与/actuator的前缀映射到URL。例如,默认情况下,health端点映射到/actuator/health。

2.1、可以使用以下与技术无关的端点

Endpoint ID Description
auditevent 显示应用暴露的审计事件(比如认证进入、订单失败)
beans 显示在您的应用程序的所有的Spring bean的完整列表。
caches 公开可用的高速缓存
conditions 显示了配置和自动配置类,为什么他们没有或不匹配的原因进行评估的条件。
configprops 显示所有@ConfigurationProperties的词整理表。
env 显示当前的环境特性
flyway 显示数据库迁移路径的详细信息
health 显示应用的健康状态
httptrace 显示HTTP足迹,最近100个HTTP request/reponse
info 显示应用的基本信息
integrationgraph 显示Spring集成图形。需要在弹簧集成核心的依赖
loggers 显示和修改配置的loggers
liquibase 显示已应用于任何Liquibase数据库迁移
metrics 显示应用多样的度量信息
mappings 显示所有的@RequestMapping路径
scheduledtasks 显示应用中的调度任务
sessions 允许从支持Spring会话的会话存储中检索和删除用户会话。需要使用Spring会话的基于Servlet的web应用程序。
shutdown 优雅地逐步关闭应用
threaddump 执行一个线程dump

2.2、Web 应用程序特有的Endpoints

如果你的应用程序是一个web应用程序(Spring MVC、Spring WebFlux或Jersey),你可以使用以下附加端点:

Endpoint ID Description
heapdump 返回一个GZip压缩的JVM堆dump
jolokia Exposes JMX beans over HTTP
logfile 返回log file中的内容(如果logging.file或者logging.path被设置)
prometheus 公开指标,该格式可以被Prometheus服务器采集

要了解有关Actuator的端点及其请求和响应格式的更多信息,请参考单独的API文档。

三、启动端点

默认情况下,除了shutdown之外的所有端点都启用了,要配置端点的启动,可以使用它的management.endpoint.<id>.enabled属性,下面的示例启用关闭端点:
management.endpoint.shutdown.enabled=true
如果你更喜欢端点opt-in(默认禁用)而不是opt-out(默认启动),设置management.endpoints.enabled-by-default属性为false并使用单独的端点启用属性来选择返回,下面的示例启用info端点并禁用所有其他端点:
management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true

禁用的端点完全从应用程序上下文中删除,如果你只想更改端点暴露的技术,则使用include和exclude属性代替。

四、暴露端点

由于端点可能包含敏感信息,所以应该仔细考虑何时公开它们,下表显示了默认公开的内置端点:

ID JMX Web
auditevents Yes No
beans Yes No
caches Yes No
conditions Yes No
configprops Yes No
env Yes No
flyway Yes No
health Yes Yes
heapdump N/A No
httptrace Yes No
info Yes Yes
integrationgraph Yes No
jolokia N/A No
logfile N/A No
loggers Yes No
liquibase Yes No
metrics Yes No
mappings Yes No
prometheus N/A No
scheduledtasks Yes No
sessions Yes No
shutdown Yes No
threaddump Yes No

4.1、更改端点是否暴露

要更改公开的端点,请使用以下技术特定的include和exclude属性:

Property Default
management.endpoints.jmx.exposure.exclude
management.endpoints.jmx.exposure.include *
management.endpoints.web.exposure.exclude
management.endpoints.web.exposure.include info, health
  1. include属性列出了公开的端点的id,
  2. exclude属性列出不应公开的端点的id,
  3. exclude属性优先于include属性,
  4. include和exclude属性都可以使用端点id列表进行配置。
  5. * 可用于选择所有端点

五、Http 暴露的端点安全配置

你应该注意保护HTTP端点的方式,就像保护其他敏感URL一样,如果存在Spring Security,则使用Spring Security的内容协商策略默认保护端点。如果你希望为HTTP端点配置自定义安全性,例如,只允许具有特定角色的用户访问它们,Spring Boot提供了一些方便的RequestMatcher对象,可以与Spring Security结合使用。
具体内容,请看官方文档。

六、端点的配置

端点为不带任何参数的读取操作自动缓存响应,要配置端点缓存响应的时间量,请使用cache.time-to-live属性,下面的示例将beans端点缓存的生存时间设置为10秒:
management.endpoint.beans.cache.time-to-live=10s

七、Actuator Web 端点的超媒体

一个链接所有端点的“discovery页面”被添加,默认情况下,“ discovery页面”在/actuator上可用。
配置自定义管理上下文路径时,“discovery页面”自动从/actuator移动到管理上下文的根,例如,如果管理上下文路径是/management,那么可以从/management获得discovery页面,当管理上下文路径被设置为/时,discovery页面被禁用,以防止与其他映射发生冲突。

八、Actuator web 端点的路径

默认情况下,通过使用端点的ID在/actuator路径下通过HTTP公开端点,例如,beans端点在/actuator/beans下公开,如果希望将端点映射到不同的路径,可以使用management.endpoints.web.path-mapping属性,另外,如果你想要更改基本路径,你可以使用management.endpoints.web.base-path。
以下示例将重新映射/actuator/health到/healthcheck:
management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheck

九、CORS 跨域支持

跨源资源共享(CORS)是W3C规范,允许你灵活地指定授权的跨域请求类型,如果你使用Spring MVC或Spring WebFlux,可以配置Actuator的web端点来支持这些场景。

CORS支持在默认情况下是禁用的,并且只在management.endpoints.web.cors.allowed-origins属性已设置时才启用,以下配置允许从example.com域GET和POST调用:
management.endpoints.web.cors.allowed-origins=http://example.com
management.endpoints.web.cors.allowed-methods=GET,POST

十、自定义端点

如果你添加一个带@Endpoint注解的@Bean,那么任何带@ReadOperation、@WriteOperation或@DeleteOperation的方法都会自动地通过JMX公开,在web应用程序中,也会通过HTTP公开,可以使用Jersey、Spring MVC或Spring WebFlux通过HTTP公开端点。

你还可以使用@JmxEndpoint或@WebEndpoint来编写特定于技术的端点,这些端点仅限于各自的技术,例如,@WebEndpoint仅通过HTTP公开,而不是通过JMX公开。

可以使用@EndpointWebExtension和@EndpointJmxExtension编写特定于技术的扩展,这些注解允许你提供特定于技术的操作,以增强现有的端点。

最后,如果你需要访问特定于web框架的功能,你可以实现Servlet或Spring @Controller和@RestController端点,代价是它们在JMX上不可用,或者在使用不同的web框架时不可用。

十一、健康信息

你可以使用健康信息检查正在运行的应用程序的状态,当生产系统崩溃时,监控软件通常会用它来通知某人,health端点公开的信息取决于management.endpoint.health.show-details属性,可以使用以下值之一配置:

  1. never:不显示细节
  2. when-authorized: 详细信息只显示给授权用户,可以使用management.endpoint.health.roles配置授权角色
  3. always: 详细信息显示给所有用户

默认值是never,当用户处于端点的一个或多个角色中时,就被认为是经过授权的,如果端点没有配置角色(默认),则认为所有经过身份验证的用户都是经过授权的,可以使用management.endpoint.health.roles属性。

如果你已经保护了你的应用程序并且希望使用always,你的安全配置必须允许对经过身份验证的用户和未经身份验证的用户访问健康端点。

健康信息是从你的ApplicationContext中定义的所有HealthIndicator bean中收集的,Spring Boot包括许多自动配置的HealthIndicators,并且你也可以自己写。默认情况下,最终的系统状态由HealthAggregator派生,它根据有序的状态列表从每个HealthIndicator排序状态。排序列表中的第一个状态被用作总体健康状态,如果没有HealthAggregator所知道的HealthIndicator状态返回,则使用UNKNOWN状态。