diff --git a/docs/se/observability.adoc b/docs/se/observability.adoc new file mode 100644 index 00000000000..66deebf96aa --- /dev/null +++ b/docs/se/observability.adoc @@ -0,0 +1,318 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2023 Oracle and/or its affiliates. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +/////////////////////////////////////////////////////////////////////////////// + += Tracing +:description: Helidon SE Observability +:feature-name: Helidon Observability +:keywords: helidon, observability +:rootdir: {docdir}/.. + +include::{rootdir}/includes/se.adoc[] + +== Contents + +- <> +- <> +- <> +- <> +- <> +- <> + +== Overview + +In Helidon 4 all observability features were moved to one logical module: `observe`. The observability support groups all observe endpoints together under a single context root (the default behavior) `/observe`. + +include::{rootdir}/includes/dependencies.adoc[] + +// tag::observe-dependency[] +[source,xml] +---- + + io.helidon.webserver.observe + helidon-webserver-observe + +---- +// end::observe-dependency[] + +For Health Observability features: + +// tag::observe-health-dependency[] +[source,xml] +---- + + io.helidon.webserver.observe + helidon-webserver-observe-health + +---- +// end::observe-health-dependency[] + +For Metrics Observability features: + +// tag::observe-metrics-dependency[] +[source,xml] +---- + + io.helidon.webserver.observe + helidon-webserver-observe-metrics + +---- +// end::observe-metrics-dependency[] + +For Info Observability features: + +// tag::observe-info-dependency[] +[source,xml] +---- + + io.helidon.webserver.observe + helidon-webserver-observe-info + +---- +// end::observe-info-dependency[] + +For Logging Observability features: + +// tag::observe-log-dependency[] +[source,xml] +---- + + io.helidon.webserver.observe + helidon-webserver-observe-log + +---- +// end::observe-log-dependency[] + + +== Usage + +Each provider usually adds a new endpoint (such as `health`, `metrics`). +This is to have a single easily configurable path for security, proxy etc. purposes, rather than expose multiple "root" endpoints that may collide with the business code. + +=== Discovery + +`ObserveProvider` instances are discovered using `ServiceLoader`. In case an explicit `Observer` is registered with the +same `type` as a provider, the provider will not be used (so we do not duplicate services). + +=== Endpoints + +The "Observe" service endpoint can be modified on the `ObserveFeature` that is registered with routing. The feature endpoint defaults to `/observe`, and all observers are prefixed with it (see further) + +Each observer has customizable endpoints as well, and the result is decided as follows: +1. If the custom endpoint is relative, the result would be under observe endpoint (e.g. for `health` -> `/observe/health`) +2. If the custom endpoint is absolute, the result would be absolute as well (e.g. for `/health` -> `/health`) + +==== Configuration Observability + +Configuration observability allows reading the current application configuration values. +Configuration observability defines the following endpoints: + +|=== +|Endpoint |Method |Action + +|`/config/profile` +|`GET` +|Returns the current configuration profile + +|`/config/values` +|`GET` +|Returns the current configuration values + +|`/config/values/{name}` +|`GET` +|Returns specified by `name` configuration value +|=== + +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 + +|`/health/ready` +|`GET` +|Returns Service Readiness + +|`/health/live` +|`GET` +|Returns whether the service is alive + +|`/health/started` +|`GET` +|Returns whether the service is started + +|`/health/ready/{name}` +|`GET` +|Returns Service `name` Readiness + +|`/health/live/{name}` +|`GET` +|Returns whether the service `name` is alive + +|`/health/started/{name}` +|`GET` +|Returns whether the service `name` is started + +|`/health/check/{name}` +|`GET` +|Returns all checks for service `name` + +|`/health/ready` +|`HEAD` +|Returns Service Readiness without details + +|`/health/live` +|`HEAD` +|Returns whether the service is alive without details + +|`/health/started` +|`HEAD` +|Returns whether the service is started without details + +|`/health/ready/{name}` +|`HEAD` +|Returns Service `name` Readiness without details + +|`/health/live/{name}` +|`HEAD` +|Returns whether the service `name` is alive without details + +|`/health/started/{name}` +|`HEAD` +|Returns whether the service `name` is started without details + +|`/health/check/{name}` +|`HEAD` +|Returns all checks for service `name` without details + +|=== + +For more information, please, check xref:{rootdir}/se/health.adoc[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 + +|`/info` +|`GET` +|Returns the Application information + +|`/info/{name}` +|`GET` +|Returns the Application information for the specified `name` + +|=== + + +==== 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 + +|`/log` +|`GET` +|Stream logs (if enabled) + +|`/log/loggers` +|`GET` +|Returns all logger handlers + +|`/log/log/loggers/{logger}` +|`GET` +|Returns the Logger by name `logger` + +|`/log/loggers/{logger}` +|`POST` +|Set Logger level by name `logger` + +|`/log/loggers/{logger}` +|`DELETE` +|Unset the specified logger `logger` + +|=== + +==== Metrics Observability + +Helidon distinguishes among three general _types_, or scopes, of metrics. + +.Types (scopes) of metrics +[%autowidth] +|==== +| Type/scope | Typical Usage + +| base | OS or Java runtime measurements (available heap, disk space, etc.). +| vendor | Implemented by vendors, including the `REST.request` metrics and other key performance indicator measurements. +| 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. + +.Formats for `/observe/metrics` output +[%autowidth] +|==== +| Format | Requested by + +| OpenMetrics (Prometheus) | default (`text/plain`) +| JSON | Header `Accept: application/json` +|==== + +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 xref:{rootdir}/se/metrics/metrics.adoc[Metrics] documentation. + +== Configuration + +To customize the endpoint of an observer: + +1. Configure a custom endpoint through configuration to modify the `ObserveProvider` setup (such as `observe.health.endpoint`) +2. Configure a custom endpoint through a builder on the specific `Observer` (`HealthObserver.builder().endpoint("myhealth")`) + + +== 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 `Weight` or implement `Weighted` to 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.). + + +== Reference + +* https://download.eclipse.org/microprofile/microprofile-metrics-5.0.0/microprofile-metrics-spec-5.0.0.pdf[MicroProfile Metrics Specification] +* xref:{rootdir}/se/metrics/metrics.adoc[Metrics] documentation. +* xref:{rootdir}/se/health.adoc[Health] documentation. \ No newline at end of file diff --git a/docs/sitegen.yaml b/docs/sitegen.yaml index 753184228ed..bcccdd47180 100644 --- a/docs/sitegen.yaml +++ b/docs/sitegen.yaml @@ -414,6 +414,12 @@ backend: - "openapi.adoc" - "openapi-generator.adoc" - "openapi-ui.adoc" + - type: "PAGE" + title: "Observability" + source: "observability.adoc" + glyph: + type: "icon" + value: "search" - type: "PAGE" title: "Reactive Messaging" source: "reactive-messaging.adoc"