一 說明
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 時實現自己的策略，可以注冊
EndpointFilterbean。
保護 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.includeproperty 來執行此操作，如下所示：
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: world2019-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"
}