知識庫 / Spring / Spring Boot RSS 訂閱

使用此算法，如果將 Bean 名稱更改為 rand，則指標標識符將為 rand，而不是 random：

@Component("rand")
public class RandomHealthIndicator implements HealthIndicator {
    // omitted
}

4.2. 禁用指示器

要禁用特定的指示器，我們可以將 management.health.<indicator_identifier>.enabled 配置屬性設置為 false。 例如，如果我們在 application.properties 中添加以下內容，則 Spring Boot 將禁用 RandomHealthIndicator：

management.health.random.enabled=false

為了激活此配置屬性，我們還應在指示器上添加 @ConditionalOnEnabledHealthIndicator 註解：

@Component
@ConditionalOnEnabledHealthIndicator("random")
public class RandomHealthIndicator implements HealthIndicator { 
    // omitted
}

現在如果調用 /actuator/health/random，Spring Boot 將返回一個 404 Not Found HTTP 響應：

@SpringBootTest
@AutoConfigureMockMvc
@TestPropertySource(properties = "management.health.random.enabled=false")
class DisabledRandomHealthIndicatorIntegrationTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void givenADisabledIndicator_whenSendingRequest_thenReturns404() throws Exception {
        mockMvc.perform(get("/actuator/health/random"))
          .andExpect(status().isNotFound());
    }
}

請注意，禁用內置或自定義指示器也採用類似流程。因此，我們也可以將相同的配置應用於內置指示器。

4.3. 補充詳情

除了報告狀態之外，我們還可以使用 <a href="https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/actuate/health/Health.Builder.html#withDetail-java.lang.String-java.lang.Object-"><em withDetail(key, value)</em></a> 方法添加額外的鍵值對詳情。

public Health health() {
    double chance = ThreadLocalRandom.current().nextDouble();
    Health.Builder status = Health.up();
    if (chance > 0.9) {
        status = Health.down();
    }

    return status
      .withDetail("chance", chance)
      .withDetail("strategy", "thread-local")
      .build();
}

我們在此向狀態報告中添加了兩件信息。通過將一個 Map<String, Object>傳遞給 withDetails(map)方法，可以實現相同的結果：

Map<String, Object> details = new HashMap<>();
details.put("chance", chance);
details.put("strategy", "thread-local");
        
return status.withDetails(details).build();

現在如果我們調用 /actuator/health/random，我們可能會看到類似的內容：

{
  "status": "DOWN",
  "details": {
    "chance": 0.9883560157173152,
    "strategy": "thread-local"
  }
}

我們可以通過自動化測試來驗證這種行為：

mockMvc.perform(get("/actuator/health/random"))
  .andExpect(jsonPath("$.status").exists())
  .andExpect(jsonPath("$.details.strategy").value("thread-local"))
  .andExpect(jsonPath("$.details.chance").exists());

當與系統組件（如數據庫或磁盤）進行通信時，有時會發生異常。我們可以使用 `withException(ex)方法來報告這些異常：

if (chance > 0.9) {
    status.withException(new RuntimeException("Bad luck"));
}

我們還可以將異常傳遞到我們之前見過的 <em><a href="https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/actuate/health/Health.Builder.html#down-java.lang.Throwable-">down(ex)</a></em> 方法：

if (chance > 0.9) {
    status = Health.down(new RuntimeException("Bad Luck"));
}

現在健康報告將包含堆棧跟蹤信息。

{
  "status": "DOWN",
  "details": {
    "error": "java.lang.RuntimeException: Bad Luck",
    "chance": 0.9603739107139401,
    "strategy": "thread-local"
  }
}

4.4. 詳細信息暴露

管理端點健康檢查的 management.endpoint.health.show-details 配置屬性控制每個健康端點可以暴露的詳細程度。

例如，如果我們將此屬性設置為 always，則 Spring Boot 將始終在健康報告中返回 details 字段，就像上面的示例一樣。

另一方面，如果我們將此屬性設置為 never，則 Spring Boot 將始終從輸出中省略 details。 此外，when_authorized 值僅對授權用户暴露額外的 details。 用户在以下情況下被授權：

Health.Builder warning = Health.status("WARNING");

management.endpoint.health.status.http-mapping.down=500
management.endpoint.health.status.http-mapping.out_of_service=503
management.endpoint.health.status.http-mapping.warning=500

mockMvc.perform(get("/actuator/health/warning"))
  .andExpect(jsonPath("$.status").value("WARNING"))
  .andExpect(status().isInternalServerError());

@Component
public class CustomStatusCodeMapper implements HttpCodeStatusMapper {

    @Override
    public int getStatusCode(Status status) {
        if (status == Status.DOWN) {
            return 500;
        }
        
        if (status == Status.OUT_OF_SERVICE) {
            return 503;
        }
        
        if (status == Status.UNKNOWN) {
            return 500;
        }

        return 200;
    }
}

if (status.getCode().equals("WARNING")) {
    return 500;
}

相反，我們不應該使用HealthIndicator來衡量值、計數事件或測量持續時間。這就是為什麼我們有指標。簡單來説，指標是報告CPU使用率、負載平均值、堆大小、HTTP響應分佈等更好的工具。

6. 結論

在本文中，我們學習瞭如何向 actuator 健康端點貢獻更多健康信息。此外，我們深入探討了健康 API 的各個組件，例如 Health、Status 以及 HTTP 狀態映射的狀態。

為了總結一下，我們簡要討論了健康信息和指標之間的區別，以及何時使用它們。