
# 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 が返すものと同じです。

## セットアップ

```yaml
# 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
```

```bash
dart run build_runner build
```

## 例

```dart
// 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);
```

```console
$ 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` だけです。その他はプロパティで追加します。

```yaml
# 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
```

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

## 内容

- [エンドポイント](endpoints.md): 有効化、公開、パス、メディアタイプ、ディスカバリーページ。
- [ヘルス](health.md): インジケーター、詳細、ステータスの集約、グループ、Kubernetes のプローブ。
- [情報](info.md): ビルドと git の情報、`info.*` プロパティ、OS と Dart。
- [マッピング](mappings.md): Web サーバーのハンドラーとアプリの画面。
- [JSON Schemas](json-schemas.md): レジストリとアプリケーションのクラスのスキーマ。
- [isolate](isolates.md): すべての isolate の負荷。JSON になったタスクマネージャー。
- [毎秒のリクエスト数](qps.md): Web スターターのデバッグ機能 `qps` の数値。
- [独自のエンドポイント](custom-endpoints.md): `@Endpoint`、`@ReadOperation`、`@Selector`、Web 拡張。
- [セキュリティ](security.md): `EndpointRequest` と `show-details=when-authorized`。
- [すべてのプロパティ](properties.md): すべての `management.*`、`spring.info.*`、`info.*` のキー。
- [Spring との違い](differences.md): Spring Boot Actuator と動作が異なる点。

## Spring (Java) との対応

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

```properties
management.endpoints.web.exposure.include=health,info
management.endpoint.health.show-details=always
```

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

- Spring Boot のエンドポイントのうち、今のところ存在するのは `health`、`info`、`mappings` だけです。`jsonschemas`、`isolates`、`qps` はこの Actuator 独自のものです。読み取り操作のみです。
- 別の管理用ポートはありません。エンドポイントはメインのサーバーにあります。
- すべての違いは [Spring との違い](differences.md) にあります。

## 関連項目

- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
- [イベントと可用性](../spring-boot-dart/events.md)
- [spring_boot_dart](../spring-boot-dart/index.md)
- [ビルドに含まれるもの](optimizations.md)
