一 说明
Actuator 的定义
actuator 是一个制造术语,指的是用于移动或控制某物的机械装置。执行器可以通过一个小的变化产生大量的运动。
要将 actuator 添加到基于 Maven 的项目,请添加以下“Starter”依赖项:
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> </dependencies>
Endpoints
Actuator endpoints 让您监控 application 并与之交互。 Spring Boot 包含许多 built-in endpoints 并允许您添加自己的。例如,health
端点提供基本的 application 健康信息。
每个端点都可以是启用或禁用。它控制是否在 application context 中创建端点并且其 bean 是否存在。要远程访问,端点也必须是通过 JMX 或 HTTP 公开。大多数 applications 选择 HTTP,其中端点的 ID 以及/actuator
的前缀映射到 URL。对于 example,默认情况下,health
端点映射到/actuator/health
。
以下 technology-agnostic endpoints 可用:
ID | 描述 | 默认情况下启用 |
---|---|---|
auditevents |
公开当前 application 的 audit events 信息。 | 是 |
beans |
显示 application 中所有 Spring beans 的完整列表。 | 是 |
caches |
暴露可用的缓存。 | 是 |
conditions |
显示在 configuration 和 auto-configuration classes 上评估的条件以及它们执行或不执行 match 的原因。 | 是 |
configprops |
显示所有@ConfigurationProperties 的整理列表。 |
是 |
env |
从 Spring 的ConfigurableEnvironment 公开 properties。 |
是 |
flyway |
显示已应用的任何 Flyway 数据库迁移。 | 是 |
health |
显示 application 健康信息。 | 是 |
httptrace |
显示 HTTP 跟踪信息(默认情况下,最后 100 个 HTTP request-response 交换)。 | 是 |
info |
显示任意 application 信息。 | 是 |
integrationgraph |
显示 Spring Integration 图。 | 是 |
loggers |
显示并修改 application 中 loggers 的 configuration。 | 是 |
liquibase |
显示已应用的任何 Liquibase 数据库迁移。 | 是 |
metrics |
显示当前 application 的'metrics'信息。 | 是 |
mappings |
显示所有@RequestMapping paths 的整理列表。 |
是 |
scheduledtasks |
显示 application 中的计划任务。 | 是 |
sessions |
允许从 Spring Session-backed session store 中检索和删除用户会话。使用 Spring Session 支持 reactive web applications 时不可用。 | 是 |
shutdown |
让 application 正常关闭。 | 没有 |
threaddump |
执行线程转储。 | 是 |
如果 application 是 web application(Spring MVC,Spring WebFlux 或 Jersey),则可以使用以下附加 endpoints:
ID | 描述 | 默认情况下启用 |
---|---|---|
heapdump |
返回hprof 堆转储文件。 |
是 |
jolokia |
通过 HTTP 公开 JMX beans(当 Jolokia 在 classpath 上时,不适用于 WebFlux)。 | 是 |
logfile |
返回日志文件的内容(如果已设置logging.file 或logging.path properties)。支持使用 HTTP Range 标头来检索 log 文件内容的一部分。 |
是 |
prometheus |
以 Prometheus 服务器可以抓取的格式公开 metrics。 | 是 |
要了解有关 Actuator 的 endpoints 及其请求和响应格式的更多信息,请参阅单独的 API 文档(HTML或PDF)。
启用 Endpoints
默认情况下,启用除shutdown
之外的所有 endpoints。要配置端点的启用,请使用其management.endpoint..enabled
property。以下 example 启用shutdown
端点:
management.endpoint.shutdown.enabled=true
如果您希望端点启用为 opt-in 而不是 opt-out,请将management.endpoints.enabled-by-default
property 设置为false
并使用单个端点enabled
properties 重新加入。以下 example 启用info
端点并禁用所有其他 endpoints:
management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true
已禁用 endpoints 完全从 application context 中删除。如果只想更改端点所暴露的技术,请改用包含和排除 properties。
暴露 Endpoints
由于 Endpoints 可能包含敏感信息,因此应仔细考虑何时公开它们。以下 table 显示 built-in endpoints 的默认曝光:
ID | JMX | Web |
---|---|---|
auditevents |
是 | 没有 |
beans |
是 | 没有 |
caches |
是 | 没有 |
conditions |
是 | 没有 |
configprops |
是 | 没有 |
env |
是 | 没有 |
flyway |
是 | 没有 |
health |
是 | 是 |
heapdump |
N/A | 没有 |
httptrace |
是 | 没有 |
info |
是 | 是 |
integrationgraph |
是 | 没有 |
jolokia |
N/A | 没有 |
logfile |
N/A | 没有 |
loggers |
是 | 没有 |
liquibase |
是 | 没有 |
metrics |
是 | 没有 |
mappings |
是 | 没有 |
prometheus |
N/A | 没有 |
scheduledtasks |
是 | 没有 |
sessions |
是 | 没有 |
shutdown |
是 | 没有 |
threaddump |
是 | 没有 |
要更改公开的 endpoints,请使用以下 technology-specific include
和exclude
properties:
属性 | 默认 |
---|---|
management.endpoints.jmx.exposure.exclude |
|
management.endpoints.jmx.exposure.include |
* |
management.endpoints.web.exposure.exclude |
|
management.endpoints.web.exposure.include |
info, health |
include
property 列出公开的 endpoints 的 ID。 exclude
property 列出不应公开的 endpoints 的 ID。 exclude
property 优先于include
property。 include
和exclude
properties 都可以配置端点 ID 列表。
对于 example,要停止通过 JMX 公开所有 endpoints 并仅显示health
和info
endpoints,请使用以下 property:
management.endpoints.jmx.exposure.include=health,info
*
可用于选择所有 endpoints。对于 example,要通过 HTTP 公开除env
和beans
endpoints 之外的所有内容,请使用以下 properties:
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
*
在 YAML 中有特殊含义,因此如果要包含(或排除)所有 endpoints,请务必添加引号,如下面的示例所示:
management:
endpoints:
web:
exposure:
include: "*"
如果您的 application 公开曝光,我们强烈建议您也保护你的 endpoints。
如果要在公开 endpoints 时实现自己的策略,可以注册
EndpointFilter
bean。
保护 HTTP Endpoints
您应该像处理任何其他敏感 URL 一样注意保护 HTTP endpoints。如果存在 Spring Security,则默认使用 Spring Security 的 content-negotiation 策略保护 endpoints。如果您希望为 HTTP endpoints 配置自定义安全性,对于 example,只允许具有特定角色的用户访问它们,Spring Boot 提供了一些方便的RequestMatcher
objects,可以与 Spring Security 结合使用。
典型的 Spring Security configuration 可能类似于以下 example:
@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
.anyRequest().hasRole("ENDPOINT_ADMIN")
.and()
.httpBasic();
}
}
前面的 example 使用EndpointRequest.toAnyEndpoint()
来匹配任何端点的请求,然后确保所有端点都具有ENDPOINT_ADMIN
角色。其他几种匹配方法也可以在EndpointRequest
上找到。有关详细信息,请参阅 API 文档(HTML或PDF)。
如果在防火墙后部署 applications,您可能希望无需身份验证即可访问所有 actuator endpoints。您可以通过更改management.endpoints.web.exposure.include
property 来执行此操作,如下所示:
application.properties.
management.endpoints.web.exposure.include=*
此外,如果存在 Spring Security,则需要添加自定义安全性 configuration,以允许对 endpoints 进行未经身份验证的访问,如下面的示例所示:
@Configuration public class ActuatorSecurity extends WebSecurityConfigurerAdapter { @Override protected void configure(HttpSecurity http) throws Exception { http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests() .anyRequest().permitAll(); } }
配置 Endpoints
Endpoints 自动缓存对不带任何参数的读取操作的响应。要配置端点将缓存响应的 time 数量,请使用其cache.time-to-live
application.properties.
management.endpoint.beans.cache.time-to-live=10s
前缀
management.endpoint.
用于唯一标识正在配置的端点。
在进行经过身份验证的 HTTP 请求时,
Principal
被视为端点的输入,因此不会缓存响应。
Actuator Web Endpoints 的超媒体
添加了“发现页面”,其中包含指向所有 endpoints 的链接。默认情况下,“发现页面”在/actuator
上可用。
配置自定义 management context 路径后,“发现页面”会自动从/actuator
移动到 management context 的根目录。对于 example,如果 management context 路径为/management
,则发现页面可从/management
获得。当 management context 路径设置为/
时,将禁用发现页面以防止与其他映射冲突的可能性。
CORS 支持
Cross-origin 资源共享(CORS)是一个W3C 规范,它允许您以灵活的方式指定哪种 cross-domain 请求被授权。如果您使用 Spring MVC 或 Spring WebFlux,则可以配置 Actuator 的 web endpoints 以支持此类方案。
默认情况下禁用 CORS 支持,仅在设置了management.endpoints.web.cors.allowed-origins
property 后才启用 CORS 支持。以下 configuration 允许来自example.com
域的GET
和POST
calls:
management.endpoints.web.cors.allowed-origins=http://example.com management.endpoints.web.cors.allowed-methods=GET,POST
二 演示
-
pom.xml
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> </dependencies>
-
启动配置类,发会发现(Exposing 2 endpoint(s),就是上面说的)
http://localhost:8080/actuator/health
http://localhost:8080/actuator/info
2019-10-29 23:14:40.757 INFO 3372 --- [ main] o.s.web.context.ContextLoader : Root WebApplicationContext: initialization completed in 1270 ms 2019-10-29 23:14:41.057 INFO 3372 --- [ main] o.s.s.concurrent.ThreadPoolTaskExecutor : Initializing ExecutorService 'applicationTaskExecutor' 2019-10-29 23:14:41.268 INFO 3372 --- [ main] o.s.b.a.e.web.EndpointLinksResolver : Exposing 2 endpoint(s) beneath base path '/actuator' 2019-10-29 23:14:41.329 INFO 3372 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path '' 2019-10-29 23:14:41.331 INFO 3372 --- [ main] com.example.demo.DemoApplication : Started DemoApplication in 2.442 seconds (JVM running for 5.186)
-
application.yml
management: endpoints: web: exposure: include: "*" info: hello: world
2019-10-29 23:33:21.756 INFO 4512 --- [ main] o.s.b.a.e.web.EndpointLinksResolver : Exposing 13 endpoint(s) beneath base path '/actuator' 2019-10-29 23:33:21.812 INFO 4512 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path '' 2019-10-29 23:33:21.816 INFO 4512 --- [ main] com.example.demo.DemoApplication : Started DemoApplication in 3.021 seconds (JVM running for 5.481)
http://localhost:8080/actuator/metrics
{ "names": [ "jvm.memory.max", "jvm.threads.states", "jvm.gc.memory.promoted", "jvm.memory.used", "jvm.gc.max.data.size", "jvm.gc.pause", "jvm.memory.committed", "system.cpu.count", "logback.events", "http.server.requests", "jvm.buffer.memory.used", "tomcat.sessions.created", "jvm.threads.daemon", "system.cpu.usage", "jvm.gc.memory.allocated", "tomcat.sessions.expired", "jvm.threads.live", "jvm.threads.peak", "process.uptime", "tomcat.sessions.rejected", "process.cpu.usage", "jvm.classes.loaded", "jvm.classes.unloaded", "tomcat.sessions.active.current", "tomcat.sessions.alive.max", "jvm.gc.live.data.size", "jvm.buffer.count", "jvm.buffer.total.capacity", "tomcat.sessions.active.max", "process.start.time" ] }
http://localhost:8080/actuator/caches
{"cacheManagers":{}}
{
"hello": "world"
}