[[411075]]

本文轉載自微信公眾號「程序新視界」，作者丑胖俠二師兄。轉載本文請聯系程序新視界公眾號。

前言

在微服務系統架構中，服務的監控是必不可少的。目前大多數微服務應用又是基于Spring Cloud系列，也可以說是基于Spring Boot系列的。此時使用Spring Boot Actuator來進行微服務的監控，不僅功能全面，而且非常方便。

在上篇文章《Spring Boot Actuator集成，難的是靈活運用!》中我們已經介紹了如何將Actuator集成到Spring Boot項目中，并且介紹了如何自定義Endpoint(端點)。有朋友留言說不夠深入，那么，本篇文章呢，我們將介紹Actuator原生端點的功能及基本使用場景。

Endpoints 介紹

Actuator中所謂的 Endpoints (翻譯為端點)提供了外部來與應用程序進行訪問和交互的功能。比如說/health端點提供了應用健康情況的信息，metrics 端點提供了應用程序的指標(JVM 內存使用、系統CPU使用等)信息。

Actuator原生的端點可分為三大類：

• 應用配置類：獲取應用程序中加載的應用配置、環境變量、自動化配置報告等與Spring Boot應用密切相關的配置類信息。
• 度量指標類：獲取應用程序運行過程中用于監控的度量指標，比如：內存信息、線程池信息、HTTP請求統計等。
• 操作控制類：提供了對應用的關閉等操作類功能。

不同版本的Actuator提供的原生端點有所出入，在使用的過程中最好以所使用版本的官方文檔為準。同時，每個原生的端點都可以通過配置來單獨的禁用或啟用。

而在Actuator 2.x 中默認端點增加了/actuator前綴，同時默認只暴露的兩個端點為/actuator/health和 /actuator/info。關于端點暴露的配置，可參考前一篇文章。下面基于Spring Boot 2.2.2.RELEASE版本來重點講解每個端點的功能和應用場景。

actuator端點

Actuator 2.x新增的默認端點，用于展示目前應用中暴露出來的端點匯總，你可以理解為可用端點的目錄。

訪問URL：http://localhost:8080/actuator ，對應展示結果如下圖：

上述只展示了一部分的端點，返回結果為JSON，這里采用了瀏覽器的JSON插件JSON-Handler進行了格式美化。通過actuator可以直觀的看出目前開放了哪些端點，以及這些端點的名稱和請求路徑。

下面我們就按照顯示actuator端點展示的列表逐一介紹。

auditevents端點

auditevents端點用于顯示應用暴露的審計事件 (比如認證進入、訂單失敗)，即使我們打開了所有端點，默認情況下也是看不到這個端點的。因為使用它的前提是需要在Spring容器中存在一個類型為AuditEventRepository的Bean的。

查看了網絡上大多數教程，基本上都是介紹了auditevents端點功能，而未展示具體實例。筆者經過多方嘗試，終于給大家寫了一個案例出來。

首先涉及到權限認證，需要先引入spring-boot-starter-security依賴：

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

 

單純添加這個依賴還是不夠的，還需要加入security的配置，不然AuthorizationAuditListener,AuthenticationAuditListener 監聽什么事件呢? 因此,我們加入如下代碼：

@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默認的登錄界面和權限控制，也就是說所有的訪問都需要進行登錄。而登錄的用戶名和密碼均為admin。

另外，前面提到需要用到AuditEventRepository的Bean，這里初始化一個對應的Bean：

@Configuration 
public class AuditEventConfig { 
 
   @Bean 
   public InMemoryAuditEventRepository repository(){ 
      return new InMemoryAuditEventRepository(); 
   } 
} 

InMemoryAuditEventRepository是AuditEventRepository接口的唯一實現類。

重啟項目，auditevents端點便可用了。訪問http://localhost:8080/actuator ,此時會跳轉到Security提供的登錄頁面：

輸入代碼中指定的用戶名和密碼，登錄成功，跳轉到/actuator頁面：

可以看到auditevents端點已經成功顯示出來了。新開頁面訪問http://localhost:8080/actuator/auditevents ，展示內容如下：

可以看到已經記錄下了權限相關的事件，其中第一次事件是我們直接訪問actuator端點時，由于之前為做權限認真，所以事件類型為"AUTHORIZATION_FAILURE"，也就是認證失敗。此時跳轉到登錄頁面，然后在登錄頁面輸入用戶名和密碼，登錄成功，對應的事件為"AUTHENTICATION_SUCCESS"。

也就是說auditevents記錄了用戶認證登錄系統相關的事件信息，包括時間戳、認證用戶、事件類型、訪問地址、sessionId等。

示例源碼地址：https://github.com/secbr/springboot-all/tree/master/springboot-actuator-auditevents 。

beans端點

/beans端點會返回Spring容器中所有bean的別名、類型、是否單例、依賴等信息。

訪問路徑為http://localhost:8080/actuator/beans，范圍結果如下：

這個端點會展示目前Spring容器中初始化的所有Bean，試想一下，如果你配置了一個Bean，但不確定是否成功實例化，是不是就可以通過這個端口查詢一下呢?

我們在項目中定義一個TestController，并注入一個UserService：

@Controller 
public class TestController { 
 
   @Resource 
   private UserService userService; 
} 

重新啟動并訪問該端點，會看到如下信息： 

可以看到TestController被實例化了，而且依賴于UserService。

caches端點

caches端點主要用于暴露應用程序中的緩沖。這里以Spring Boot提供的Cache組件來展示一下實例。

在項目中集成spring-boot-starter-cache，引入依賴：

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

 

然后在啟動類上添加@EnableCaching，開啟緩存功能。

定義一個CacheController，對其方法queryAll使用緩存機制：

@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注解來實現緩存功能，緩存的key為queryAll。此時，訪問http://localhost:8080/actuator/caches ，會展示緩存的根內容，但里面并沒有緩存。

訪問一下http://localhost:8080/queryAll ，也就是觸發一下緩存內容的生成。此時再訪問上面的鏈接，便可以看到應用程序中的緩存信息了：

可以看到，返回的內容不僅展示了應用程序的緩存管理器，同時也展示了緩存的Key和緩存數據存儲類型信息。

caches-cache端點

caches-cache端點是對上面caches端點的擴展，caches端點展示的所有的緩存信息。如果想直接看出具體的一個緩存信息，則可以使用caches-cache端點。

訪問的URL為：http://localhost:8080/actuator/caches/{cache}，其中大括號內的值可以替換為緩存的key。

http://localhost:8080/actuator/caches/queryAll

將上面的占位符換成queryAll(緩存的key)，執行結果如下：

可以看出，只查詢除了指定的緩存信息，包括緩存管理器、緩存名稱(key)，緩存的存儲類型。

health端點

health端點用來檢查應用的運行狀態，最高頻使用的一個端點。檢查應用實例的運行狀態以及應用不”健康“的原因，比如數據庫連接、磁盤空間不夠等。

訪問地址：http://localhost:8080/actuator/health

展示結果：

{ 
    "status": "UP" 
} 

上面的實例過于簡單，在項目中把數據庫給集成進去：

<!--數據庫連接相關--> 
<dependency> 
    <groupId>org.springframework.boot</groupId> 
    <artifactId>spring-boot-starter-jdbc</artifactId> 
</dependency> 
<dependency> 
    <groupId>mysql</groupId> 
    <artifactId>mysql-connector-java</artifactId> 
</dependency> 

 

然后在application配置文件中進行配置：

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的值。該屬性有三個可選項：

never ：不展示詳細信息，up 或者 down 的狀態，默認配置;

when-authorized：詳細信息將會展示給通過認證的用戶。授權的角色可以通過management.endpoint.health.roles 配置;

always：對所有用戶暴露詳細信息。

默認值是never，所以我們直接訪問看到的只有UP或DOWN。現在集成了數據庫，同時把該項值配置為always，看一下詳情：

可以看到整體狀態為UP，其中下面的三個組件均為UP，而數據庫是MYSQL，檢查數據庫的語句為“SELECT 1”。同時，還展示了磁盤信息和ping的狀態。

現在我們把數據庫的用戶名和密碼故意改錯，重啟訪問可得：

狀態為DOWN，組件中db出現了問題，狀態為DOWN。問題的詳情在error中展示，可以看出是建立連接時出錯了。在實踐中，我們可以通過health端口監控數據庫、Redis、MongoDB、磁盤等健康情況。Actuator預定義的處理類為：DataSourceHealthIndicator, DiskSpaceHealthIndicator, MongoHealthIndicator, RedisHealthIndicator等。

而且每個指標都可以單獨的進行開啟和關閉，以數據庫的為例：

management: 
  health: 
    db: 
      enabled: true 

info端點

/info 端點用來查看配置文件 application中以info開頭的配置信息，默認情況下 application中并沒有 info 節點配置，所以默認為空。

application中添加如下配置：

info: 
  user: 
    type: 公眾號 
    name: 程序新視界 
    wechat: zhuan2quan 

訪問http://localhost:8080/actuator/info ，展示結果如下：

conditions端點

Spring Boot提供了自動配置功能，使用起來非常方便。但這些自動配置類是什么情況下生效的，是否生效是比較難排查的。此時，可以使用 conditions 在應用運行時查看某個配置類在什么條件下生效，或為什么沒有生效。

訪問URL：http://localhost:8080/actuator/conditions ，部分返回信息如下：

可以看到某個自動配置類對應的生效條件和提示信息。

shutdown端點

shutdown端點屬于操作控制類端點，可以優雅關閉 Spring Boot 應用。需要在配置文件中開啟：

management: 
  endpoint: 
    shutdown: 
      enabled: true 

該端點只支持POST請求，執行命令及返回結果如下：

curl -X POST "http://localhost:8080/actuator/shutdown"  
{ 
    "message": "Shutting down, bye..." 
} 

執行之后，會發現應用程序已經被關閉了。由于該端點會關閉應用程序，因此使用時需要小心。

configprops端點

在Spring Boot項目中，我們經常會用到@ConfigurationProperties注解來批量注入一些屬性，而configprops端點就是用來顯示這些被該注解標注的配置類。

比如前面的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 ，部分信息如下：

不僅可以看到系統中默認集成的配置類信息，還可以看到我們自定義的配置類信息。這里需要注意的是對應的類需要進行實例化(@Component)這里才能夠看到。

我們自定義的類中返回了Bean的名稱、配置前綴。上面的ProjectInfoProperties還返回了屬性信息。

env端點

env端點用于獲取全部環境屬性，包括application配置文件中的內容、系統變量等。

訪問URL：http://localhost:8080/actuator/env ，返回部分信息：

env-toMatch端點

env-toMatch端點與caches和caches-cache類似，一個是獲取所有的，一個是獲取指定的。這里的env-toMatch端點是獲取指定key的環境變量屬性。

基本格式為：http://localhost:8080/actuator/env/{toMatch}。 實例URL：http://localhost:8080/actuator/env/info.user.name ，返回結果如下圖： 圖片

返回數據信息包括該屬性的來源、value值等信息。

loggers端點

/loggers 端點暴露了程序內部配置的所有 logger 的信息，包括不同的package、不同的類的日志級別信息。

訪問URL：http://localhost:8080/actuator/loggers ，部分返回結果：

loggers-name端點

loggers-name端點也是logger端點的細分，可以通過name訪問某一個logger。

基本請求格式：http://localhost:8080/actuator/loggers/{name} 示例請求URL：http://localhost:8080/actuator/loggers/com.secbro2.SpringbootActuatorApplication ，返回結果如下：

{ 
    "configuredLevel": null, 
    "effectiveLevel": "INFO" 
} 

可以看出，啟動類的日志級別為INFO。

heapdump端點

heapdump端點會返回一個JVM 堆dump，通過JVM自帶的監控工具VisualVM可打開此文件查看內存快照。這是內存優化，基于堆棧層面進行排查的利器。

訪問URL：http://localhost:8080/actuator/heapdump 。Mac操作系統下瀏覽器訪問會下載一個名字為heapdump的文件，無后綴，30M。

命令行執行jvisualvm命令，打開VisualVM，依次點擊“文件”、“裝入”，記得文件類型要選擇“堆Dump(.hprof,.*)”，然后選擇heapdump。

此時便可以通過工具來進行堆棧信息的分析了。對于線上問題的分析提供了極為便利的方式。

threaddump端點

/threaddump 端點會生成當前線程活動的快照。在日常定位問題的時候查看線程的情況非常有用，主要展示了線程名、線程ID、線程的狀態、是否等待鎖資源等信息。

訪問URL：http://localhost:8080/actuator/threaddump ，部分返回結果：

我們可通過線程快照來排查生產環境的問題。

metrics端點

/metrics 端點用來暴露當前應用的各類重要度量指標，比如：內存信息、線程信息、垃圾回收信息、tomcat、數據庫連接池等。2.x版本這里只顯示了一個指標的列表。

訪問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端點可以提供應用運行狀態的完整度量指標報告，這項功能非常的實用，但是對于監控系統中的各項監控功能，它們的監控內容、數據收集頻率都有所不同，如果我們每次都通過全量獲取報告的方式來收集，略顯粗暴。官方也是可能是處于此方面的考慮，在Spring Boot 2.x之后，/metrics端點只顯示了指標的列表。

如果需要查看具體的某項指標，則可通過/metrics-requiredMetricName端點來實現。

metrics-requiredMetricName端點

metrics-requiredMetricName端點，用于訪問指定指標的報告，一般會配合/metrics端點先查出指標列表，然后再查詢具體的某個指標。

基本格式：http://localhost:8080/actuator/metrics/{requiredMetricName}。 實例URL：http://localhost:8080/actuator/metrics/jvm.memory.max ，返回結果如下：

{ 
    "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" 
            ] 
        } 
    ] 
} 

上述結果展示了最大可用內存的情況。其他相關指標的展示替換對應的名字進行查看即可。

scheduledtasks端點

/scheduledtasks端點用于展示應用中的定時任務信息。

先在項目中構建兩個定時任務，首先在啟動類上添加@EnableScheduling開啟定時任務功能。然后創建定時任務類：

@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."); 
    } 
} 

其中定義了兩種類型的定時任務，work是基于cron實現的定時任務，work1是基于fixedDelay實現的定時任務。

訪問URL：http://localhost:8080/actuator/scheduledtasks ，返回結果信息如下：

{ 
    "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": [] 
} 

可以看到，通過該端點可以明確的知道當前應用中定義的定時任務，以及執行模式和頻次。

mappings端點

/mappings端點用于描述全部的 URI 路徑，以及和控制器的映射關系。這個功能算是比較常用的了，如果想系統的查看URL對應的Controller及方法，可以使用此端點。

訪問URL：http://localhost:8080/actuator/mappings ，部分返回結果如下：

至此關于Spring Boot Actuator提供的所有端點介紹完畢。

小結

 

本文通過對Spring Boot Actuator提供所有端點構建實例并演示結果，本文大多數內容和實例都是全網第一手資料。該框架對排查線上問題，性能優化等都有極大的幫助。而在寫本文的過程中也越來越驚嘆Actuator的功能之強大，強烈推薦用起來。