記事ディレクトリ

0. 序文
1. 参考資料
2. 基本的な紹介
- デフォルトでサポートされるエンドポイント
3. 手順
4. サンプルプロジェクト
5. まとめ

0. 序文

背景: Spring Boot のさまざまなコンポーネントや機能を散発的に使用しており、体系的に研究してまとめたことはありませんでしたが、この機会に波を起こすことにしました。一緒に学び、一緒に進歩しましょう。ははは

Spring Boot Actuator は、アプリケーションのステータス、メトリクス、ヘルスチェック、構成情報などを取得するために使用できる一連の監視エンドポイントを提供する強力な監視および管理フレームワークです。Actuator の監視エンドポイントには HTTP リクエスト経由でアクセスでき、アプリケーションのランタイムに関する情報を含むレスポンスを返すことができます。

Actuator を使用すると、アプリケーションの状態を簡単に理解し、主要なメトリクスを監視し、必要に応じて適切なアクションを実行できます。これにより、開発者とオペレータは Spring Boot アプリケーションを監視および管理する簡単かつ効率的な方法を利用できます。

このシリーズの記事では、Spring Boot Actuator を使用したエンドポイントの監視のさまざまな側面について詳しく説明します。ヘルスチェック、情報、メトリクスなどのデフォルトの監視エンドポイントを 1 つずつ説明し、特定のニーズを満たすためにこれらのエンドポイントをカスタマイズおよび拡張する方法について説明します。

この一連の記事では、次のことを学習します。

アクチュエーターの概要と基本概念。
ヘルスチェック、情報、メトリックなどを含む、デフォルトの監視エンドポイントの詳細な説明。
特定のアプリケーションのステータスと情報を取得するために監視エンドポイントをカスタマイズする方法。
エンドポイントのセキュリティ構成を監視して、機密情報へのアクセスを保護します。
Actuator のイベントおよびリスナー機能の使用方法。
カスタムインジケーター、カスタムエンドポイント、カスタム EndpointGroup などを含む、Actuator の拡張メカニズム。

この一連の記事を読むことで、Spring Boot Actuator 監視エンドポイントの機能と使用法を包括的に理解し、Actuator を柔軟に使用して Spring Boot アプリケーションを監視および管理できるようになります。楽しくて実践的な学習の旅を始めましょう!

1. 参考資料

Spring Boot アクチュエーターのチュートリアル

Tutorialspoint それは今でも比較的優れた権威のあるウェブサイトです。上に挙げた例のいくつかは、十分な参考価値があります。少なくとも CSDN のいくつかのコード例よりもはるかに優れています。コピーされることはありません。バグはまったく同じです (笑)。まだまだ充実した内容となっておりますので、気軽に閲覧することをお勧めします。上記のリンクでは、デフォルトのエンドポイント、カスタムエンドポイント、ヘルスチェックなどを含む Spring Boot Actuator の基本概念と使用法を紹介し、いくつかのサンプルコードを提供します。
公式ドキュメント - Spring Boot アクチュエーター

公式ドキュメントには、モニタリングエンドポイントの概要、デフォルトエンドポイントの概要、カスタムエンドポイントの作成と構成など、Actuator の詳細な手順が記載されています。

公式ドキュメント - ヘルスインジケーター

公式ドキュメントのヘルスインジケーターに関するセクションでは、カスタムヘルスチェックインジケーターの作成方法が説明されており、構成オプションの例と説明がいくつか提供されています。
Baeldung - Spring Boot アクチュエーターのガイド

Baeldung Web サイトの記事では、Actuator の中心概念、監視エンドポイントの詳細な説明、エンドポイントのカスタマイズと構成方法をカバーする包括的な Spring Boot Actuator ガイドが提供されています。

2. 基本的な紹介

spring-boot-starter-actuatorSpring Boot アプリケーションの実行時情報を監視および管理するために Spring Boot によって提供されるモジュールです。アプリケーションの健全性ステータス、パフォーマンス指標、構成情報などを取得するための一連の監視エンドポイント (エンドポイント) を提供し、HTTP または JMX 経由のアクセスをサポートします。

spring-boot-starter-actuatorの主な特徴と機能を次に示します。

ヘルスインジケーター:spring-boot-starter-actuatorアプリケーションの健全性をチェックするために使用できるヘルスエンドポイントを提供します。ヘルスインジケーターを介して、データベース接続、ディスク領域、メモリ使用量などの事前定義されたヘルスチェックルールのセットを提供します。ヘルスインジケーターをカスタマイズしてカスタムヘルスチェックルールを追加することもできます。
情報エンドポイント (情報エンドポイント) : このエンドポイントは、アプリケーションのカスタム情報を取得するために使用されます。バージョン番号、ビルド情報などのアプリケーションのメタデータは、情報エンドポイントを通じて構成および公開できます。
メトリクス: spring-boot-starter-actuatorCPU 使用率、メモリ使用量、リクエスト処理時間などのアプリケーションメトリクスの収集と公開をサポートします。Micrometer ライブラリを使用してメトリクスを収集および管理し、メトリクスエンドポイントを通じて公開できます。
構成プロパティ: この機能により、アプリケーション構成プロパティの取得と調整が可能になります。アプリケーションの構成プロパティは、構成プロパティエンドポイントを通じて表示および変更でき、プロパティの動的な更新がサポートされています。
Logging :spring-boot-starter-actuatorアプリケーションのログレベルを管理するためのエンドポイントを提供します。ロガーレベルを表示および変更し、ログエンドポイントを通じてログ構成を再ロードできます。
リモートシェル (リモートシェル) : この機能を使用すると、SSH または Telnet 経由でアプリケーションに接続し、一部の管理操作を実行できます。アプリケーションでリモートシェルを有効にすると、コマンドラインインターフェイスを介してアプリケーションをリモートで管理および監視できます。

上記の機能は、依存関係を導入することでspring-boot-starter-actuatorSpring Boot アプリケーションに簡単に統合できます。同時に、spring-boot-starter-actuator監視エンドポイントへの安全なアクセスを確保するために、いくつかのセキュリティ構成オプションが提供されます。

デフォルトでサポートされるエンドポイント

Spring Boot は、デフォルトで次の一般的に使用されるエンドポイントを提供します。
ここに画像の説明を挿入

/actuator/health : アプリケーションの健全性ステータスを表示します。健全性ステータスを表す JSON 応答を返します。
私たちのアプリケーションが電子商取引プラットフォームであり、/actuator/healthエンドポイントの健全性ステータスやその他のカスタムヘルスチェック項目を表示するとします。

{
    
    
  "status": "UP",
  "components": {
    
    
    "database": {
    
    
      "status": "UP",
      "details": {
    
    
        "connection": "OK",
        "activeConnections": 10
      }
    },
    "storage": {
    
    
      "status": "UP",
      "details": {
    
    
        "availableSpace": "10 GB",
        "usedSpace": "2 GB"
      }
    },
    "paymentGateway": {
    
    
      "status": "DOWN",
      "details": {
    
    
        "error": "Connection timeout"
      }
    }
  }
}

/actuator/info : アプリケーション情報を表示します。
/actuator/metrics : アプリケーションのメトリクスを表示します。メモリ使用量、HTTP リクエスト数などを返します。
/actuator/beans : アプリケーション内のすべての Spring Bean を表示します。すべての Bean を含む JSON 応答を返します。
/actuator/env : アプリケーションの環境プロパティを表示します。プロファイルプロパティ、システムプロパティなどのアプリケーション環境プロパティを含む JSON 応答を返します。
/actuator/mappings : アプリケーションの URL マッピングを表示します。コントローラー、リクエストメソッドなど、アプリケーション内のすべての URL マッピングに関する情報を含む JSON 応答を返します。
/actuator/trace : 最近の HTTP リクエストトレース情報を表示します。リクエストメソッド、URL、ステータスコードなどを含む、最新の HTTP リクエストを含む JSON レスポンスを返します。

{
    
    
  "traces": [
    {
    
    
      "timestamp": "2023-08-15T09:26:18.062Z",
      "principal": null,
      "session": null,
      "request": {
    
    
        "method": "GET",
        "uri": "http://localhost:8001/actuator/loggers",
        "headers": {
    
    
          "accept": [
            "application/vnd.spring-boot.actuator.v2+json"
          ],
          "host": [
            "localhost:8001"
          ],
          "connection": [
            "Keep-Alive"
          ],
          "user-agent": [
            "Apache-HttpClient/4.5.14 (Java/17.0.7)"
          ],
          "accept-encoding": [
            "br,deflate,gzip,x-gzip"
          ]
        },
        "remoteAddress": null
      },
      "response": {
    
    
        "status": 200,
        "headers": {
    
    
          "Access-Control-Allow-Origin": [
            "*"
          ],
          "Access-Control-Allow-Credentials": [
            "true"
          ],
          "Access-Control-Allow-Methods": [
            "GET,POST,OPTIONS,PUT,DELETE"
          ],
          "Content-Type": [
            "application/vnd.spring-boot.actuator.v2+json;charset=UTF-8"
          ],
          "Transfer-Encoding": [
            "chunked"
          ],
          "Date": [
            "Tue, 15 Aug 2023 09:26:18 GMT"
          ]
        }
      },
      "timeTaken": 49
    },
    {
    
    
      "timestamp": "2023-08-15T09:24:19.108Z",
      "principal": null,
      "session": null,
      "request": {
    
    
        "method": "GET",
        "uri": "http://localhost:8001/actuator/beans",
        "headers": {
    
    
          "accept": [
            "application/vnd.spring-boot.actuator.v2+json"
          ],
          "host": [
            "localhost:8001"
          ],
          "connection": [
            "Keep-Alive"
          ],
          "user-agent": [
            "Apache-HttpClient/4.5.14 (Java/17.0.7)"
          ],
          "accept-encoding": [
            "br,deflate,gzip,x-gzip"
          ]
        },
        "remoteAddress": null
      },
      "response": {
    
    
        "status": 200,
        "headers": {
    
    
          "Access-Control-Allow-Origin": [
            "*"
          ],
          "Access-Control-Allow-Credentials": [
            "true"
          ],
          "Access-Control-Allow-Methods": [
            "GET,POST,OPTIONS,PUT,DELETE"
          ],
          "Content-Type": [
            "application/vnd.spring-boot.actuator.v2+json;charset=UTF-8"
          ],
          "Transfer-Encoding": [
            "chunked"
          ],
          "Date": [
            "Tue, 15 Aug 2023 09:24:19 GMT"
          ]
        }
      },
      "timeTaken": 70
    },
    {
    
    
      "timestamp": "2023-08-15T09:23:50.737Z",
      "principal": null,
      "session": null,
      "request": {
    
    
        "method": "GET",
        "uri": "http://localhost:8001/actuator/health",
        "headers": {
    
    
          "accept": [
            "application/vnd.spring-boot.actuator.v2+json"
          ],
          "host": [
            "localhost:8001"
          ],
          "connection": [
            "Keep-Alive"
          ],
          "user-agent": [
            "Apache-HttpClient/4.5.14 (Java/17.0.7)"
          ],
          "accept-encoding": [
            "br,deflate,gzip,x-gzip"
          ]
        },
        "remoteAddress": null
      },
      "response": {
    
    
        "status": 200,
        "headers": {
    
    
          "Access-Control-Allow-Origin": [
            "*"
          ],
          "Access-Control-Allow-Credentials": [
            "true"
          ],
          "Access-Control-Allow-Methods": [
            "GET,POST,OPTIONS,PUT,DELETE"
          ],
          "Content-Type": [
            "application/vnd.spring-boot.actuator.v2+json;charset=UTF-8"
          ],
          "Transfer-Encoding": [
            "chunked"
          ],
          "Date": [
            "Tue, 15 Aug 2023 09:23:51 GMT"
          ]
        }
      },
      "timeTaken": 488
    }
  ]
}
响应文件已保存。
> 2023-08-15T172634.200.json

Response code: 200; Time: 38ms (38 ms); Content length: 2230 bytes (2.23 kB)

/actuator/auditevents : アプリケーションの監査イベントを表示します。ログインの成功、失敗などのアプリケーション監査イベントを含む JSON 応答を返します。
/actuator/loggers : アプリケーションのロガー構成を表示および変更します。ロガーレベルを変更できるロガー構成情報を含む JSON 応答を返します。
/actuator/httptrace : 最近の HTTP トレース情報を表示します。リクエストとレスポンスのヘッダー、ステータスコードなど、最新の HTTP リクエストとレスポンスのトレース情報を含む JSON レスポンスを返します。
/actuator/threaddump : アプリケーションのスレッドダンプ情報を表示します。スレッドのステータスと問題を分析するためのアプリケーションスレッドダンプ情報を含む JSON 応答を返します。

大家可以在自己的项目中去尝试获取一下这些信息，此处不再演示。、続けましょう。

3. 手順

3.1. 依存関係の導入

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

3.2. 設定ファイル

これらの構成は必要に応じて構成できます。もう 1 つのポイントは、エンドポイントを開くには特定のセキュリティリスクがあるということです。上で示した結果から、実際にいくつかのコア情報を出力し、攻撃者に価値を提供することがわかります。実稼働環境は、必要な場合以外は開かないでください。

 # Actuator Endpoints
# 启用所有端点，默认为true
management.endpoints.enabled-by-default=true
# 管理端点的基本路径，默认为/actuator
management.endpoints.web.base-path=/actuator
# 配置需要暴露的端点，*表示全部暴露
management.endpoints.web.exposure.include=*
# 配置需要排除的端点，如果需要排除特定端点，可以在此处指定
management.endpoints.web.exposure.exclude=
# 允许跨域访问的来源，*表示允许全部来源
management.endpoints.web.cors.allowed-origins=*
# 允许跨域访问的HTTP方法
management.endpoints.web.cors.allowed-methods=GET

# Health Endpoint
# 显示详细的健康状态信息，always表示始终显示
management.endpoint.health.show-details=always

# Info Endpoint
# 应用程序名称
info.app.name=我的应用程序
# 应用程序版本
info.app.version=1.0.0

# Metrics Endpoint
# 启用度量指标端点
management.endpoint.metrics.enabled=true
# 启用缓存的度量指标
management.endpoint.metrics.cache.enabled=true
# 启用默认的度量指标
management.metrics.export.defaults.enabled=true

# Beans Endpoint
# 启用显示所有 Spring Bean 的端点
management.endpoint.beans.enabled=true

# Environment Endpoint
# 启用显示应用程序环境属性的端点
management.endpoint.env.enabled=true

# Mappings Endpoint
# 启用显示应用程序 URL 映射信息的端点
management.endpoint.mappings.enabled=true

# Trace Endpoint
# 启用显示最近的 HTTP 请求跟踪信息的端点
management.endpoint.trace.enabled=true

# Auditevents Endpoint
# 启用显示应用程序审计事件的端点
management.endpoint.auditevents.enabled=true

# Loggers Endpoint
# 启用显示和修改应用程序日志记录器配置的端点
management.endpoint.loggers.enabled=true

# Httptrace Endpoint
# 启用显示最近的 HTTP 请求和响应跟踪信息的端点
management.endpoint.httptrace.enabled=true

# Threaddump Endpoint
# 启用显示应用程序线程转储信息的端点
management.endpoint.threaddump.enabled=true

3.3. コアソースコード

そのコアコードには、次の主要なコンポーネントと機能が含まれています。異なるバージョンには、上記の構成項目を含む異なるクラスとインターフェイスがあります。この記事は以下に基づいています2.0.3

エンドポイントインターフェイス:Endpointこのインターフェイスは、監視および管理機能のコアメソッドを定義します。すべての監視エンドポイントはこのインターフェイスを実装し、独自のロジック実装を提供する必要があります。
MetricsEndpoint クラス:MetricsEndpointアプリケーションメトリック情報を提供するために使用されるモニタリングエンドポイントです。これは、アプリケーションのメトリックデータを収集して呼び出し元に返すことにより、インターフェイスのメソッドをAbstractEndpoint継承して実装します。Endpoint
InfoEndpoint クラス:InfoEndpointアプリケーションに関するカスタム情報を提供するための監視エンドポイントです。アプリケーションに関するカスタム情報を収集して呼び出し元に返すことにより、インターフェイスのメソッドをAbstractEndpoint継承して実装します。Endpoint
ControllerEndpointHandlerMapping クラス:EndpointHandlerMappingこのクラスは、HTTP リクエストを対応する監視エンドポイントプロセッサにマッピングする役割を担う Spring MVC プロセッサマッパーです。
EndpointWebMvcManagementContextConfiguration クラス:EndpointWebMvcManagementContextConfigurationこのクラスは Spring Boot Actuator の自動構成クラスであり、などをEndpointHandlerMapping含むActuator のコアコンポーネントを登録および構成するために使用されます。EndpointMvcAdapter
AbstractEndpoint クラス:AbstractEndpointこのクラスはEndpointインターフェイスの抽象実装であり、エンドポイントの ID、有効かどうか、セキュリティ構成など、いくつかの共通の関数とメソッドを提供します。カスタム監視エンドポイントはこのクラスから継承して実装を簡素化できます。
HealthIndicator : Spring Boot Actuator によって提供されるコアインターフェイスであり、アプリケーションのヘルスチェックロジックを定義するために使用されます。これにより、開発者はヘルスチェックの実装をカスタマイズし、それを Spring Bean として登録し、アクチュエーターの一部にすることができます。。

ヘルスチェックに追加された、合意された構成が非常に多くあることがわかります。
HealthIndicatorInterface は Spring Boot Actuator によって提供されるコアインターフェイスであり、アプリケーションのヘルスチェックロジックを定義するために使用されます。これにより、開発者はヘルスチェックの実装をカスタマイズし、それを Spring Bean として登録し、アクチュエーターの一部にすることができます。
HealthIndicatorこのインターフェイスには、アプリケーションの正常性ステータスを表すオブジェクトhealth()を返すメソッドが 1 つだけあります。カスタムヘルスインジケーターを実装するには、インターフェイスを実装し、そのインターフェイスにメソッドを実装する必要があります。このメソッドでは、開発者は独自のヘルスチェックロジックを作成し、アプリケーションのヘルスステータスを記述するオブジェクトを返すことができます。オブジェクトは、、などの静的メソッドを使用して作成できます。ヘルスステータスのより詳細な説明を提供するために、ステータス情報、エラーメッセージ、例外情報などを含めることができます。Health
HealthIndicatorhealth()Health
HealthHealth.up()Health.down()Health.unknown()

簡単な実装は次のとおりです。

@Component
public class MyHealthIndicator implements HealthIndicator {
    
    

    @Override
    public Health health() {
    
    
        // 自定义健康检查逻辑
        boolean isHealthy = checkHealth(); // 健康检查的具体实现

        if (isHealthy) {
    
    
            return Health.up().build(); // 返回健康状态
        } else {
    
    
            return Health.down().withDetail("Error", "Something went wrong").build(); // 返回不健康状态，并提供错误信息
        }
    }

    private boolean checkHealth() {
    
    
        // 实现自定义的健康检查逻辑
        // 返回 true 表示健康，返回 false 表示不健康
        // 可以根据具体需求进行判断
    }
}

4. サンプルプロジェクト

MongoDB をデータベースとして使用する Spring Boot アプリケーションがあり、MongoDB データベースへの接続ステータスをチェックするカスタムヘルスチェックルールを追加するとします。接続に問題がない場合、アプリケーションは正常であるとマークされ、そうでない場合は異常であるとマークされます。

MongoDBHealthIndicatorまず、カスタムヘルスインジケータークラスを作成し、HealthIndicatorインターフェイスを実装し、health()MongoDB 接続のヘルスチェックを実行するメソッドをオーバーライドする必要があります。
このオブジェクトを利用してMongoClientMongoDBのpingコマンドを実行し、コマンドが正常に実行できればデータベースとの接続は正常であると考えられます。例外がある場合は、ヘルスステータスの詳細にエラーメッセージが追加されます。

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

@Component
public class MongoDBHealthIndicator implements HealthIndicator {
    
    

    private final MongoClient mongoClient;

    public MongoDBHealthIndicator(MongoClient mongoClient) {
    
    
        this.mongoClient = mongoClient;
    }

    @Override
    public Health health() {
    
    
        try {
    
    
            mongoClient.getDatabase("admin").runCommand("ping"); // 执行 MongoDB 的 ping 命令，检查连接状态
            return Health.up().build(); // 健康状态
        } catch (Exception e) {
    
    
            return Health.down().withDetail("Error", e.getMessage()).build(); // 非健康状态，添加错误信息
        }
    }
}

次に、アプリケーションがMongoDBHealthIndicatorクラスを自動的にスキャンできることを確認します。自動スキャンは@ComponentScan、または注釈を使用して実行できます。@SpringBootApplication

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {
    
    

    public static void main(String[] args) {
    
    
        SpringApplication.run(MyApplication.class, args);
    }
}

最後に、アプリケーションを起動し、/actuator/healthエンドポイントにアクセスして、カスタムヘルスチェックルールの結果を表示します。

GET /actuator/health

次の出力のような、返された JSON でカスタムヘルスチェックの結果を確認できるはずです。
mongoDBカスタムヘルスチェックの結果を示します。statusフィールドは"UP"ヘルスステータス用、detailsフィールドは追加の詳細用です。接続に問題がある場合は、statusフィールドがに変わり"DOWN"、detailsフィールドにエラーメッセージが表示されます。

{
    
    
  "status": "UP",
  "components": {
    
    
    "mongoDB": {
    
    
      "status": "UP",
      "details": {
    
    
        "error": null
      }
    },
    "ping": {
    
    
      "status": "UP",
      "details": {
    
    
        "error": null
      }
    }
  }
}

5. まとめ

Spring Boot Actuator は、Spring Boot アプリケーションを監視および管理するための、簡単で拡張可能かつ構成可能な方法を提供するように設計されています。

コンベンションは設定よりも優れています: Spring Boot Actuator は、設定原則よりも Spring Boot のコンベンションに従います。デフォルト設定と自動アセンブリを通じて、アプリケーションの起動時に、面倒な手動設定を行わなくても、監視および管理エンドポイントが自動的に利用可能になります。
エンドポイントのモジュール性と拡張性: Actuator は、コアエンドポイントのセット (ヘルスチェック、情報、メトリクスなど) を提供し、カスタムエンドポイントの追加と拡張もサポートします。開発者は、独自のニーズに応じてカスタムエンドポイントを作成し、簡単な構成を通じてそれらを Actuator に統合できます。
HTTP ベースのリモートアクセス: Actuator のエンドポイントは HTTP プロトコル経由でアクセスされ、アプリケーションのコードやランタイム環境に直接アクセスすることなく、監視および管理操作をリモートで実行できます。これにより、分散環境での複数のアプリケーションの監視と管理が容易になります。
豊富な監視および管理機能を提供: Actuator は、健全性ステータス、パフォーマンスインジケーター、環境プロパティ、ロガー構成など、アプリケーションのさまざまな側面を監視および管理するための一連の強力なエンドポイントを提供します。これらの機能は、開発者がアプリケーションの状態を迅速に理解し、トラブルシューティングやパフォーマンスの最適化を実行するのに役立ちます。
セキュリティと権限の制御: Actuator は、エンドポイントへのアクセスを制限するセキュリティ構成オプションを提供し、許可されたユーザーまたはロールのみが機密の監視および管理エンドポイントにアクセスできるようにします。これにより、アプリケーションのセキュリティと機密情報の機密性が保護されます。

Spring Boot Knowledge Collectionのアクチュエータ監視エンドポイントの詳細説明