Endpoints

An actuator endpoint answers over HTTP when it is enabled and exposed. Enabled decides whether the endpoint exists at all; exposed decides whether HTTP shows it. Both are set with Spring Boot's management.* properties, and the endpoints answer on the web starter's server under /actuator.

Why

The health check must be reachable by a load balancer, but the mappings of an application are nobody else's business. Exposing only health by default, as Spring Boot does, keeps the rest private until you choose otherwise.

Example

# lib/resources/application.yml
management:
  endpoints:
    web:
      base-path: /manage                 # /manage/health instead of /actuator/health
      exposure:
        include: "*"                     # every enabled endpoint...
        exclude: mappings                # ...but the mappings
      path-mapping:
        health: healthcheck              # /manage/healthcheck
      discovery:
        enabled: true
  endpoint:
    info:
      access: read-only
# lib/resources/application.properties: the same
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"}

In YAML, quote "*": a bare * is an alias.

Enabled

An endpoint is enabled by the first of these that is set:

  1. management.endpoint.<id>.access: none disables it, read-only and unrestricted enable it (Spring Boot 3.4 and later);
  2. management.endpoint.<id>.enabled: true or false (Spring Boot 2 and 3);
  3. management.endpoints.access.default: the access of every endpoint without its own;
  4. management.endpoints.enabled-by-default;
  5. the endpoint's own default: @Endpoint(enableByDefault:), true for the built-in ones.

The built-in ids are health, info, mappings, jsonschemas, isolates and qps. The qps endpoint exists only when the web starter's debug feature is in the build (spring.web.debug.qps.enabled: true, see Requests per second).

A disabled endpoint is neither exposed nor listed. An unknown access value stops the start (must be one of none, read-only, unrestricted). Only read operations exist so far, so read-only and unrestricted mean the same.

# Everything off, then health back on.
management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true

Exposed

Key Default Meaning
management.endpoints.web.exposure.include health The ids exposed over HTTP, or * for all
management.endpoints.web.exposure.exclude none The ids not exposed, or *; wins over include

Paths

Key Default Meaning
management.endpoints.web.base-path /actuator The path under which the endpoints are. / puts them at the root (/health), without the discovery page. A missing leading / is added, trailing ones dropped
management.endpoints.web.path-mapping.<id> the id Another path for one endpoint
management.endpoints.web.discovery.enabled true Whether the base path answers the links to the exposed endpoints

The endpoints are under server.context-path like every other path of the web starter. There is no separate management port.

The discovery page

GET /actuator lists the exposed endpoints:

{"_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}}}

Media types and status codes

Request Answer
Accept: application/vnd.spring-boot.actuator.v3+json, */* or none Version 3 JSON, application/vnd.spring-boot.actuator.v3+json
Accept: application/json The same JSON as application/json
Accept: application/vnd.spring-boot.actuator.v2+json Version 2 JSON (the health's parts under details)
an Accept the endpoint cannot give 406
a method other than GET and HEAD 405
an operation that answers null 404
a query parameter that is missing or cannot be converted 400

In Spring (Java)

The same keys, defaults and media types. Spring Boot can also expose endpoints over JMX and on a separate management.server.port; here they are HTTP on the main server only.

See also