Spring Boot 探索 | Actuator 端點詳細說明
先在這裡
宣告
一下:這一系列的文章都是自己查詢網上資料學習而來,不可避免有些內容從其他地方copy過來,如有侵犯請聯絡我刪除,謝謝!(引用部分都會添加註腳
)
本系列文章的寫作環境為:
Spring Boot 2.0.7.RELEASE
、JDK 1.8.0_131
、IntelliJ IDEA ULTIMATE 2018.1
。並沒有使用最新版本的Spring Boot進行學習,新版本還不穩定,存在很多問題,不要把時間花費在無謂的BUG上。
接上文……,這篇文章我們詳細的說明一下 Actuator 內建的端點。
Endpoints(端點)介紹
Endpoints 是 Actuator 的核心部分,它用來監視應用程式及互動,spring-boot-actuator中已經內建了非常多的Endpoints(health、info、beans、httptrace、shutdown等等),同時也允許我們擴充套件自己的端點。
Endpoints 分成兩類:原生端點
和使用者自定義端點
;自定義端點主要是指擴充套件性,使用者可以根據自己的實際應用,定義一些比較關心的指標,在執行期進行監控。
原生端點是在應用程式裡提供的眾多 restful api
介面,通過它們可以監控應用程式執行時的內部狀況。原生端點又可以分成三類:
- 應用配置類:可以檢視應用在執行期間的靜態資訊:例如自動配置資訊、載入的spring bean資訊、yml檔案配置資訊、環境資訊、請求對映資訊;
- 度量指標類:主要是執行期間的動態資訊,例如堆疊、請求連、一些健康指標、metrics資訊等;
- 操作控制類:主要是指shutdown,使用者可以傳送一個請求將應用的監控功能關閉。
Actuator 預設提供了以下介面,具體如下表所示:
ID | 描述 | 預設啟用 | 預設公開 |
---|---|---|---|
auditevents |
公開當前應用程式的審計事件資訊 | Yes | No |
beans |
顯示應用程式中所有Spring bean的完整列表 | Yes | No |
conditions |
顯示在配置和自動配置類上評估的條件以及它們是否匹配的原因 | Yes | No |
configprops |
顯示所有@ConfigurationProperties 對照的列表 |
Yes | No |
env |
從Spring的ConfigurableEnvironment 中公開屬性 |
Yes | No |
flyway |
顯示已應用的任何Flyway資料庫遷移 | Yes | No |
health |
顯示應用程式健康資訊 | Yes | Yes |
httptrace |
顯示HTTP跟蹤資訊(預設情況下,最後100個HTTP請求-響應互動) | Yes | No |
info |
顯示任意應用程式資訊 | Yes | Yes |
loggers |
顯示和修改應用程式中記錄器的配置 | Yes | No |
liquibase |
顯示已應用的任何Liquibase資料庫遷移 | Yes | No |
metrics |
顯示當前應用程式的“指標”資訊 | Yes | No |
mappings |
顯示所有@RequestMapping 路徑對照的列表 |
Yes | No |
scheduledtasks |
顯示應用程式中排程的任務 | Yes | No |
sessions |
允許從Spring Session支援的會話儲存中檢索和刪除使用者會話 | Yes | No |
shutdown |
讓應用程式優雅地關閉 | No | No |
threaddump |
執行執行緒轉儲 | Yes | No |
如果你的應用程式是一個web應用程式(Spring MVC、Spring WebFlux或Jersey),你可以使用以下附加端點:
ID | 描述 | 預設啟用 | 預設公開 |
---|---|---|---|
heapdump |
返回一個GZip壓縮的hprof 堆轉儲檔案 |
Yes | No |
jolokia |
在HTTP上公開JMX bean(當Jolokia在類路徑上時,WebFlux不可用) | Yes | No |
logfile |
返回日誌檔案的內容,支援使用HTTP Range header來檢索日誌檔案內容的一部分 |
Yes | No |
prometheus |
公開指標,該格式可以被Prometheus伺服器採集 | Yes | No |
需要注意的是:
- Spring Boot 2.0的端點和之前的版本有較大不同,使用時需注意。另外,端點的監控機制也有很大不同,啟用了不代表可以直接訪問,還需要將其暴露出來;
- 傳統的
management.security
管理已被標記為不推薦,現在一般使用單獨啟用並暴露; - 禁用的端點將從應用程式上下文中完全刪除,如果只想公開端點(對外暴露),需要使用
include
和exclude
屬性屬性。
要檢視所有的內建端點,我們需要在 application.yml 檔案中新增如下配置項,啟用並暴露所有埠:
management:
endpoints:
web:
exposure:
include: "*" # 暴露所有埠
enabled-by-default: true # 啟用所有埠
訪問 /actuator 端點,可以獲取所有啟用並暴露的端點:http://127.0.0.1:8080/actuator
{
"_links": {
"self": {
"href": "http://127.0.0.1:8080/actuator",
"templated": false
},
......
"beans": {
"href": "http://127.0.0.1:8080/actuator/beans",
"templated": false
},
"health": {
"href": "http://127.0.0.1:8080/actuator/health",
"templated": false
},
"conditions": {
"href": "http://127.0.0.1:8080/actuator/conditions",
"templated": false
},
......
}
}
Actuator 在 1.X 和 2.X 之間變化很大,具體可以看我的這篇文章:4.2.3 Actuator 在 Spring Boot 1.X 和Spring Boot 2.X 的差異
應用配置類端點
由於Spring Boot為了改善傳統 Spring 應用繁雜的配置內容,採用了包掃描和自動化配置的機制來載入原本集中於 xml 檔案中的各項內容。雖然這樣的做法,讓我們的程式碼變得非常簡潔,但是整個應用的例項建立和依賴關係等資訊都被離散到了各個配置類的註解上,這使得我們分析整個應用中資源和例項的各種關係變得非常的困難。而這類端點就可以幫助我們輕鬆的獲取一系列關於 Spring 應用配置內容的詳細報告,比如:自動化配置的報告、Bean建立的報告、環境屬性的報告等。1
/conditions
該端點在 1.x 版本中叫 autoconfig,該端點用來獲取應用的自動化配置報告。其中,包括所有自動化配置的候選項。同時還列出了每個候選項自動化配置的各個先決條件是否滿足。所以,該端點可以幫助我們方便的找到一些自動化配置為什麼沒有生效的具體原因。該報告內容將自動化配置內容分為三部分:
- positiveMatches:返回的是條件匹配成功的自動化配置;
- negativeMatches:返回的是條件匹配不成功的自動化配置;
- unconditionalClasses;
{
"positiveMatches": {
"EndpointWebMvcAutoConfiguration": [
{
"condition": "OnClassCondition",
"message": "@ConditionalOnClass classes found: javax.servlet.Servlet,org.springframework.web.servlet.DispatcherServlet"
},
{
"condition": "OnWebApplicationCondition",
"message": "found web application StandardServletEnvironment"
}
],
......
},
"negativeMatches": {
"HealthIndicatorAutoConfiguration.DataSourcesHealthIndicatorConfiguration": [
{
"condition": "OnClassCondition",
"message": "required @ConditionalOnClass classes not found: org.springframework.jdbc.core.JdbcTemplate"
}
],
......
}
}
從如上示例中我們可以看到,每個自動化配置候選項中都有一系列的條件,比如上面沒有成功匹配的HealthIndicatorAutoConfiguration.DataSourcesHealthIndicatorConfiguration配置,它的先決條件就是需要在工程中包含org.springframework.jdbc.core.JdbcTemplate類。由於我們沒有引入相關的依賴,它就不會執行自動化配置內容。所以,當我們發現有一些期望的配置沒有生效時,就可以通過該端點來檢視沒有生效的具體原因。
/beans
該端點用來獲取應用上下文中建立的所有Bean。
如上示例中,我們可以看到在每個bean中都包含了下面這幾個資訊:
- 外層的key是Bean的名稱;
- scope:Bean的作用域;
- type:Bean的Java型別;
- reource:class檔案的具體路徑;
- dependencies:依賴的Bean名稱。
/configprops
該端點用來獲取應用中配置的屬性資訊報告,prefix屬性代表了屬性的配置字首,properties代表了各個屬性的名稱和值,例如我們可以設定spring.http.encoding.charset=”UTF-8” 。
/env 和 /env/{toMatch}
該端點與 /configprops 不同,它用來獲取應用所有可用的環境屬性報告。包括:環境變數、JVM屬性、應用的配置配置、命令列中的引數。從下面該端點返回的示例片段中,我們可以看到它不僅返回了應用的配置屬性,還返回了系統屬性、環境變數等豐富的配置資訊,其中也包括了應用還沒有使用的配置。所以它可以幫助我們方便地看到當前應用可以載入的配置資訊,並配合@ConfigurationProperties
註解將它們引入到我們的應用程式中來進行使用。另外,為了配置屬性的安全,對於一些類似密碼等敏感資訊,該端點都會進行隱私保護,但是我們需要讓屬性名中包含:password、secret、key這些關鍵詞,這樣該端點在返回它們的時候會使用*來替代實際的屬性值。2
/env 是返回所有的環境引數,如果只是檢視其中一個的只需要在後邊加上引數名稱即可。如:http://127.0.0.1:8080/actuator/env/local.server.port
/mappings
顯示所有的@RequestMapping
路徑。
{
"handler": "public java.lang.String com.lpf.actuator.DemoController.index()",
"predicate": "{[/index],methods=[GET]}",
"details": {
"handlerMethod": {
"className": "com.lpf.actuator.DemoController",
"name": "index",
"descriptor": "()Ljava/lang/String;"
},
"requestMappingConditions": {
"consumes": [],
"headers": [],
"methods": [
"GET"
],
"params": [],
"patterns": [
"/index"
],
"produces": []
}
}
}
/info
該端點用來返回一些應用自定義的資訊。預設情況下,該端點只會返回一個空的json內容。我們可以在 application.yml 配置檔案中通過info字首來設定一些屬性。另外,還有關於應用內部的一些資訊,這些資訊從編譯檔案比如:META-INF/build-info.properties 或者 Git 檔案比如:git.properties 或者任何環境的 property 中獲取。
深度解析:https://blog.csdn.net/qq_26000415/article/details/79234812
使用案例: https://blog.csdn.net/dyc87112/article/details/73739530
操作控制類端點
控制類端點擁有強大的控制能力,如果要使用它們的話,需要通過屬性來配置開啟。
/shutdown
在原生端點中,提供了一個用來關閉應用的端點:/shutdown(預設是關閉的)。我們可以通過如下配置開啟它:management.endpoint.shutdown.enabled=true。在配置了上述屬性之後,只需要訪問該應用的/shutdown端點就能實現關閉該應用的遠端操作。由於開放關閉應用的操作本身是一件非常危險的事,所以真正在線上使用的時候,我們需要對其加入一定的保護機制,比如:定製Actuator的端點路徑、整合Spring Security進行安全校驗等。
度量指標類
上面我們所介紹的應用配置類端點所提供的資訊報告在應用啟動的時候都已經基本確定了其返回內容,可以說是一個靜態報告。而度量指標類端點提供的報告內容則是動態變化的,這些端點提供了應用程式在執行過程中的一些快照資訊,比如:記憶體使用情況、HTTP請求統計、外部資源指標等。這些端點對於我們構建微服務架構中的監控系統非常有幫助,由於Spring Boot應用自身實現了這些端點,所以我們可以很方便地利用它們來收集我們想要的資訊,以制定出各種自動化策略。下面,我們就來分別看看這些強大的端點功能。2
/metrics 和 /metrics/{requiredMetricName}
該端點用來返回當前應用的各類重要度量指標,比如:記憶體資訊、執行緒資訊、垃圾回收資訊等。
這一對端點不像前邊的幾對端點,這一對端點中 /metrics 返回所有你能檢視的度量指標,/metrics/{requiredMetricName} 是看某一個度量指標的具體值。例如:/actuator/metrics/jvm.buffer.memory.used
Metrics的視覺化: Spring Boot Metrics監控之Prometheus&Grafana
/health
該端點用來獲取應用的各類健康指標資訊。在 spring-boot-starter-actuator 模組中自帶實現了一些常用資源的健康指標檢測器。這些檢測器都通過 HealthIndicator 介面實現,並且會根據依賴關係的引入實現自動化裝配,比如用於檢測磁碟的 DiskSpaceHealthIndicator、檢測 DataSource 連線是否可用的 DataSourceHealthIndicator 等。
/httptrace
該端點用來返回基本的HTTP跟蹤資訊。預設情況下,跟蹤資訊的儲存採用org.springframework.boot.actuate.trace.InMemoryTraceRepository實現的記憶體方式,始終保留最近的100條請求記錄。
/auditevents
顯示應用暴露的審計事件 (比如認證進入、訂單失敗)
loggers 和 /loggers/{name}3
顯示和修改配置的loggers。它展示了應用中可配置的loggers的列表和相關的日誌等級。
你同樣能夠使用 /loggers/{name} 來展示特定logger的細節。例如,你可以使用 /loggers/ROOT:
/loggers 這個端點不止可以檢視 Logger 等級,還可以修改執行時 Logger 的等級。例如,你可以用 POST 呼叫/loggers/ROOT ,並傳遞如下引數:
{
"configuredLevel": "DEBUG"
}
我們再回過頭來檢視 ROOT 的 Loggers 等級時,已經修改為如下狀態:
/heapdump
返回一個GZip壓縮的JVM堆dump。
- 介紹HeapDumpWebEndpoint原理: https://www.jianshu.com/p/6df45fed02fa
- 分析dump檔案: https://www.cnblogs.com/liangzs/p/8489321.html
- 分析dump檔案: https://blog.csdn.net/albertfly/article/details/78686408
- 分析dump檔案: https://www.javatang.com/archives/2017/10/30/53562102.html
- 分析dump檔案: https://www.cnblogs.com/toSeeMyDream/p/7151635.html
/threaddump
執行一個執行緒dump。
分析工具和方法: https://blog.csdn.net/hivon/article/details/8331350
/scheduledtasks
顯示應用中的排程任務。