Spring Boot Actuator的端點(diǎn)都怎么用？咱用事實(shí)說話！
本文轉(zhuǎn)載自微信公眾號「程序新視界」，作者丑胖俠二師兄。轉(zhuǎn)載本文請聯(lián)系程序新視界公眾號。
前言
在微服務(wù)系統(tǒng)架構(gòu)中，服務(wù)的監(jiān)控是必不可少的。目前大多數(shù)微服務(wù)應(yīng)用又是基于Spring Cloud系列，也可以說是基于Spring Boot系列的。此時使用Spring Boot Actuator來進(jìn)行微服務(wù)的監(jiān)控，不僅功能全面，而且非常方便。
在上篇文章《Spring Boot Actuator集成，難的是靈活運(yùn)用!》中我們已經(jīng)介紹了如何將Actuator集成到Spring Boot項(xiàng)目中，并且介紹了如何自定義Endpoint(端點(diǎn))。有朋友留言說不夠深入，那么，本篇文章呢，我們將介紹Actuator原生端點(diǎn)的功能及基本使用場景。
Endpoints 介紹
Actuator中所謂的 Endpoints (翻譯為端點(diǎn))提供了外部來與應(yīng)用程序進(jìn)行訪問和交互的功能。比如說/health端點(diǎn)提供了應(yīng)用健康情況的信息，metrics 端點(diǎn)提供了應(yīng)用程序的指標(biāo)(JVM 內(nèi)存使用、系統(tǒng)CPU使用等)信息。
Actuator原生的端點(diǎn)可分為三大類：
- 應(yīng)用配置類：獲取應(yīng)用程序中加載的應(yīng)用配置、環(huán)境變量、自動化配置報告等與Spring Boot應(yīng)用密切相關(guān)的配置類信息。
- 度量指標(biāo)類：獲取應(yīng)用程序運(yùn)行過程中用于監(jiān)控的度量指標(biāo)，比如：內(nèi)存信息、線程池信息、HTTP請求統(tǒng)計(jì)等。
- 操作控制類：提供了對應(yīng)用的關(guān)閉等操作類功能。
不同版本的Actuator提供的原生端點(diǎn)有所出入，在使用的過程中最好以所使用版本的官方文檔為準(zhǔn)。同時，每個原生的端點(diǎn)都可以通過配置來單獨(dú)的禁用或啟用。
而在Actuator 2.x 中默認(rèn)端點(diǎn)增加了/actuator前綴，同時默認(rèn)只暴露的兩個端點(diǎn)為/actuator/health和 /actuator/info。關(guān)于端點(diǎn)暴露的配置，可參考前一篇文章。下面基于Spring Boot 2.2.2.RELEASE版本來重點(diǎn)講解每個端點(diǎn)的功能和應(yīng)用場景。
actuator端點(diǎn)
Actuator 2.x新增的默認(rèn)端點(diǎn)，用于展示目前應(yīng)用中暴露出來的端點(diǎn)匯總，你可以理解為可用端點(diǎn)的目錄。
訪問URL：http://localhost:8080/actuator ，對應(yīng)展示結(jié)果如下圖：
上述只展示了一部分的端點(diǎn)，返回結(jié)果為JSON，這里采用了瀏覽器的JSON插件JSON-Handler進(jìn)行了格式美化。通過actuator可以直觀的看出目前開放了哪些端點(diǎn)，以及這些端點(diǎn)的名稱和請求路徑。
下面我們就按照顯示actuator端點(diǎn)展示的列表逐一介紹。
auditevents端點(diǎn)
auditevents端點(diǎn)用于顯示應(yīng)用暴露的審計(jì)事件 (比如認(rèn)證進(jìn)入、訂單失敗)，即使我們打開了所有端點(diǎn)，默認(rèn)情況下也是看不到這個端點(diǎn)的。因?yàn)槭褂盟那疤崾切枰赟pring容器中存在一個類型為AuditEventRepository的Bean的。
查看了網(wǎng)絡(luò)上大多數(shù)教程，基本上都是介紹了auditevents端點(diǎn)功能，而未展示具體實(shí)例。筆者經(jīng)過多方嘗試，終于給大家寫了一個案例出來。
首先涉及到權(quán)限認(rèn)證，需要先引入spring-boot-starter-security依賴：
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-security</artifactId>
- </dependency>
單純添加這個依賴還是不夠的，還需要加入security的配置，不然AuthorizationAuditListener,AuthenticationAuditListener 監(jiān)聽什么事件呢? 因此,我們加入如下代碼：
- @Configuration
- public class WebSecurityConfig extends WebSecurityConfigurerAdapter {
- @Override
- protected void configure(AuthenticationManagerBuilder auth) throws Exception {
- auth.inMemoryAuthentication()
- .withUser("admin")
- .password(bcryptPasswordEncoder().encode("admin"))
- .roles("admin");
- }
- @Bean
- public PasswordEncoder bcryptPasswordEncoder() {
- return new BCryptPasswordEncoder();
- }
- }
這里采用了security默認(rèn)的登錄界面和權(quán)限控制，也就是說所有的訪問都需要進(jìn)行登錄。而登錄的用戶名和密碼均為admin。
另外，前面提到需要用到AuditEventRepository的Bean，這里初始化一個對應(yīng)的Bean：
- @Configuration
- public class AuditEventConfig {
- @Bean
- public InMemoryAuditEventRepository repository(){
- return new InMemoryAuditEventRepository();
- }
- }
InMemoryAuditEventRepository是AuditEventRepository接口的唯一實(shí)現(xiàn)類。
重啟項(xiàng)目，auditevents端點(diǎn)便可用了。訪問http://localhost:8080/actuator ,此時會跳轉(zhuǎn)到Security提供的登錄頁面：
輸入代碼中指定的用戶名和密碼，登錄成功，跳轉(zhuǎn)到/actuator頁面：
可以看到auditevents端點(diǎn)已經(jīng)成功顯示出來了。新開頁面訪問http://localhost:8080/actuator/auditevents ，展示內(nèi)容如下：
可以看到已經(jīng)記錄下了權(quán)限相關(guān)的事件，其中第一次事件是我們直接訪問actuator端點(diǎn)時，由于之前為做權(quán)限認(rèn)真，所以事件類型為"AUTHORIZATION_FAILURE"，也就是認(rèn)證失敗。此時跳轉(zhuǎn)到登錄頁面，然后在登錄頁面輸入用戶名和密碼，登錄成功，對應(yīng)的事件為"AUTHENTICATION_SUCCESS"。
也就是說auditevents記錄了用戶認(rèn)證登錄系統(tǒng)相關(guān)的事件信息，包括時間戳、認(rèn)證用戶、事件類型、訪問地址、sessionId等。
示例源碼地址：https://github.com/secbr/springboot-all/tree/master/springboot-actuator-auditevents 。
beans端點(diǎn)
/beans端點(diǎn)會返回Spring容器中所有bean的別名、類型、是否單例、依賴等信息。
訪問路徑為http://localhost:8080/actuator/beans，范圍結(jié)果如下：
這個端點(diǎn)會展示目前Spring容器中初始化的所有Bean，試想一下，如果你配置了一個Bean，但不確定是否成功實(shí)例化，是不是就可以通過這個端口查詢一下呢?
我們在項(xiàng)目中定義一個TestController，并注入一個UserService：
- @Controller
- public class TestController {
- @Resource
- private UserService userService;
- }
重新啟動并訪問該端點(diǎn)，會看到如下信息：
可以看到TestController被實(shí)例化了，而且依賴于UserService。
caches端點(diǎn)
caches端點(diǎn)主要用于暴露應(yīng)用程序中的緩沖。這里以Spring Boot提供的Cache組件來展示一下實(shí)例。
在項(xiàng)目中集成spring-boot-starter-cache，引入依賴：
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-cache</artifactId>
- </dependency>
然后在啟動類上添加@EnableCaching，開啟緩存功能。
定義一個CacheController，對其方法queryAll使用緩存機(jī)制：
- @RestController
- public class CacheController {
- @RequestMapping("/queryAll")
- @Cacheable(value = "queryAll")
- public Map<String, String> queryAll() {
- Map<String, String> map = new HashMap<>();
- map.put("1", "Tom");
- map.put("2", "Steven");
- return map;
- }
- }
這里使用@Cacheable注解來實(shí)現(xiàn)緩存功能，緩存的key為queryAll。此時，訪問http://localhost:8080/actuator/caches ，會展示緩存的根內(nèi)容，但里面并沒有緩存。
訪問一下http://localhost:8080/queryAll ，也就是觸發(fā)一下緩存內(nèi)容的生成。此時再訪問上面的鏈接，便可以看到應(yīng)用程序中的緩存信息了：
可以看到，返回的內(nèi)容不僅展示了應(yīng)用程序的緩存管理器，同時也展示了緩存的Key和緩存數(shù)據(jù)存儲類型信息。
caches-cache端點(diǎn)
caches-cache端點(diǎn)是對上面caches端點(diǎn)的擴(kuò)展，caches端點(diǎn)展示的所有的緩存信息。如果想直接看出具體的一個緩存信息，則可以使用caches-cache端點(diǎn)。
訪問的URL為：http://localhost:8080/actuator/caches/{cache}，其中大括號內(nèi)的值可以替換為緩存的key。
http://localhost:8080/actuator/caches/queryAll
將上面的占位符換成queryAll(緩存的key)，執(zhí)行結(jié)果如下：
可以看出，只查詢除了指定的緩存信息，包括緩存管理器、緩存名稱(key)，緩存的存儲類型。
health端點(diǎn)
health端點(diǎn)用來檢查應(yīng)用的運(yùn)行狀態(tài)，最高頻使用的一個端點(diǎn)。檢查應(yīng)用實(shí)例的運(yùn)行狀態(tài)以及應(yīng)用不”健康“的原因，比如數(shù)據(jù)庫連接、磁盤空間不夠等。
訪問地址：http://localhost:8080/actuator/health
展示結(jié)果：
- {
- "status": "UP"
- }
上面的實(shí)例過于簡單，在項(xiàng)目中把數(shù)據(jù)庫給集成進(jìn)去：
- <!--數(shù)據(jù)庫連接相關(guān)-->
- <dependency>
- <groupId>org.springframework.boot</groupId>
- <artifactId>spring-boot-starter-jdbc</artifactId>
- </dependency>
- <dependency>
- <groupId>mysql</groupId>
- <artifactId>mysql-connector-java</artifactId>
- </dependency>
然后在application配置文件中進(jìn)行配置：
- spring:
- datasource:
- url: jdbc:mysql://xxx:3333/xxx?characterEncoding=utf8&serverTimezone=Asia/Shanghai
- username: root
- password: root
- driver-class-name: com.mysql.cj.jdbc.Driver
同時，我們要在application配置文件中配置一下management.endpoint.health.show-details的值。該屬性有三個可選項(xiàng)：
never ：不展示詳細(xì)信息，up 或者 down 的狀態(tài)，默認(rèn)配置;
when-authorized：詳細(xì)信息將會展示給通過認(rèn)證的用戶。授權(quán)的角色可以通過management.endpoint.health.roles 配置;
always：對所有用戶暴露詳細(xì)信息。
默認(rèn)值是never，所以我們直接訪問看到的只有UP或DOWN?，F(xiàn)在集成了數(shù)據(jù)庫，同時把該項(xiàng)值配置為always，看一下詳情：
可以看到整體狀態(tài)為UP，其中下面的三個組件均為UP，而數(shù)據(jù)庫是MYSQL，檢查數(shù)據(jù)庫的語句為“SELECT 1”。同時，還展示了磁盤信息和ping的狀態(tài)。
現(xiàn)在我們把數(shù)據(jù)庫的用戶名和密碼故意改錯，重啟訪問可得：
狀態(tài)為DOWN，組件中db出現(xiàn)了問題，狀態(tài)為DOWN。問題的詳情在error中展示，可以看出是建立連接時出錯了。在實(shí)踐中，我們可以通過health端口監(jiān)控?cái)?shù)據(jù)庫、Redis、MongoDB、磁盤等健康情況。Actuator預(yù)定義的處理類為：DataSourceHealthIndicator, DiskSpaceHealthIndicator, MongoHealthIndicator, RedisHealthIndicator等。
而且每個指標(biāo)都可以單獨(dú)的進(jìn)行開啟和關(guān)閉，以數(shù)據(jù)庫的為例：
- management:
- health:
- db:
- enabled: true
info端點(diǎn)
/info 端點(diǎn)用來查看配置文件 application中以info開頭的配置信息，默認(rèn)情況下 application中并沒有 info 節(jié)點(diǎn)配置，所以默認(rèn)為空。
application中添加如下配置：
- info:
- user:
- type: 公眾號
- name: 程序新視界
- wechat: zhuan2quan
訪問http://localhost:8080/actuator/info ，展示結(jié)果如下：
conditions端點(diǎn)
Spring Boot提供了自動配置功能，使用起來非常方便。但這些自動配置類是什么情況下生效的，是否生效是比較難排查的。此時，可以使用 conditions 在應(yīng)用運(yùn)行時查看某個配置類在什么條件下生效，或?yàn)槭裁礇]有生效。
訪問URL：http://localhost:8080/actuator/conditions ，部分返回信息如下：
可以看到某個自動配置類對應(yīng)的生效條件和提示信息。
shutdown端點(diǎn)
shutdown端點(diǎn)屬于操作控制類端點(diǎn)，可以優(yōu)雅關(guān)閉 Spring Boot 應(yīng)用。需要在配置文件中開啟：
- management:
- endpoint:
- shutdown:
- enabled: true
該端點(diǎn)只支持POST請求，執(zhí)行命令及返回結(jié)果如下：
- curl -X POST "http://localhost:8080/actuator/shutdown"
- {
- "message": "Shutting down, bye..."
- }
執(zhí)行之后，會發(fā)現(xiàn)應(yīng)用程序已經(jīng)被關(guān)閉了。由于該端點(diǎn)會關(guān)閉應(yīng)用程序，因此使用時需要小心。
configprops端點(diǎn)
在Spring Boot項(xiàng)目中，我們經(jīng)常會用到@ConfigurationProperties注解來批量注入一些屬性，而configprops端點(diǎn)就是用來顯示這些被該注解標(biāo)注的配置類。
比如前面的info配置，我們就可以定義一個類InfoProperties：
- @Component
- @ConfigurationProperties(prefix = "info")
- public class InfoProperties {
- private String type;
- private String name;
- private String wechat;
- // 省略getter/setter
- }
訪問URL：http://localhost:8080/actuator/configprops ，部分信息如下：
不僅可以看到系統(tǒng)中默認(rèn)集成的配置類信息，還可以看到我們自定義的配置類信息。這里需要注意的是對應(yīng)的類需要進(jìn)行實(shí)例化(@Component)這里才能夠看到。
我們自定義的類中返回了Bean的名稱、配置前綴。上面的ProjectInfoProperties還返回了屬性信息。
env端點(diǎn)
env端點(diǎn)用于獲取全部環(huán)境屬性，包括application配置文件中的內(nèi)容、系統(tǒng)變量等。
訪問URL：http://localhost:8080/actuator/env ，返回部分信息：
env-toMatch端點(diǎn)
env-toMatch端點(diǎn)與caches和caches-cache類似，一個是獲取所有的，一個是獲取指定的。這里的env-toMatch端點(diǎn)是獲取指定key的環(huán)境變量屬性。
基本格式為：http://localhost:8080/actuator/env/{toMatch}。 實(shí)例URL：http://localhost:8080/actuator/env/info.user.name ，返回結(jié)果如下圖： 圖片
返回?cái)?shù)據(jù)信息包括該屬性的來源、value值等信息。
loggers端點(diǎn)
/loggers 端點(diǎn)暴露了程序內(nèi)部配置的所有 logger 的信息，包括不同的package、不同的類的日志級別信息。
訪問URL：http://localhost:8080/actuator/loggers ，部分返回結(jié)果：
loggers-name端點(diǎn)
loggers-name端點(diǎn)也是logger端點(diǎn)的細(xì)分，可以通過name訪問某一個logger。
基本請求格式：http://localhost:8080/actuator/loggers/{name} 示例請求URL：http://localhost:8080/actuator/loggers/com.secbro2.SpringbootActuatorApplication ，返回結(jié)果如下：
- {
- "configuredLevel": null,
- "effectiveLevel": "INFO"
- }
可以看出，啟動類的日志級別為INFO。
heapdump端點(diǎn)
heapdump端點(diǎn)會返回一個JVM 堆dump，通過JVM自帶的監(jiān)控工具VisualVM可打開此文件查看內(nèi)存快照。這是內(nèi)存優(yōu)化，基于堆棧層面進(jìn)行排查的利器。
訪問URL：http://localhost:8080/actuator/heapdump 。Mac操作系統(tǒng)下瀏覽器訪問會下載一個名字為heapdump的文件，無后綴，30M。
命令行執(zhí)行jvisualvm命令，打開VisualVM，依次點(diǎn)擊“文件”、“裝入”，記得文件類型要選擇“堆Dump(.hprof,.*)”，然后選擇heapdump。
此時便可以通過工具來進(jìn)行堆棧信息的分析了。對于線上問題的分析提供了極為便利的方式。
threaddump端點(diǎn)
/threaddump 端點(diǎn)會生成當(dāng)前線程活動的快照。在日常定位問題的時候查看線程的情況非常有用，主要展示了線程名、線程ID、線程的狀態(tài)、是否等待鎖資源等信息。
訪問URL：http://localhost:8080/actuator/threaddump ，部分返回結(jié)果：
我們可通過線程快照來排查生產(chǎn)環(huán)境的問題。
metrics端點(diǎn)
/metrics 端點(diǎn)用來暴露當(dāng)前應(yīng)用的各類重要度量指標(biāo)，比如：內(nèi)存信息、線程信息、垃圾回收信息、tomcat、數(shù)據(jù)庫連接池等。2.x版本這里只顯示了一個指標(biāo)的列表。
訪問URL：http://localhost:8080/actuator/metrics 。
- {
- "names": [
- "jvm.memory.max",
- "jvm.threads.states",
- "jvm.gc.pause",
- "http.server.requests",
- "process.files.max",
- "jvm.gc.memory.promoted",
- "system.load.average.1m",
- "jvm.memory.used",
- "jvm.gc.max.data.size",
- "jvm.memory.committed",
- "system.cpu.count",
- "logback.events",
- "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",
- "process.files.open",
- "jvm.buffer.count",
- "jvm.buffer.total.capacity",
- "tomcat.sessions.active.max",
- "process.start.time"
- ]
- }
/metrics端點(diǎn)可以提供應(yīng)用運(yùn)行狀態(tài)的完整度量指標(biāo)報告，這項(xiàng)功能非常的實(shí)用，但是對于監(jiān)控系統(tǒng)中的各項(xiàng)監(jiān)控功能，它們的監(jiān)控內(nèi)容、數(shù)據(jù)收集頻率都有所不同，如果我們每次都通過全量獲取報告的方式來收集，略顯粗暴。官方也是可能是處于此方面的考慮，在Spring Boot 2.x之后，/metrics端點(diǎn)只顯示了指標(biāo)的列表。
如果需要查看具體的某項(xiàng)指標(biāo)，則可通過/metrics-requiredMetricName端點(diǎn)來實(shí)現(xiàn)。
metrics-requiredMetricName端點(diǎn)
metrics-requiredMetricName端點(diǎn)，用于訪問指定指標(biāo)的報告，一般會配合/metrics端點(diǎn)先查出指標(biāo)列表，然后再查詢具體的某個指標(biāo)。
基本格式：http://localhost:8080/actuator/metrics/{requiredMetricName}。 實(shí)例URL：http://localhost:8080/actuator/metrics/jvm.memory.max ，返回結(jié)果如下：
- {
- "name": "jvm.memory.max",
- "description": "The maximum amount of memory in bytes that can be used for memory management",
- "baseUnit": "bytes",
- "measurements": [
- {
- "statistic": "VALUE",
- "value": 5606211583
- }
- ],
- "availableTags": [
- {
- "tag": "area",
- "values": [
- "heap",
- "nonheap"
- ]
- },
- {
- "tag": "id",
- "values": [
- "Compressed Class Space",
- "PS Survivor Space",
- "PS Old Gen",
- "Metaspace",
- "PS Eden Space",
- "Code Cache"
- ]
- }
- ]
- }
上述結(jié)果展示了最大可用內(nèi)存的情況。其他相關(guān)指標(biāo)的展示替換對應(yīng)的名字進(jìn)行查看即可。
scheduledtasks端點(diǎn)
/scheduledtasks端點(diǎn)用于展示應(yīng)用中的定時任務(wù)信息。
先在項(xiàng)目中構(gòu)建兩個定時任務(wù)，首先在啟動類上添加@EnableScheduling開啟定時任務(wù)功能。然后創(chuàng)建定時任務(wù)類：
- @Component
- public class MyTask {
- @Scheduled(cron = "0/10 * * * * *")
- public void work() {
- System.out.println("I am a cron job.");
- }
- @Scheduled(fixedDelay = 10000)
- public void work1() {
- System.out.println("I am a fixedDelay job.");
- }
- }
其中定義了兩種類型的定時任務(wù)，work是基于cron實(shí)現(xiàn)的定時任務(wù)，work1是基于fixedDelay實(shí)現(xiàn)的定時任務(wù)。
訪問URL：http://localhost:8080/actuator/scheduledtasks ，返回結(jié)果信息如下：
- {
- "cron": [
- {
- "runnable": {
- "target": "com.secbro2.job.MyTask.work"
- },
- "expression": "0/10 * * * * *"
- }
- ],
- "fixedDelay": [
- {
- "runnable": {
- "target": "com.secbro2.job.MyTask.work1"
- },
- "initialDelay": 0,
- "interval": 10000
- }
- ],
- "fixedRate": [],
- "custom": []
- }
可以看到，通過該端點(diǎn)可以明確的知道當(dāng)前應(yīng)用中定義的定時任務(wù)，以及執(zhí)行模式和頻次。
mappings端點(diǎn)
/mappings端點(diǎn)用于描述全部的 URI 路徑，以及和控制器的映射關(guān)系。這個功能算是比較常用的了，如果想系統(tǒng)的查看URL對應(yīng)的Controller及方法，可以使用此端點(diǎn)。
訪問URL：http://localhost:8080/actuator/mappings ，部分返回結(jié)果如下：
至此關(guān)于Spring Boot Actuator提供的所有端點(diǎn)介紹完畢。
小結(jié)
本文通過對Spring Boot Actuator提供所有端點(diǎn)構(gòu)建實(shí)例并演示結(jié)果，本文大多數(shù)內(nèi)容和實(shí)例都是全網(wǎng)第一手資料。該框架對排查線上問題，性能優(yōu)化等都有極大的幫助。而在寫本文的過程中也越來越驚嘆Actuator的功能之強(qiáng)大，強(qiáng)烈推薦用起來。
