spring_boot_actuator

Actuator は、動作中のアプリケーションが自分自身について知っていることを伝えます。正常に動いているか、どのバージョンか、どのアドレスに応答するか、です。ロードバランサーは /actuator/health にリクエストを送ってよいかを尋ね、Kubernetes は /actuator/health/liveness と /readiness を尋ね、運用担当者は /actuator/info でどのビルドが動いているかを尋ねます。応答は Spring Boot のパス、プロパティ、JSON を持つため、あらゆる Spring のツールがそれを読めます。

2 つのパッケージで構成されます。

パッケージ 内容 依存関係に挙げるもの
spring_boot_starter_actuator スターター: エンドポイントを Bean として宣言し、spring_boot_starter_web を通して /actuator の下で応答する。spring_boot_actuator を再エクスポートする アプリケーション
spring_boot_actuator HTTP なしのエンドポイント: ヘルスのモデル、情報のコントリビューター、マッピング、@Endpoint、management.* のプロパティクラス エンドポイントに寄与するライブラリ (データスターターの db インジケーター、セキュリティスターターの EndpointRequest)

これらは spring-boot-starter-actuator と spring-boot-actuator (ヘルスのモデルについては Spring Boot 4 の spring-boot-health) に当たる Dart のものです。

使う理由

Actuator がなければ、各アプリケーションがそれぞれの形で独自のヘルスのコントローラーを書き、監視の設定もそのたびにやり直すことになります。Actuator があれば、依存関係を追加するだけで済みます。ヘルスチェックはすべてのインジケーターを集約し、プローブはアプリケーションの可用性に従い、応答は Spring Boot が返すものと同じです。

セットアップ

# pubspec.yaml
dependencies:
  spring_boot_starter_actuator: ^0.9.0   # spring_boot_actuator を持ち込み、Web スターターを必要とする

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
dart run build_runner build

例

// bin/main.dart
import 'package:spring_boot_starter_actuator/spring_boot_starter_actuator.dart';

import 'spring_gen/main.spring.dart';

@SpringBootApplication()
void main(List<String> args) => runApplication(args);
$ curl -i localhost:8080/actuator/health
HTTP/1.1 200 OK
content-type: application/vnd.spring-boot.actuator.v3+json

{"status":"UP"}

アプリケーションが DOWN または OUT_OF_SERVICE のとき、応答は 503 です。Spring Boot と同じく、デフォルトで公開されるのは health だけです。その他はプロパティで追加します。

# lib/resources/application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info,mappings
  endpoint:
    health:
      show-details: always
      probes:
        enabled: true
  info:
    env:
      enabled: true
info:
  app:
    team: neon-books
$ curl localhost:8080/actuator/health
{"status":"UP","components":{"diskSpace":{"status":"UP","details":{"total":499963174912,"free":91300605952,"threshold":10485760,"path":"/srv/shop/.","exists":true}},"livenessState":{"status":"UP"},"ping":{"status":"UP"},"readinessState":{"status":"UP"}},"groups":["liveness","readiness"]}

$ curl localhost:8080/actuator/info
{"app":{"team":"neon-books"}}

エンドポイント

エンドポイント パス 表示するもの ページ
ディスカバリー /actuator 公開されたすべてのエンドポイントへの _links エンドポイント
health /actuator/health、/actuator/health/{*path} 集約されたステータス、コンポーネント、グループ、プローブ ヘルス
info /actuator/info ビルド、git、info.* プロパティ、OS と Dart のバージョン 情報
mappings /actuator/mappings Web サーバーのハンドラーと、ナビゲーションスターターがあればアプリの画面 マッピング
jsonschemas /actuator/jsonschemas、/actuator/jsonschemas/{name} レジストリと、すべての @Introspected クラスの JSON Schema JSON Schemas
isolates /actuator/isolates アプリケーションのすべての isolate とその負荷: 働いていた時間の割合、遅れ、実行中のリクエスト、メモリー isolate
qps /actuator/qps、/actuator/qps/now 毎秒のリクエスト数、レイテンシー、エラー。isolate ごとと合計。Web スターターのデバッグ機能 qps がビルドに入っているときだけ 毎秒のリクエスト数

内容

Spring (Java) との対応

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
management.endpoints.web.exposure.include=health,info
management.endpoint.health.show-details=always

プロパティも JSON も同じです。重要な違い:

関連項目