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.