Overview
In Helidon 4 all observability features were moved to one logical module: observe. Observability features specified by MicroProfile—such as metrics and health—keep their familiar endpoints. The endpoints for other observability features are grouped together under a single context root which defaults to /observe.
Maven Coordinates
You do not need to explicitly add any observability dependency in your Helidon MP project pom.xml file for MicroProfile technologies.
Adding a dependency on Helidon’s MP metrics or health component, for example, brings along the necessary observability components automatically.
To include other observability features in your Helidon MP application, add one or more of the following dependencies.
For Info Observability features:
<dependency>
<groupId>io.helidon.webserver.observe</groupId>
<artifactId>helidon-webserver-observe-info</artifactId>
</dependency>For Logging Observability features:
<dependency>
<groupId>io.helidon.webserver.observe</groupId>
<artifactId>helidon-webserver-observe-log</artifactId>
</dependency>For Configuration Observability features:
<dependency>
<groupId>io.helidon.webserver.observe</groupId>
<artifactId>helidon-webserver-observe-config</artifactId>
</dependency>Usage
The MicroProfile observability features use top-level endpoints (such as /health and /metrics) which you can customize if you wish. See the configuration section below for more information.
Other observability features add endpoints under the /observe path
Feature Weight and Endpoint Conflicts
In some ways Helidon treats all types of observers as a single observability feature. In particular, you can use configuration to control the weight of the various Helidon features, and the weight prescribes the order in which Helidon handles routing for those features.
The Helidon-provided feature for processing your application endpoints has weight 100 by default, and the observability feature has default weight 80. This means that Helidon normally prioritizes routing for your application endpoints over the endpoints for the observers such as metrics and health.
This can have unexpected results if your application declares a resource path /{name}. Because Helidon normally prioritizes the routing of your endpoints, Helidon routes requests for /metrics and /health to your /{name} endpoint instead of to the actual metrics and health endpoints.
One way to avoid this is to assign a weight from 101 to 200 to the observe feature in your configuration. Then Helidon prioritizes the routing of the observe feature ahead of routing your application endpoints.
META-INF/microprofile-config.properties Assigning Feature Weight to Control Routingserver.features.observe.weight = 120Helidon does not enforce the weight range 101-200 for observability, but you should use a value in this range for the observe weight to avoid problems with other features such as security, CORS, and others; their relative ordering is important.
Endpoints
Some observer endpoints—metrics and health—were present in earlier releases of Helidon MP. By default those continue to use their customary paths (/metrics, /health). You can customize the endpoint for each of those observers are described in the documentation for each observer.
Other observers have no counterpart in the MicroProfile spec and they respond by default at subpaths of /observe as described below.
Configuration Observability
Configuration observability allows reading the current application configuration values. Configuration observability defines the following endpoints:
| Endpoint | Method | Action |
|---|---|---|
|
|
Returns the current configuration profile |
|
|
Returns the current configuration values |
|
|
Returns specified by |
|
Note
|
All secrets and passwords are obfuscated with "*" characters. |
Health Observability
Health observability allows reading application readiness to serve requests, whether the services are alive. Health observability defines the following endpoints:
| Endpoint | Method | Action |
|---|---|---|
|
|
Returns Service Readiness |
|
|
Returns whether the service is alive |
|
|
Returns whether the service is started |
|
|
Returns Service |
|
|
Returns whether the service |
|
|
Returns whether the service |
|
|
Returns all checks for service |
|
|
Returns Service Readiness without details |
|
|
Returns whether the service is alive without details |
|
|
Returns whether the service is started without details |
|
|
Returns Service |
|
|
Returns whether the service |
|
|
Returns whether the service |
|
|
Returns all checks for service |
For more information, please, check Health documentation.
Information Observability
Info observability allows configuration of custom properties to be available to users. Information observability defines the following endpoints:
| Endpoint | Method | Action |
|---|---|---|
|
|
Returns the Application information |
|
|
Returns the Application information for the specified |
Logger Observability
Log observability allows reading and configuring of log levels of various loggers and reading log messages. Logger Observability defines the following endpoints:
| Endpoint | Method | Action |
|---|---|---|
|
|
Stream logs (if enabled) |
|
|
Returns all logger handlers |
|
|
Returns the Logger by name |
|
|
Set Logger level by name |
|
|
Unset the specified logger |
Metrics Observability
Helidon distinguishes among three general types, or scopes, of metrics.
| Type/scope | Typical Usage |
|---|---|
base |
OS or Java runtime measurements (available heap, disk space, etc.). |
vendor |
Implemented by vendors, including the |
application |
Declared via annotations or programmatically registered by your service code. |
When you add the metrics dependency to your project, Helidon automatically provides a built-in REST endpoint /observe/metrics which responds with a report of the registered metrics and their values.
Clients can request a particular output format.
| Format | Requested by |
|---|---|
OpenMetrics (Prometheus) |
default ( |
JSON |
Header |
Clients can also limit the report by appending the metric type to the path:
-
/observe/metrics/base -
/observe/metrics/vendor -
/observe/metrics/application
For more information see Metrics documentation.
Configuration
To customize the endpoint of an observer:
-
For MicroProfile technologies (metrics, health) refer to the Helidon MP documentation for them:
-
metrics config documentation
-
health config documentation
-
-
For other observers, assign a custom endpoint using a config setting such as
server.features.observe.info.endpoint.
To control the observability features as a whole, add config settings under server.features.observe.
observeThis type provides the following service implementations:
-
io.helidon.webserver.spi.ServerFeatureProvider
Configuration options
| key | type | default value | description |
|---|---|---|---|
|
|
Cors support inherited by each observe provider, unless explicitly configured. |
|
|
boolean |
|
Whether the observe support is enabled. |
|
string |
|
Root endpoint to use for observe providers. By default, all observe endpoint are under this root endpoint. Example: If root endpoint is |
|
io.helidon.webserver.observe.spi.Observer[] (service provider interface) Such as: |
|
Observers to use with this observe features. Each observer type is registered only once, unless it uses a custom name (default name is the same as the type). |
|
string[] |
|
Sockets the observability endpoint should be exposed on. If not defined, defaults to the default socket (io.helidon.webserver.WebServer.DEFAULT_SOCKET_NAME. Each observer may have its own configuration of sockets that are relevant to it, this only controls the endpoints! |
|
double |
|
Change the weight of this feature. This may change the order of registration of this feature. By default, observability weight is ObserveFeature.WEIGHT so it is registered after routing. |
Additional Information
The Observability features are now implemented with HttpFeature and can be registered with HttpRouting.Builder#addFeature(java.util.function.Supplier). Such a feature encapsulates a set of endpoints, services and/or filters.
Feature is similar to HttpService but gives more freedom in setup.
Main difference is that a feature can add Filter filters and it cannot be registered on a path (that is left to the discretion of the feature developer).
-
Features are not registered immediately - each feature can define a
Weightor implementWeightedto order features according to their weight. Higher weighted features are registered first. -
This is to allow ordering of features in a meaningful way (e.g. Context should be first, Tracing second, Security third etc).