Endpoints of your own

An @Endpoint class adds an endpoint next to health and info, under /actuator/<id>, with the same rules for enabling, exposure, security and media types. It is Spring Boot's @Endpoint.

Why

Operations data that belongs to the application (feature flags, queue sizes, a cache's statistics) fits the actuator: one base path, one security rule, one JSON style. Writing it as an endpoint instead of a controller gives it all of that for free.

Example

// GET /actuator/features and GET /actuator/features/{name}
@Endpoint(id: 'features')
class FeaturesEndpoint {
  FeaturesEndpoint(this.flags);

  final FeatureFlags flags;

  @ReadOperation()
  Map<String, bool> features() => flags.all;

  @ReadOperation()
  bool? feature(@Selector() String name) => flags.all[name]; // null answers 404
}
management.endpoints.web.exposure.include=health,features
$ curl localhost:8080/actuator/features
{"search":true,"recommendations":false}
$ curl localhost:8080/actuator/features/search
true

@Endpoint

Parameter Default Meaning
id required The endpoint's id: its path under the base path, and the <id> of its properties
enableByDefault true Whether it is enabled when no property says otherwise
name from the class The bean name

@Endpoint is a @Component: the class must be in the scanned code. The endpoint is found in the bean definitions the generator writes, without reflection.

It follows the same rules as the built-in ones: management.endpoint.features.enabled or .access, management.endpoints.web.exposure.include, management.endpoints.web.path-mapping.features. See Endpoints.

Operations

Element Becomes
@ReadOperation() method A GET (and HEAD) operation. produces: lists its media types
@Selector() parameter A path segment, in order: /actuator/features/{name}
@Selector(match: SelectorMatch.allRemaining) parameter The rest of the path, as a List<String>
another parameter A query parameter, converted to its type; missing (when not nullable) or unconvertible is a 400
a SecurityContext parameter The request's user and roles
a null result 404
a WebEndpointResponse(body:, status:, contentType:) result That status and media type
a Future result Awaited

The result is written as JSON. Only read operations exist so far: there is no @WriteOperation or @DeleteOperation.

@EndpointWebExtension

A web extension replaces operations of an endpoint over HTTP, for example to answer another status, as the health endpoint's extension does:

@EndpointWebExtension(endpoint: FeaturesEndpoint)
class FeaturesWebExtension {
  FeaturesWebExtension(this.delegate);

  final FeaturesEndpoint delegate;

  @ReadOperation()
  WebEndpointResponse<bool> feature(@Selector() String name) {
    final value = delegate.feature(name);
    return value == null
        ? const WebEndpointResponse(status: 404)
        : WebEndpointResponse(body: value);
  }
}

In Spring (Java)

@Endpoint(id = "features")
@Component
class FeaturesEndpoint {
  @ReadOperation
  Map<String, Boolean> features() { ... }

  @ReadOperation
  Boolean feature(@Selector String name) { ... }
}

The same annotations. Differences: read operations only, no JMX, and the endpoint is found at build time.

See also