エンドポイント

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 では "*" を引用符で囲んでください。裸の * はエイリアスです。

有効

エンドポイントは、次のうち最初に設定されているものによって有効になります。

  1. management.endpoint.<id>.access: none は無効にし、read-only と unrestricted は有効にします (Spring Boot 3.4 以降)。
  2. management.endpoint.<id>.enabled: true または false (Spring Boot 2 と 3)。
  3. management.endpoints.access.default: 自分の設定を持たないすべてのエンドポイントのアクセス。
  4. management.endpoints.enabled-by-default。
  5. エンドポイント自身のデフォルト: @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 だけです。

関連項目