Skip to content

feat: update observability documentation #5769

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
caalador wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

feat: update observability documentation #5769

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d6a5022
feat: update observability documentation
caalador Jun 30, 2026
91acf90
Add integrations documents
caalador Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/styles/config/vocabularies/Docs/accept.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ Codeium
[cC]onfig(|uration|ure|urer|urator|map)
[cC]onformant
[cC]ontainer-less
Contentful
Coolors
Corretto
# Vale spelling doesn't recognize "Spring Data's"
Expand Down Expand Up @@ -259,8 +260,10 @@ Workbox
WSL
Xcode
XPath
Zipkin

# Accepted abbreviations whose plural and/or possessive forms otherwise give an error
AOP
API
APIs
CDN
Expand All @@ -270,8 +273,11 @@ IDE
JDK
MVC
LLMs
OTLP
PWA
RPC
SLA
SLAs
SPI
SSDs
SVG
Expand Down
269 changes: 96 additions & 173 deletions articles/tools/observability/configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,237 +1,160 @@
---
title: Configuration
page-title: Configuring Observability Kit for Vaadin applications
description: How to configure Observability Kit and what are its default settings.
description: How to configure Observability Kit and what its default settings are.
meta-description: Learn to set up and manage the Observability Kit for monitoring your Vaadin applications effectively.
order: 20
---


= Configuring Observability Kit

Instrumentation can be configured in the [filename]`agent.properties` file that's used with the Java agent.
Every feature of Observability Kit is enabled by default, so most applications need no configuration at all.
When you do need to turn features off or tune them, how you configure the kit depends on how it's set up.

[cols="1,3"]
|===
|Setup |How to configure

== Service Configuration

The `service` attributes are used to differentiate traces from services or applications which might have many instances running simultaneously, such as horizontally scaled services.

The service attributes are as follows:

[unordered]
`service.name`:: is an attribute that's used to distinguish a service by name. The default value is `vaadin` -- the only attribute with a default value. It's also the only one required.
`service.namespace`:: helps to distinguish a group of services.
`service.instance.id`:: helps to distinguish instances of the same service that exist simultaneously. It must be unique for each instance of the same `service.namespace`, `service.name` pair.
`service.version`:: is the semantic versioning string of the service version.

The `service.name` attribute is configured using the `otel.service.name` property, either in the [filename]`agent.properties` configuration file as a system property, or as an environment variable.
|Spring Boot starter
|`vaadin.observability.*` properties in [filename]`application.properties` (or any Spring property source).

[.example]
--
Add the following line to the [filename]`agent.properties` file:
|Plain Spring
|The same `vaadin.observability.*` keys, read with `@Value`.

[source,properties]
----
<source-info group="Configuration file"></source-info>
otel.service.name=myapp
----
|Standalone
|An [classname]`ObservabilitySettings` instance, built with its builder and passed to [methodname]`ObservabilityKit.install()`.
|===

Pass the `otel.service.name` system property when starting the Java process.
[source,terminal]
----
<source-info group="System property"></source-info>
java -Dotel.service.name="myapp" ...
----
NOTE: Configuration covers only the kit's own instrumentation.
Service identity (service name and resource attributes) and metric *export* are part of your Micrometer and Spring Boot Actuator setup, not the kit -- see <<getting-started#export-the-metrics,Export the Metrics>>.

Define the `OTEL_SERVICE_NAME` environment variable before starting the Java process.
[source,terminal]
----
<source-info group="Environment variable"></source-info>
# Linux / macOS
export OTEL_SERVICE_NAME="myapp"
# Windows
set OTEL_SERVICE_NAME="myapp"
----

--
== Spring Boot Properties

Other service attributes are configured using the `otel.resource.attributes` property, either in the [filename]`agent.properties` configuration file as a system property, or as en environment variable. Multiple attributes are separated by commas.
With the Spring Boot starter, configure the kit through `vaadin.observability.*` properties:

[.example]
--
Add the following line to the [filename]`agent.properties` file:
.`application.properties`
[source,properties]
----
<source-info group="Configuration file"></source-info>
otel.resource.attributes=service.namespace=myservices,service.instance.id=myapp-eu
----

Pass the `otel.resource.attributes` system property when starting the Java process.
[source,terminal]
----
<source-info group="System property"></source-info>
java -Dotel.resource.attributes="service.namespace=myservices,service.instance.id=myapp-eu" ...
----

Define the `OTEL_RESOURCE_ATTRIBUTES` environment variable before starting the Java process.
[source,terminal]
----
<source-info group="Environment variable"></source-info>
# Linux / macOS
export OTEL_RESOURCE_ATTRIBUTES="service.namespace=myservices,service.instance.id=myapp-eu"
# Windows
set OTEL_RESOURCE_ATTRIBUTES="service.namespace=myservices,service.instance.id=myapp-eu"
----

--

For more information about service configuration, see the https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/#service[OpenTelemetry documentation].


== Default OpenTelemetry Instrumentation

The custom distribution disables default OpenTelemetry instrumentation for Vaadin and servlets.

The default instrumentation is disabled because logging all requests for a single-page application isn't helpful -- although it does generate plenty of data. It was disabled to have control over which requests generate a trace.
# Turn the whole kit off
vaadin.observability.enabled=false

The `jetty`, `servlet`, and `tomcat` instrumentation modules are disabled by default. To enable any of them, add the following line to the [filename]`agent.properties` file:

[source,properties]
# Or toggle individual feature groups
vaadin.observability.client=false
vaadin.observability.traces=false
----
otel.instrumentation.${instrumentationName}.enabled=true
----

== Frontend Observability Configuration

:prerelease-feature: Frontend Observability
:artifact-id: observability-kit-starter
:version: 2.1-SNAPSHOT
include::{articles}/flow/_prerelease-banner.adoc[opts=optional]

Frontend observability is enabled by default, with all the client-side instrumentation active. The configuration can be tuned in two ways: statically by editing the [filename]`agent.properties` file, or by providing environment variables or system properties; or dynamically by implementing the [interfacename]`ObservabilityClientConfigurer` interface, which applies changes at runtime.

With static configuration, the same settings are applied to all UI instances. Changes to the configuration require a server restart.

With dynamic configuration, the instrumentation can be enabled or disabled at runtime, without restarting the server. The configuration can also be tuned for a specific browser tab. Changes are applied when the browser page is reloaded.
The full set of properties:

[cols="2,1,3"]
|===
|Property |Default |Description

=== Frontend Observability Static Configuration

Static frontend observability configuration can be provided by adding entries to the [filename]`agent.properties` file or with environment variables or system properties, as mentioned earlier.

The following properties can be used to tune frontend instrumentation:
|`vaadin.observability.enabled`
|`true`
|Master switch for the auto-configuration.
Spring Boot only.

[cols="4,4,1"]
|===
|Property Name |Description |Default Value
|`vaadin.observability.sessions`
|`true`
|Session count, lifetime, and lock metrics.

|`otel.instrumentation.vaadin.frontend.enabled`
|Enables or disables all frontend instrumentation.
|`vaadin.observability.uis`
|`true`
|UI count metrics.

|`otel.instrumentation.vaadin.frontend.document-load`
|Enables or disables the Document Load instrumentation.
|`vaadin.observability.navigation`
|`true`
|Navigation timing.

|`otel.instrumentation.vaadin.frontend.user-interaction`
|Enables or disables the User Interaction instrumentation.
|`vaadin.observability.requests`
|`true`
|Server-side request and RPC timing.

|`otel.instrumentation.vaadin.frontend.xml-http-request`
|Enables or disables the XML HTTP Request instrumentation.
|`vaadin.observability.errors`
|`true`
|Error counters.

|`otel.instrumentation.vaadin.frontend.long-task`
|Enables or disables the Long Task instrumentation.
|`vaadin.observability.client`
|`true`
|Browser-side timing collected from the client.

|`otel.instrumentation.vaadin.frontend.frontend-error`
|Enables or disables the Frontend Error instrumentation.
|`vaadin.observability.traces`
|`true`
|Emit tracing spans through the Observation API.

|`vaadin.observability.traces-session-id`
|`false`
|Include the session ID as a span attribute.

|`vaadin.observability.route-cardinality-limit`
|`200`
|Maximum number of distinct `route` tag values before they collapse to `_other`.

|`vaadin.observability.client-rate-per-session`
|`100`
|Maximum number of client-side samples accepted per session, as a throttling guard.
|===

For more information about the frontend instrumentation, consult the <<reference#frontend-traces,Observability Kit Reference>> page.

== Plain Spring

In a plain-Spring (non-Boot) application, the same feature-toggle keys are read with `@Value`, so you set them the same way in your property source.
The `vaadin.observability.enabled` master switch is specific to the Spring Boot auto-configuration; to disable the kit in plain Spring, don't import [classname]`ObservabilityConfiguration`.

=== Frontend Observability Runtime Configuration (Flow)
See the <<getting-started#other-setups,Getting Started>> page for the plain-Spring setup.

By default, frontend observability enables all out-of-the-box client-side instrumentation. Observability Kit provides a way to enable, disable and tune the instrumentation at runtime.

This is done by implementing the [interfacename]`ObservabilityClientConfigurer` interface and applying the desired settings to the [interfacename]`ObservabilityClientConfiguration` instance provided to the [methodname]`configure` method. The configuration is applied during UI initialization: The Configurer logic can access the current [classname]`VaadinRequest`. If a security infrastructure has been configured for a project and the user is logged into the application, the user details can also be accessed. This allows fine-tuning of observability to single-user level.
== Standalone

For example, the following implementation shows how to set up observability based on a mutable configuration tied to the currently logged-in user.
In a standalone (non-Spring) deployment, build an [classname]`ObservabilitySettings` instance and pass it to [methodname]`ObservabilityKit.install()`.
Each builder method matches one of the properties above.

.`UserBasedFrontendObservability.java`
[source,java]
----
include::{root}/src/main/java/com/vaadin/demo/observability/UserBasedFrontendObservability.java[tags=full-class,indent=0]
ObservabilitySettings settings = ObservabilitySettings.builder()
.client(false)
.traces(false)
.routeCardinalityLimit(500)
.build();

ObservabilityKit.install(meterRegistry, settings);
----

With the above implementation, the configuration can be fetched from a database table. This allows changes to be applied at runtime after a browser page reload.
For standalone no `enabled` flag exists; to disable the kit, don't call [methodname]`install()`.

The Configurer is loaded through the Java ServiceLoader API, by adding the file [filename]`com.vaadin.observability.ObservabilityClientConfigurer` to the [filename]`src/main/resources/META-INF/services/` directory, with the content being the fully qualified name of the Configurer class. For this example, the file looks like this:

`com.vaadin.observability.ObservabilityClientConfigurer`
[source]
----
org.example.UserBasedFrontendObservability
----
== What the Features Control

For details on observability client settings, consult the Javadocs of the [interfacename]`ObservabilityClientConfiguration` interface.
The feature toggles map directly to the built-in meters and spans:

.Load Configurer in Spring Project
[NOTE]
For Spring based projects, the Configurer can be loaded by exposing the implementation as a Spring managed [annotationname]`@Bean`, without the need to register the class for the ServiceLoader API.
[cols="1,3"]
|===
|Feature |What it records

|`sessions`
|Active session gauge, session-created counter, session-lifetime timer, and session-lock wait/hold timers.

== Frontend Observability Configuration (Hilla)
|`uis`
|Active UI gauge and UI-created counter.

:prerelease-feature: Frontend Observability
:artifact-id: observability-kit-starter
:version: 2.1.1
|`navigation`
|Server-side navigation timing, tagged by route and outcome.

To enable frontend observability, you need to add the `@hilla/observability-kit-client` package to your `package.json` file. After that, you can use the `init` function provided by the package.
|`requests`
|Server-side request and RPC timing.

The `init` function requires two parameters: the `export` method from the `ObservabilityEndpoint` that comes with the starter artifact; and a list of options.
|`errors`
|Server-side error counter, tagged by exception.

The options list has the following structure:
|`client`
|Browser-observed timing -- bootstrap, navigation, server round trip, Web Vitals, and client errors.

[source,typescript]
----
export interface TelemetryInitializationOptions {
/** Specifies URLs to ignore */
ignoredURLs?: readonly string[];
/** Disables tracking of internal Vaadin/Hilla URLs */
ignoreVaadinURLs?: boolean;
/** Frontend-specific `service.instance.id` attribute */
instanceId?: string;
/** Frontend-specific `service.name` attribute */
serviceName?: string;
/** Frontend-specific `service.version` attribute */
serviceVersion?: string;
/** Enables or disables the Document Load instrumentation. */
traceDocumentLoad?: boolean;
/** Enables or disables the Frontend Error instrumentation. */
traceErrors?: boolean;
/** Enables or disables the Long Task instrumentation. */
traceLongTask?: boolean;
/** Enables or disables the User Interaction instrumentation. */
traceUserInteraction?: readonly EventName[] | null;
/** Enables or disables the XML HTTP Request instrumentation. */
traceXmlHTTPRequest?: boolean;
}
----
|`traces`
|Tracing spans for the request lifecycle, navigation, and RPC, emitted through the Observation API.
|===

By default, the options are set as follows:
For the exact meter and span names produced by each feature, see the <<reference#,Reference>> page.

[source,typescript]
----
const options = {
serviceName: 'hilla',
traceDocumentLoad: true,
traceErrors: true,
traceLongTask: true,
traceUserInteraction: ['click'],
traceXmlHTTPRequest: true,
};
----
[discussion-id]`27B2E4EF-7AF3-41F8-9CFF-928963337D56`
Loading
Loading