MENU
  1. ホーム
  2. Java
  3. Spring Bootでのカスタムヘルスチェックエンドポイントの作成方法を徹底解説

Spring Bootでのカスタムヘルスチェックエンドポイントの作成方法を徹底解説

Java

Spring Bootを使用する際、アプリケーションの健全性を監視することは、システムの安定稼働において非常に重要です。標準的なヘルスチェックエンドポイントは、Spring Boot Actuatorが提供する機能の一部として活用されますが、時にはアプリケーション特有の要件に応じたカスタムヘルスチェックが必要になることがあります。例えば、特定の外部サービスへの接続状況や、データベースの特定テーブルの状態を監視したい場合です。

本記事では、Spring Bootを用いてカスタムヘルスチェックエンドポイントを作成する手順を詳しく解説し、実運用で役立つ具体的な方法を紹介します。

目次
  1. ヘルスチェックの基本概念
  2. カスタムヘルスチェックの必要性
    1. 外部サービスの依存状況
    2. データの一貫性の確認
    3. カスタムアプリケーションロジックの監視
  3. Spring Bootでのヘルスインジケーターの作成
    1. HealthIndicatorインターフェースの基本構造
    2. Healthのビルダーを活用
  4. サンプルコード：カスタムヘルスチェックの実装
    1. カスタムヘルスチェックの実装例
    2. 説明
    3. Spring Boot Actuatorでの確認
  5. カスタムヘルスチェックでの条件設定
    1. 応答時間に基づく条件設定
    2. システムリソースに基づく条件設定
    3. まとめ
  6. 複数のカスタムヘルスチェックの統合
    1. 複数のカスタムヘルスチェックの統合方法
    2. カスタムヘルスインジケーターの例
    3. 統合されたヘルスチェック結果の表示
    4. 各ヘルスインジケーターの状態を独立して確認
    5. まとめ
  7. ヘルスチェックのセキュリティ考慮点
    1. ヘルスチェックエンドポイントのアクセス制御
    2. エンドポイントの情報を制限する
    3. ヘルスチェックエンドポイントの限定公開
    4. まとめ
  8. カスタムメトリクスと連携したヘルスチェック
    1. メトリクスの基本概念
    2. カスタムメトリクスの作成
    3. カスタムメトリクスとヘルスチェックの連携
    4. カスタムメトリクスのエクスポートと監視
    5. カスタムメトリクスを使ったトラブルシューティング
    6. まとめ
  9. 運用時のカスタムヘルスチェックの監視
    1. 監視ツールの導入
    2. アラートの設定
    3. エンドポイントの定期監視
    4. ロギングと監査ログの活用
    5. ダッシュボードの構築
    6. まとめ
  10. カスタムヘルスチェックのテスト方法
    1. ユニットテストによる検証
    2. 統合テストによるシステム全体の確認
    3. モックを使った外部依存関係のテスト
    4. まとめ
  11. まとめ

ヘルスチェックの基本概念

ヘルスチェックとは、アプリケーションの健全性を定期的に監視し、その状態を外部のシステムやツールに報告する仕組みを指します。健全性の指標には、アプリケーションが正常に動作しているか、外部サービスやリソース（データベース、メッセージキューなど）が正しく接続されているかなどが含まれます。

Spring Bootでは、Spring Boot Actuatorという機能が標準でヘルスチェックを提供しており、アプリケーションの健全性を確認できるエンドポイント（/actuator/health）が自動的に作成されます。Actuatorは、CPU使用率やメモリの状態、データベースの接続状態など、システムに関連するさまざまなヘルス情報を取得し、JSON形式で出力します。

Spring Bootの標準機能により、基本的なシステム監視は容易に行えますが、特定のビジネスロジックやアプリケーション固有の監視項目が必要な場合には、カスタムヘルスチェックを実装することが必要になります。

カスタムヘルスチェックの必要性

標準的なヘルスチェックはシステム全体の健全性を確認するには便利ですが、アプリケーションの特定の要件に応じたヘルスチェックが必要になる場合があります。例えば、以下のようなシナリオではカスタムヘルスチェックが有効です。

外部サービスの依存状況

アプリケーションが外部のAPIやサービスに依存している場合、そのサービスが正常に動作しているかを確認する必要があります。標準のヘルスチェックではこれらの依存サービスの状態をカバーできないため、カスタムヘルスチェックを使用して、特定のサービスが応答しない場合や遅延が発生した際にその状態を記録できます。

データの一貫性の確認

データベースが動作しているだけでは十分でないケースがあります。たとえば、特定のテーブルのレコード数が異常に増加していないか、または一定期間データが更新されていないかを監視する必要がある場合です。これにより、ビジネスロジックに影響を与える潜在的な問題を早期に検出することができます。

カスタムアプリケーションロジックの監視

特定のバッチジョブやキュー処理の状況、あるいはバックグラウンドで動作する重要なプロセスの健全性を監視するため、カスタムヘルスチェックを実装することで、問題が発生した際に速やかに対処することができます。

カスタムヘルスチェックは、アプリケーションの特定のニーズや運用要件に応じて監視項目を追加することで、より高精度なシステムの監視が可能になります。

Spring Bootでのヘルスインジケーターの作成

Spring Bootでは、HealthIndicatorインターフェースを実装することで、カスタムヘルスチェックを簡単に作成できます。HealthIndicatorは、特定のリソースやサービスの状態をチェックし、その結果をヘルスステータスとして返す役割を担います。カスタムヘルスチェックを作成するためには、このインターフェースを使って独自のロジックを実装します。

HealthIndicatorインターフェースの基本構造

HealthIndicatorインターフェースを実装するクラスは、health()メソッドをオーバーライドし、その中でチェックしたいリソースやサービスの状態を確認します。このメソッドは、Healthオブジェクトを返し、その中にヘルスステータスと、必要であれば追加の詳細情報を含めます。

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class CustomHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        // ヘルスチェックロジック
        boolean isHealthy = checkCustomService();

        if (isHealthy) {
            return Health.up().withDetail("Custom Service", "Available").build();
        } else {
            return Health.down().withDetail("Custom Service", "Unavailable").build();
        }
    }

    // サービスやリソースの状態確認ロジック
    private boolean checkCustomService() {
        // ここに具体的なチェックロジックを実装
        return true; // 状態が正常かどうかを返す
    }
}

このように、HealthIndicatorインターフェースを実装したクラスを作成し、@Componentアノテーションを付けることで、Spring Bootは自動的にカスタムヘルスチェックエンドポイントに組み込みます。

Healthのビルダーを活用

Healthオブジェクトには、正常な状態（up()）、異常な状態（down()）、警告状態（status()）などを設定できます。さらに、詳細なデバッグ情報を付加するためにwithDetail()メソッドを使用して、状態や原因を詳しく表示することも可能です。

サンプルコード：カスタムヘルスチェックの実装

実際にカスタムヘルスチェックエンドポイントを作成する具体的な手順を、サンプルコードと共に見ていきます。ここでは、外部のデータベース接続や特定の外部APIへの接続を確認するヘルスチェックを例にします。

カスタムヘルスチェックの実装例

以下のサンプルコードでは、特定の外部APIが正常に動作しているかを監視するカスタムヘルスチェックを実装します。このヘルスチェックは、外部APIに対して接続を試み、そのレスポンスが正常かどうかを確認します。

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;

@Component
public class ApiHealthIndicator implements HealthIndicator {

    private final RestTemplate restTemplate = new RestTemplate();
    private static final String API_URL = "https://api.example.com/health";

    @Override
    public Health health() {
        try {
            // 外部APIに接続してステータスを確認
            String response = restTemplate.getForObject(API_URL, String.class);
            if ("OK".equals(response)) {
                return Health.up().withDetail("External API", "Available").build();
            } else {
                return Health.down().withDetail("External API", "Unhealthy Response").build();
            }
        } catch (Exception e) {
            // エラーが発生した場合、ダウンステータスを返す
            return Health.down(e).withDetail("External API", "Unavailable").build();
        }
    }
}

説明

  1. RestTemplateの使用
    RestTemplateを用いて、指定した外部API（API_URL）に対してGETリクエストを送信し、そのレスポンスを取得しています。
  2. 正常なレスポンスの場合
    APIからのレスポンスが期待する「OK」であれば、Health.up()を使用してアプリケーションの状態を「正常（UP）」として返します。さらに、withDetail()メソッドで「External API」という詳細情報を付与しています。
  3. 異常なレスポンスやエラーの場合
    APIの応答が期待するものと異なる場合や、APIがダウンしている場合には、Health.down()を使用して「異常（DOWN）」ステータスを返します。また、例外が発生した場合には、そのエラー内容をステータスに含めて返しています。

Spring Boot Actuatorでの確認

このカスタムヘルスチェックをSpring Bootアプリケーションに組み込むと、/actuator/healthエンドポイントにアクセスすることで、カスタムヘルスチェックの結果が確認できます。カスタムで実装したヘルスインジケーターの結果も、標準のヘルス情報と共に表示されます。

例えば、以下のようなJSONが返されます：

{
    "status": "DOWN",
    "components": {
        "diskSpace": {
            "status": "UP",
            "details": {
                "total": 499963174912,
                "free": 366425206784,
                "threshold": 10485760
            }
        },
        "externalAPI": {
            "status": "DOWN",
            "details": {
                "External API": "Unavailable",
                "error": "java.net.ConnectException: Connection refused"
            }
        }
    }
}

このように、カスタムヘルスチェックを組み込むことで、外部APIやその他のリソースに問題が発生した際にすぐに検知することが可能になります。

カスタムヘルスチェックでの条件設定

カスタムヘルスチェックを実装する際には、単にサービスが動作しているかどうかを確認するだけでなく、特定の条件に基づいてアプリケーションの健全性を判断することが重要です。たとえば、データベースの負荷状況、メモリの使用量、特定のリソースのレスポンスタイムなどに基づいてステータスを制御することができます。

応答時間に基づく条件設定

特定のAPIや外部サービスに対する応答時間が遅くなると、アプリケーション全体に影響が出る可能性があります。この場合、応答時間が一定の閾値を超えた場合に「DOWN」ステータスを返すように設定することが考えられます。以下はその実装例です。

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;

@Component
public class ResponseTimeHealthIndicator implements HealthIndicator {

    private final RestTemplate restTemplate = new RestTemplate();
    private static final String API_URL = "https://api.example.com/health";
    private static final long TIMEOUT_THRESHOLD = 2000; // 応答時間の閾値（ミリ秒）

    @Override
    public Health health() {
        long startTime = System.currentTimeMillis();
        try {
            // 外部APIに接続
            restTemplate.getForObject(API_URL, String.class);
            long responseTime = System.currentTimeMillis() - startTime;

            if (responseTime < TIMEOUT_THRESHOLD) {
                return Health.up().withDetail("Response Time", responseTime + "ms").build();
            } else {
                return Health.down().withDetail("Response Time", responseTime + "ms").withDetail("Reason", "Slow response").build();
            }
        } catch (Exception e) {
            // エラーが発生した場合
            return Health.down(e).withDetail("Response Time", "Error").build();
        }
    }
}

実装のポイント

  1. 応答時間の計測
    外部APIにリクエストを送信する前後で、現在のシステム時刻を取得し、応答までにかかった時間を計測します。
  2. 閾値の設定
    設定した閾値（ここでは2000ミリ秒）を超えた場合は、Health.down()を使用して「DOWN」ステータスを返します。正常な応答であれば、Health.up()を返します。
  3. 追加情報の付与
    withDetail()メソッドを使って、応答時間や問題の原因を詳細としてレスポンスに含めることで、後からデバッグや問題解決が容易になります。

システムリソースに基づく条件設定

次に、システムリソース（例：メモリ使用率、CPU負荷など）に基づいてヘルスステータスを設定する方法を見ていきます。以下は、JavaのRuntimeクラスを使用してメモリの使用状況に基づいた条件を設定する例です。

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MemoryUsageHealthIndicator implements HealthIndicator {

    private static final long MEMORY_THRESHOLD = 500 * 1024 * 1024; // メモリ使用量の閾値（500MB）

    @Override
    public Health health() {
        long usedMemory = Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory();

        if (usedMemory < MEMORY_THRESHOLD) {
            return Health.up().withDetail("Memory Usage", usedMemory / (1024 * 1024) + "MB").build();
        } else {
            return Health.down().withDetail("Memory Usage", usedMemory / (1024 * 1024) + "MB").withDetail("Reason", "High memory usage").build();
        }
    }
}

実装のポイント

  1. メモリ使用状況の取得
    Runtime.getRuntime()を使って、JVMが使用しているメモリ量を取得します。totalMemory()とfreeMemory()メソッドを使用して、現在のメモリ使用量を計算します。
  2. 閾値に基づくステータスの決定
    メモリ使用量が設定した閾値（500MB）を超えた場合は、Health.down()を返し、正常であればHealth.up()を返します。
  3. 詳細な情報をレスポンスに追加
    withDetail()メソッドで、メモリ使用量や原因をレスポンスに含めることで、システムの状態をより詳細に把握できるようにします。

まとめ

カスタムヘルスチェックでの条件設定は、単にサービスが動作しているかどうかだけでなく、システムの健全性に影響を与える要素を詳細に監視するために非常に重要です。応答時間やリソース使用状況に基づいたチェックを行うことで、パフォーマンスの問題やリソース不足を早期に検知し、問題が深刻化する前に対処することが可能になります。

複数のカスタムヘルスチェックの統合

複数のカスタムヘルスチェックを実装し、それらを統合して全体的なシステムの健全性を確認することは、より包括的な監視を可能にします。Spring Boot Actuatorは、複数のカスタムヘルスチェックを自動的に集約し、全体のステータスを一つのヘルスエンドポイントで確認できるようにします。

複数のカスタムヘルスチェックの統合方法

Spring Bootでは、各カスタムヘルスチェックはそれぞれ独立したHealthIndicatorとして実装されます。ActuatorはこれらのHealthIndicatorを自動的に集約し、/actuator/healthエンドポイントにおいて、全体のシステムの健全性を統合して表示します。各ヘルスインジケーターは個別に評価され、すべてのヘルスインジケーターが「UP」であれば、全体も「UP」となります。逆に、1つでも「DOWN」のヘルスインジケーターがあれば、全体のステータスは「DOWN」となります。

カスタムヘルスインジケーターの例

以下に、複数のカスタムヘルスチェックを統合する例を示します。ここでは、メモリ使用状況と外部APIのステータスを個別に監視し、それらを統合して全体のステータスを確認します。

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MemoryHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        long usedMemory = Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory();
        long maxMemory = Runtime.getRuntime().maxMemory();
        if (usedMemory < maxMemory * 0.8) {
            return Health.up().withDetail("Memory Usage", usedMemory / (1024 * 1024) + "MB").build();
        } else {
            return Health.down().withDetail("Memory Usage", usedMemory / (1024 * 1024) + "MB").withDetail("Reason", "High memory usage").build();
        }
    }
}

@Component
public class ExternalApiHealthIndicator implements HealthIndicator {

    private final RestTemplate restTemplate = new RestTemplate();
    private static final String API_URL = "https://api.example.com/health";

    @Override
    public Health health() {
        try {
            String response = restTemplate.getForObject(API_URL, String.class);
            if ("OK".equals(response)) {
                return Health.up().withDetail("External API", "Available").build();
            } else {
                return Health.down().withDetail("External API", "Unhealthy Response").build();
            }
        } catch (Exception e) {
            return Health.down().withDetail("External API", "Unavailable").build();
        }
    }
}

これら2つのカスタムヘルスチェックは、1つはメモリの使用状況を監視し、もう1つは外部APIの状態を確認するものです。これらをSpring Boot Actuatorが自動的に統合し、全体の健全性をエンドポイントで確認できます。

統合されたヘルスチェック結果の表示

複数のヘルスインジケーターが統合された結果は、/actuator/healthエンドポイントにアクセスすることで確認できます。以下のようなJSON形式で、各カスタムヘルスインジケーターの状態が表示されます。

{
    "status": "DOWN",
    "components": {
        "memoryHealthIndicator": {
            "status": "UP",
            "details": {
                "Memory Usage": "512MB"
            }
        },
        "externalApiHealthIndicator": {
            "status": "DOWN",
            "details": {
                "External API": "Unavailable"
            }
        }
    }
}

この例では、メモリの状態は「UP」（正常）ですが、外部APIが利用できないため、externalApiHealthIndicatorの状態が「DOWN」と表示され、全体のステータスも「DOWN」となっています。

各ヘルスインジケーターの状態を独立して確認

/actuator/healthエンドポイントでは全体の統合された結果を確認できますが、各個別のヘルスチェック結果も詳細として確認できます。これにより、どの部分がシステムの障害の原因かを迅速に特定できます。

まとめ

複数のカスタムヘルスチェックを実装し、それらを統合して全体的なシステムの健全性を監視することは、複雑なシステムにおいて非常に効果的です。Spring Boot Actuatorを利用することで、個別のリソースやサービスの状態を自動的に集約し、簡単に統合されたステータスを確認できるため、問題の早期発見と対応が可能になります。

ヘルスチェックのセキュリティ考慮点

ヘルスチェックエンドポイントはシステムの健全性を監視するために非常に有用ですが、その情報には機密性がある場合があります。ヘルスチェックがシステムの内部情報（メモリ使用状況、データベース接続のステータス、外部APIの可用性など）を含むため、これらの情報が外部に公開されると、攻撃者に悪用されるリスクがあります。したがって、セキュリティを考慮して、ヘルスチェックエンドポイントを適切に保護することが重要です。

ヘルスチェックエンドポイントのアクセス制御

Spring Boot Actuatorのデフォルト設定では、/actuator/healthエンドポイントは公開されており、誰でもアクセス可能な状態になっています。このエンドポイントが不正アクセスされないように、適切なアクセス制御を設定することが必要です。以下に、エンドポイントのセキュリティを強化する方法を説明します。

認証と認可の設定

Spring Securityを使って、ヘルスチェックエンドポイントへのアクセスを認証されたユーザーのみに制限することができます。application.propertiesまたはapplication.ymlで次のように設定することで、特定のエンドポイントに対してアクセス制限をかけられます。

management:
  endpoints:
    web:
      exposure:
        include: health
  security:
    enabled: true

また、認証と認可を設定するために、Spring Securityのカスタム設定も加えることができます。

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/actuator/health").authenticated() // 認証が必要
            .and()
            .httpBasic(); // Basic認証
    }
}

この設定により、/actuator/healthエンドポイントには認証されたユーザーのみがアクセスできるようになります。さらに、必要に応じてBasic認証を有効にし、認証情報を使ってアクセス制御を行います。

エンドポイントの情報を制限する

場合によっては、完全なシステム情報を外部に公開せず、必要最低限の情報のみをヘルスチェックエンドポイントで提供することが望ましいです。たとえば、システムが正常かどうかだけを公開し、詳細なシステム状態は管理者にのみ見せるようにすることができます。

詳細情報の非表示設定

application.propertiesやapplication.ymlで次のように設定することで、ヘルスエンドポイントに含まれる詳細情報を非表示にできます。

management:
  endpoint:
    health:
      show-details: never  # 詳細情報を非表示

この設定により、/actuator/healthエンドポイントは、一般ユーザーに対してはシステムの状態（UP/DOWN）のみを返し、詳細な情報は表示されません。

詳細情報の制限付き公開

特定のユーザーやロールに対してのみ詳細情報を公開したい場合、以下のようにshow-detailsオプションを使用して制御できます。

management:
  endpoint:
    health:
      show-details: when_authorized  # 認証された場合のみ詳細を表示

これにより、認証されたユーザーに対してのみ詳細情報が表示され、一般のアクセスには公開されません。

ヘルスチェックエンドポイントの限定公開

さらにセキュリティを強化するために、ヘルスチェックエンドポイントを特定のネットワーク範囲内のみに公開することもできます。例えば、社内ネットワークや特定のIPアドレスからのみアクセスを許可する設定が可能です。

IPフィルタリングの設定

Spring Securityでカスタムフィルタを使い、特定のIPアドレスのみがエンドポイントにアクセスできるように制御する例です。

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            .antMatchers("/actuator/health").access("hasIpAddress('192.168.1.0/24')") // 特定IPのみ許可
            .and()
            .httpBasic();
    }
}

この設定により、指定したIPアドレスレンジ内からのリクエストのみが許可され、それ以外のアクセスは拒否されます。

まとめ

ヘルスチェックエンドポイントは、システムの重要な情報を提供するため、適切なセキュリティ対策を講じる必要があります。認証と認可を利用したアクセス制御や、エンドポイントに公開する情報の制限、特定のネットワークからのアクセスのみを許可するIPフィルタリングなどを活用して、エンドポイントを保護しましょう。これにより、システムの健全性を監視しながら、機密情報を保護することができます。

カスタムメトリクスと連携したヘルスチェック

カスタムメトリクスを使用してシステムのパフォーマンスや動作状況を詳細に監視し、これらのメトリクスとカスタムヘルスチェックを連携させることで、より高度で包括的なシステム監視が可能になります。Spring Boot Actuatorでは、メトリクスとヘルスチェックを統合することで、アプリケーションの健全性やパフォーマンスに関するより豊富な情報を取得できます。

メトリクスの基本概念

メトリクスは、アプリケーションやシステムの動作に関するさまざまな情報を定量的に測定するための指標です。Spring Bootでは、Actuatorを通じてCPU使用率、メモリ使用量、HTTPリクエスト数など、標準的なシステムメトリクスを収集できます。さらに、アプリケーション固有のカスタムメトリクスも追加して、システムの状態をより詳細に監視できます。

カスタムメトリクスの作成

Spring Bootでは、MeterRegistryを使用してカスタムメトリクスを登録できます。次の例では、特定のサービスへのリクエスト数を計測し、それをカスタムメトリクスとして登録する方法を示します。

import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.stereotype.Service;

@Service
public class CustomService {

    private final MeterRegistry meterRegistry;

    public CustomService(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        // メトリクスの登録
        meterRegistry.counter("custom.service.requests").increment();
    }

    public String performOperation() {
        // リクエストごとにカウンタをインクリメント
        meterRegistry.counter("custom.service.requests").increment();
        return "Operation completed";
    }
}

このコードでは、MeterRegistryを使用してカスタムメトリクス（custom.service.requests）を定義しています。このカウンタは、サービスの操作が実行されるたびにインクリメントされます。

カスタムメトリクスとヘルスチェックの連携

次に、カスタムメトリクスを使ってカスタムヘルスチェックと連携させる方法を見ていきます。例えば、特定の操作が異常に多く実行されている場合に、それを検知してヘルスチェックの状態を「DOWN」にするという条件を設定することができます。

import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class CustomMetricsHealthIndicator implements HealthIndicator {

    private final MeterRegistry meterRegistry;

    public CustomMetricsHealthIndicator(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
    }

    @Override
    public Health health() {
        // カスタムメトリクスの値を取得
        double requestCount = meterRegistry.counter("custom.service.requests").count();

        if (requestCount < 1000) {
            return Health.up().withDetail("Request Count", requestCount).build();
        } else {
            return Health.down().withDetail("Request Count", requestCount).withDetail("Reason", "Too many requests").build();
        }
    }
}

この例では、カスタムメトリクスで計測されたリクエスト数が1000回を超えた場合、ヘルスチェックが「DOWN」として返されます。このように、メトリクスをヘルスチェックと連携させることで、リクエスト数やその他のカスタム指標に基づいてアプリケーションの状態を動的に監視できます。

カスタムメトリクスのエクスポートと監視

Spring Boot Actuatorは、カスタムメトリクスをさまざまな監視システムにエクスポートするための機能を提供しています。これにより、Prometheus、Grafana、InfluxDBなどの外部ツールを使用して、カスタムメトリクスを収集・可視化できます。以下は、Prometheusにカスタムメトリクスをエクスポートする設定の例です。

management:
  endpoints:
    web:
      exposure:
        include: health, metrics, prometheus
  metrics:
    export:
      prometheus:
        enabled: true

この設定により、/actuator/prometheusエンドポイントが有効化され、カスタムメトリクスを含むすべてのメトリクスがPrometheus形式でエクスポートされます。

カスタムメトリクスを使ったトラブルシューティング

カスタムメトリクスとヘルスチェックの連携を通じて、アプリケーションの異常な状態を早期に検知し、トラブルシューティングを迅速に行うことが可能です。例えば、リクエスト数が急激に増加した場合、その原因を分析し、適切な対策を講じることができます。また、外部システムと連携することで、監視ツールからリアルタイムでアラートを受け取ることも可能です。

まとめ

カスタムメトリクスとヘルスチェックの連携は、Spring Boot Actuatorの強力な機能の1つです。これにより、アプリケーションのパフォーマンスや動作状況を詳細に監視し、リアルタイムで健全性を評価することができます。外部ツールとの連携を通じて、システムの監視体制をさらに強化し、異常を迅速に検知・対処できるようにしましょう。

運用時のカスタムヘルスチェックの監視

運用環境でカスタムヘルスチェックを実装することは、アプリケーションの安定性とパフォーマンスを維持するために不可欠です。カスタムヘルスチェックによって、アプリケーションの状態をリアルタイムで監視し、問題が発生した場合に即座に対応することが可能になります。ここでは、運用時にカスタムヘルスチェックを効果的に監視する方法について説明します。

監視ツールの導入

Spring Boot Actuatorのヘルスチェック結果は、標準で提供されているエンドポイントを介して簡単に監視ツールと統合できます。代表的な監視ツールとして以下のようなものがあります。

  • Prometheus：メトリクスデータを収集し、Grafanaなどのツールと連携してリアルタイムでアラートを発行できます。
  • Grafana：Prometheusなどからデータを取得し、視覚的にアプリケーションの状態を可視化することが可能です。
  • DatadogやNew Relic：商用の監視ソリューションであり、カスタムヘルスチェックやメトリクスをリアルタイムで監視・分析できます。

これらの監視ツールを使用することで、アプリケーションの状態を一目で把握でき、異常が発生した際にはアラートを受け取ることができます。

アラートの設定

運用中にシステム障害が発生した際、迅速な対応が求められます。監視ツールを使用してカスタムヘルスチェックに基づいたアラートを設定することで、問題の早期検出が可能になります。たとえば、PrometheusとGrafanaを使用して、次のような条件に基づいたアラートを設定できます。

  • 外部APIの応答が遅い：外部APIに対するヘルスチェックが「DOWN」ステータスを返した場合、リアルタイムでアラートを送信。
  • メモリ使用量が一定の閾値を超えた：カスタムメトリクスに基づいてメモリ使用量を監視し、閾値を超えた場合にアラートを発生。

これにより、システムが異常な動作を開始した際に、運用チームに通知が送られ、迅速に対処することが可能です。

エンドポイントの定期監視

カスタムヘルスチェックエンドポイントを監視するには、定期的にエンドポイントにアクセスし、アプリケーションの状態を確認することが推奨されます。これは、ヘルスチェック結果に応じて自動的に復旧措置を取ったり、アラートをトリガーするための重要なプロセスです。

たとえば、外部監視ツールを使用して、数分おきに/actuator/healthエンドポイントにアクセスし、ステータスが「DOWN」になった場合に特定の処理（リスタート、再接続など）を実行することができます。これにより、手動でシステムを監視する手間を省き、問題発生時のダウンタイムを最小限に抑えることができます。

ロギングと監査ログの活用

カスタムヘルスチェックの結果を監査ログとして記録し、後で問題のトラブルシューティングや分析に利用できるようにすることが推奨されます。Spring Bootのlogging機能を活用して、各ヘルスチェックの結果や異常発生時の詳細な情報をロギングすることが可能です。

logging:
  level:
    org.springframework.boot.actuate.health: INFO
    com.example.customhealth: DEBUG

このようにロギング設定を行うことで、ヘルスチェックの状態を詳細に記録し、異常発生時に原因を追跡することが容易になります。ログには、各エンドポイントのステータス、応答時間、エラーの詳細などを含めることができます。

ダッシュボードの構築

監視ツールを活用して、アプリケーションの健全性を一目で確認できるダッシュボードを構築することが重要です。Grafanaなどのツールを使用すれば、各カスタムヘルスチェックやメトリクスの状態を可視化し、運用チームがすぐに対応できる環境を整えることができます。

ダッシュボードには、以下のような情報を含めることができます。

  • ヘルスステータスの概要（UP/DOWN）
  • メモリやCPUの使用状況
  • 特定のリソースやサービスの状態
  • 異常時のアラート履歴や傾向

これにより、運用チームはリアルタイムでシステムの状態を把握し、問題発生時には迅速に対応できるようになります。

まとめ

運用時のカスタムヘルスチェックの監視は、システムの安定稼働を維持するために欠かせません。監視ツールやアラート機能を適切に活用し、エンドポイントの定期監視やロギング、ダッシュボードを構築することで、運用環境での問題を早期に発見し、対策を講じることが可能になります。これにより、システムダウンタイムを最小限に抑え、アプリケーションの健全性を維持できます。

カスタムヘルスチェックのテスト方法

カスタムヘルスチェックを実装する際には、その機能が期待通りに動作することを確認するために、十分なテストを行うことが重要です。Spring Bootでは、ユニットテストと統合テストの両方を使用して、カスタムヘルスチェックの動作を検証できます。ここでは、カスタムヘルスチェックのテスト方法について具体的に説明します。

ユニットテストによる検証

カスタムヘルスチェックは、特定の条件やシナリオに応じて「UP」または「DOWN」を返す必要があります。ユニットテストを使用して、これらの条件に基づく動作を個別にテストします。以下は、JUnitを使用したカスタムヘルスチェックのテスト例です。

import org.junit.jupiter.api.Test;
import org.springframework.boot.actuate.health.Health;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class CustomHealthIndicatorTest {

    private final CustomHealthIndicator healthIndicator = new CustomHealthIndicator();

    @Test
    public void testHealthStatusUp() {
        // 正常な条件でヘルスチェックがUPを返すかを確認
        Health health = healthIndicator.health();
        assertEquals(Health.up().build().getStatus(), health.getStatus());
    }

    @Test
    public void testHealthStatusDown() {
        // 異常な条件でヘルスチェックがDOWNを返すかを確認
        // ここでは、異常条件をセットしてテスト
        healthIndicator.setSimulateError(true); // エラーシミュレーション
        Health health = healthIndicator.health();
        assertEquals(Health.down().build().getStatus(), health.getStatus());
    }
}

ポイント

  1. 正常な状態のテスト: 正常な条件下でHealth.up()が返されることを確認します。
  2. 異常な状態のテスト: シミュレーションで異常を発生させた状態で、Health.down()が返されることを検証します。

ユニットテストでは、特定のコンポーネントやメソッドが期待通りに動作するかを確認し、カスタムヘルスチェックが正しく状態を報告できることを保証します。

統合テストによるシステム全体の確認

統合テストでは、実際にSpring Bootアプリケーションが起動した状態でカスタムヘルスチェックエンドポイントをテストします。以下のように、@SpringBootTestアノテーションを使ってエンドポイントの動作を確認できます。

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.boot.actuate.health.Status;
import static org.junit.jupiter.api.Assertions.assertEquals;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class HealthEndpointIntegrationTest {

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    public void testHealthEndpoint() {
        // ヘルスエンドポイントに対してリクエストを送信
        var response = restTemplate.getForEntity("/actuator/health", String.class);

        // レスポンスのステータスコードが200 OKであることを確認
        assertEquals(200, response.getStatusCodeValue());

        // 応答の内容にUPが含まれているかを確認
        assertEquals(true, response.getBody().contains(Status.UP.toString()));
    }
}

ポイント

  1. エンドポイントへのアクセス: /actuator/healthエンドポイントにリクエストを送り、そのステータスコードとレスポンス内容を確認します。
  2. ステータスの確認: 結果が「UP」であることをチェックし、システム全体の統合状態が正常かどうかを検証します。

モックを使った外部依存関係のテスト

カスタムヘルスチェックが外部サービスやAPIに依存している場合、外部の依存をシミュレートするためにモックを使用してテストを行うことが有効です。以下は、MockRestServiceServerを使用した外部API依存のテスト例です。

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.http.HttpStatus;
import org.springframework.test.web.client.MockRestServiceServer;
import org.springframework.web.client.RestTemplate;

import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withStatus;

@SpringBootTest
public class ExternalApiHealthIndicatorTest {

    @Autowired
    private RestTemplate restTemplate;

    @Autowired
    private CustomHealthIndicator customHealthIndicator;

    @Test
    public void testExternalApiHealthCheck() {
        MockRestServiceServer mockServer = MockRestServiceServer.createServer(restTemplate);
        mockServer.expect(requestTo("https://api.example.com/health"))
                  .andRespond(withStatus(HttpStatus.OK));

        // カスタムヘルスチェックの状態を確認
        Health health = customHealthIndicator.health();
        assertEquals(Health.up().build().getStatus(), health.getStatus());
    }
}

ポイント

  1. モックサーバの使用: MockRestServiceServerを使い、外部APIが正常に応答する状況をシミュレーションします。
  2. モックによるテスト: 外部サービスの挙動をコントロールすることで、カスタムヘルスチェックが正しく機能するかをテストします。

まとめ

カスタムヘルスチェックのテストは、アプリケーションの健全性を保証するために不可欠です。ユニットテストと統合テストを組み合わせることで、システム全体での正しい動作を確認し、外部依存関係をモックすることで実際の運用に近い環境でテストを行うことが可能です。テストを通じて、カスタムヘルスチェックが期待通りに動作し、運用環境でも確実にシステムの健全性を保つことができます。

まとめ

本記事では、Spring Bootでのカスタムヘルスチェックエンドポイントの作成方法について詳しく解説しました。カスタムヘルスチェックは、標準の機能だけではカバーできないアプリケーション固有の要件や外部サービスの監視に対応するために重要です。HealthIndicatorインターフェースを用いて簡単にカスタムヘルスチェックを実装し、複数のヘルスチェックを統合した監視や、セキュリティ対策、カスタムメトリクスとの連携も実現できます。

さらに、テストによるヘルスチェックの検証や、運用環境での監視手法を取り入れることで、アプリケーションの健全性を維持し、早期に問題を発見・対処することが可能です。これらの手法を活用して、より堅牢なシステム運用を目指しましょう。

Java
java Spring Boot カスタムヘルスチェック

コメント

コメントする

目次
  1. ヘルスチェックの基本概念
  2. カスタムヘルスチェックの必要性
    1. 外部サービスの依存状況
    2. データの一貫性の確認
    3. カスタムアプリケーションロジックの監視
  3. Spring Bootでのヘルスインジケーターの作成
    1. HealthIndicatorインターフェースの基本構造
    2. Healthのビルダーを活用
  4. サンプルコード：カスタムヘルスチェックの実装
    1. カスタムヘルスチェックの実装例
    2. 説明
    3. Spring Boot Actuatorでの確認
  5. カスタムヘルスチェックでの条件設定
    1. 応答時間に基づく条件設定
    2. システムリソースに基づく条件設定
    3. まとめ
  6. 複数のカスタムヘルスチェックの統合
    1. 複数のカスタムヘルスチェックの統合方法
    2. カスタムヘルスインジケーターの例
    3. 統合されたヘルスチェック結果の表示
    4. 各ヘルスインジケーターの状態を独立して確認
    5. まとめ
  7. ヘルスチェックのセキュリティ考慮点
    1. ヘルスチェックエンドポイントのアクセス制御
    2. エンドポイントの情報を制限する
    3. ヘルスチェックエンドポイントの限定公開
    4. まとめ
  8. カスタムメトリクスと連携したヘルスチェック
    1. メトリクスの基本概念
    2. カスタムメトリクスの作成
    3. カスタムメトリクスとヘルスチェックの連携
    4. カスタムメトリクスのエクスポートと監視
    5. カスタムメトリクスを使ったトラブルシューティング
    6. まとめ
  9. 運用時のカスタムヘルスチェックの監視
    1. 監視ツールの導入
    2. アラートの設定
    3. エンドポイントの定期監視
    4. ロギングと監査ログの活用
    5. ダッシュボードの構築
    6. まとめ
  10. カスタムヘルスチェックのテスト方法
    1. ユニットテストによる検証
    2. 統合テストによるシステム全体の確認
    3. モックを使った外部依存関係のテスト
    4. まとめ
  11. まとめ