エンドポイント
Actuator のエンドポイントは、有効かつ公開されているときに HTTP で応答します。有効かどうかはエンドポイントがそもそも存在するかを決め、公開されているかどうかは HTTP がそれを見せるかを決めます。どちらも Spring Boot の management.* プロパティで設定し、エンドポイントは Web スターターのサーバーで /actuator の下に応答します。
使う理由
ヘルスチェックはロードバランサーから到達できなければなりませんが、アプリケーションのマッピングは他の誰にも関係のないものです。Spring Boot と同じく、デフォルトで health だけを公開することで、それ以外は自分で選ぶまで非公開に保たれます。
例
# lib/resources/application.yml
management:
endpoints:
web:
base-path: /manage # /actuator/health の代わりに /manage/health
exposure:
include: "*" # 有効なすべてのエンドポイント...
exclude: mappings # ...ただしマッピングは除く
path-mapping:
health: healthcheck # /manage/healthcheck
discovery:
enabled: true
endpoint:
info:
access: read-only
# lib/resources/application.properties: 同じ内容
management.endpoints.web.base-path=/manage
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=mappings
management.endpoints.web.path-mapping.health=healthcheck
management.endpoints.web.discovery.enabled=true
management.endpoint.info.access=read-only
$ curl localhost:8080/manage/healthcheck
{"status":"UP"}
YAML では "*" を引用符で囲んでください。裸の * はエイリアスです。
有効
エンドポイントは、次のうち最初に設定されているものによって有効になります。
management.endpoint.<id>.access:noneは無効にし、read-onlyとunrestrictedは有効にします (Spring Boot 3.4 以降)。management.endpoint.<id>.enabled:trueまたはfalse(Spring Boot 2 と 3)。management.endpoints.access.default: 自分の設定を持たないすべてのエンドポイントのアクセス。management.endpoints.enabled-by-default。- エンドポイント自身のデフォルト:
@Endpoint(enableByDefault:)。組み込みのものはtrue。
組み込みの ID は health、info、mappings、jsonschemas、isolates、qps です。qps エンドポイントは、Web スターターのデバッグ機能がビルドに入っているときにだけ存在します (spring.web.debug.qps.enabled: true、毎秒のリクエスト数 を参照)。
無効なエンドポイントは公開も列挙もされません。不明な access の値は起動を止めます (must be one of none, read-only, unrestricted)。今のところ読み取り操作しかないため、read-only と unrestricted は同じ意味です。
# すべて無効にしてから、health だけを再び有効にする。
management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true
公開
| キー | デフォルト | 意味 |
|---|---|---|
management.endpoints.web.exposure.include |
health |
HTTP で公開する ID。すべてなら * |
management.endpoints.web.exposure.exclude |
なし | 公開しない ID、または *。include より優先される |
パス
| キー | デフォルト | 意味 |
|---|---|---|
management.endpoints.web.base-path |
/actuator |
エンドポイントを置くパス。/ はディスカバリーページなしでルートに置く (/health)。先頭の / がなければ追加され、末尾のものは取り除かれる |
management.endpoints.web.path-mapping.<id> |
ID | 一つのエンドポイントの別のパス |
management.endpoints.web.discovery.enabled |
true |
ベースパスが公開されたエンドポイントへのリンクを返すかどうか |
エンドポイントは、Web スターターの他のすべてのパスと同じく server.context-path の下にあります。別の管理用ポートはありません。
ディスカバリーページ
GET /actuator は公開されたエンドポイントを列挙します。
{"_links": {
"self": {"href": "http://localhost:8080/actuator", "templated": false},
"health": {"href": "http://localhost:8080/actuator/health", "templated": false},
"health-path": {"href": "http://localhost:8080/actuator/health/{*path}", "templated": true},
"info": {"href": "http://localhost:8080/actuator/info", "templated": false}}}
メディアタイプとステータスコード
| リクエスト | 応答 |
|---|---|
Accept: application/vnd.spring-boot.actuator.v3+json、*/*、またはなし |
バージョン 3 の JSON、application/vnd.spring-boot.actuator.v3+json |
Accept: application/json |
同じ JSON を application/json として |
Accept: application/vnd.spring-boot.actuator.v2+json |
バージョン 2 の JSON (ヘルスの各部分は details の下) |
エンドポイントが返せない Accept |
406 |
GET と HEAD 以外のメソッド |
405 |
null を返す操作 |
404 |
| ないか変換できないクエリパラメーター | 400 |
Spring (Java) との対応
キー、デフォルト、メディアタイプは同じです。Spring Boot はエンドポイントを JMX や別の management.server.port でも公開できます。ここでは、メインのサーバーでの HTTP だけです。