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

Open
caalador wants to merge 9 commits into
base: main
Choose a base branch
from
Open

feat: update observability documentation #5769

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ff920d8
feat: update observability documentation
caalador Jun 30, 2026
45636b2
Add integrations documents
caalador Jul 1, 2026
742fd96
Update integrations to spring-boot 4
caalador Jul 2, 2026
53ad039
Update with latest added/changed functionality
caalador Jul 20, 2026
f53000c
lint words that are really ment
caalador Jul 20, 2026
aa8ae4f
Minor updates to match the observability-kit state
caalador Aug 17, 2026
7e23cda
Update docs for vaadin/observability-kit#355
caalador Aug 17, 2026
fab3b85
Merge branch 'main' into feat/observability-v5
caalador Aug 20, 2026
307fa1f
Merge branch 'main' into feat/observability-v5
caalador Aug 21, 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
10 changes: 10 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 @@ -34,6 +34,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 @@ -99,6 +100,7 @@ IntelliJ
[iI]nterdependencies
[iI]terable
Jakarta EE
Jaeger('s)?
Jandex
Java
\.java
Expand Down Expand Up @@ -190,7 +192,10 @@ readonly
[rR]enderers?
Roboto
[rR]ollout
[rR]esends?
[rR]esizable
[rR]esync
[rR]esynchronizations?
Scala
[sS]anitization
[sS]cannability
Expand Down Expand Up @@ -260,8 +265,10 @@ Workbox
WSL
Xcode
XPath
Zipkin

# Accepted abbreviations whose plural and/or possessive forms otherwise give an error
AOP
API
APIs
CDN
Expand All @@ -272,8 +279,11 @@ JDK
JREs
MVC
LLMs
OTLP
PWA
RPC
SLA
SLAs
SPI
SSDs
SVG
Expand Down
260 changes: 118 additions & 142 deletions articles/tools/observability/configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,204 +1,180 @@
---
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

|Spring Boot starter
|`vaadin.observability.*` properties in [filename]`application.properties` (or any Spring property source).

== Service Configuration
|Plain Spring
|The same `vaadin.observability.*` keys, read with `@Value`.

The `service` attributes are used to differentiate traces from services or applications which might have many instances running simultaneously, such as horizontally scaled services.
|Standalone
|An [classname]`ObservabilitySettings` instance, built with its builder and passed to [methodname]`ObservabilityKit.install()`.
|===

The service attributes are as follows:
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>>.

[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 Properties

[.example]
--
Add the following line to the [filename]`agent.properties` file:
With the Spring Boot starter, configure the kit through `vaadin.observability.*` properties:

.`application.properties`
[source,properties]
----
<source-info group="Configuration file"></source-info>
otel.service.name=myapp
----
# Turn the whole kit off
vaadin.observability.enabled=false

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" ...
# Or toggle individual feature groups
vaadin.observability.client=false
vaadin.observability.traces=false
----

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"
----
The full set of properties:

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

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.
|`vaadin.observability.enabled`
|`true`
|Master switch for the auto-configuration.
Spring Boot only.

[.example]
--
Add the following line to the [filename]`agent.properties` file:
[source,properties]
----
<source-info group="Configuration file"></source-info>
otel.resource.attributes=service.namespace=myservices,service.instance.id=myapp-eu
----
|`vaadin.observability.sessions`
|`true`
|Session count, lifetime, and lock metrics.

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" ...
----
|`vaadin.observability.uis`
|`true`
|UI count metrics.

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"
----
|`vaadin.observability.navigation`
|`true`
|Navigation timing.

--
|`vaadin.observability.requests`
|`true`
|Server-side request and RPC timing.

|`vaadin.observability.errors`
|`true`
|Error counters.

For more information about service configuration, see the https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/#service[OpenTelemetry documentation].
|`vaadin.observability.client`
|`true`
|Browser-side timing collected from the client.

|`vaadin.observability.resync`
|`true`
|Observe UIDL message resends and client-requested resynchronizations.

== Default OpenTelemetry Instrumentation
|`vaadin.observability.database`
|`false`
|Wrap [classname]`DataSource` beans to record JDBC result-set row counts per route and, when tracing is on, emit a span per query.
Spring Boot starter only.

The custom distribution disables default OpenTelemetry instrumentation for Vaadin and servlets.
|`vaadin.observability.database-statement`
|`false`
|Attach the parameterized SQL as `db.statement` on the query span.
Off by default, since SQL is higher cardinality and can be sensitive.

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.
|`vaadin.observability.traces`
|`true`
|Emit tracing spans through the Observation API.

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:
|`vaadin.observability.route-cardinality-limit`
|`200`
|Maximum number of distinct `route` tag values before they collapse to `_other`.

[source,properties]
----
otel.instrumentation.${instrumentationName}.enabled=true
----
|`vaadin.observability.client-rate-per-session`
|`100`
|Maximum number of client-side samples accepted per session, as a throttling guard.
|===

== Frontend Observability Configuration

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

Frontend observability is enabled by default, with all the client-side instrumentation active. The configuration can be tuned statically by editing the [filename]`agent.properties` file, or by providing environment variables or system properties.
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`.

With static configuration, the same settings are applied to all UI instances. Changes to the configuration require a server restart.
See the <<getting-started#other-setups,Getting Started>> page for the plain-Spring setup.


=== Frontend Observability Static Configuration
== Standalone

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.
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.

The following properties can be used to tune frontend instrumentation:
[source,java]
----
ObservabilitySettings settings = ObservabilitySettings.builder()
.client(false)
.traces(false)
.routeCardinalityLimit(500)
.build();

[cols="4,4,1"]
|===
|Property Name |Description |Default Value
ObservabilityKit.install(meterRegistry, settings);
----

|`otel.instrumentation.vaadin.frontend.enabled`
|Enables or disables all frontend instrumentation.
|`true`
For standalone no `enabled` flag exists; to disable the kit, don't call [methodname]`install()`.

|`otel.instrumentation.vaadin.frontend.document-load`
|Enables or disables the Document Load instrumentation.
|`true`
This two-argument overload creates an [classname]`ObservationRegistry` internally and doesn't expose it.
To use your own -- which you need for exporting spans or for writing custom Observations -- pass it explicitly; see <<getting-started#standalone,Standalone (Without Spring)>>.

|`otel.instrumentation.vaadin.frontend.user-interaction`
|Enables or disables the User Interaction instrumentation.
|`true`

|`otel.instrumentation.vaadin.frontend.xml-http-request`
|Enables or disables the XML HTTP Request instrumentation.
|`true`
== What the Features Control

|`otel.instrumentation.vaadin.frontend.long-task`
|Enables or disables the Long Task instrumentation.
|`true`
The feature toggles map directly to the built-in meters and spans:

|`otel.instrumentation.vaadin.frontend.frontend-error`
|Enables or disables the Frontend Error instrumentation.
|`true`
[cols="1,3"]
|===
|Feature |What it records

For more information about the frontend instrumentation, consult the <<reference#frontend-traces,Observability Kit Reference>> page.
|`sessions`
|Active session gauge, session-created counter, session-lifetime timer, and session-lock wait/hold timers.

|`uis`
|Active UI gauge and UI-created counter.

== Frontend Observability Configuration (Hilla)
|`navigation`
|Server-side navigation timing, tagged by route and outcome.

:prerelease-feature: Frontend Observability
:artifact-id: observability-kit-starter
:version: 2.1.1
|`requests`
|Server-side request and RPC timing.

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.
|`errors`
|Server-side error counter, tagged by exception.

The `init` function requires two parameters: the `export` method from the `ObservabilityEndpoint` that comes with the starter artifact; and a list of options.
|`client`
|Browser-observed timing -- bootstrap, navigation, Web Vitals, and client errors.

The options list has the following structure:
|`resync`
|A counter of UIDL message resends and client-requested resynchronizations, tagged by type.

[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;
}
----
|`database`
|JDBC result-set row counts per route and, when tracing is on, a span per query.
Spring Boot starter only, off by default.

By default, the options are set as follows:
|`traces`
|Tracing spans for the request lifecycle, navigation, and RPC, emitted through the Observation API.
|===

[source,typescript]
----
const options = {
serviceName: 'hilla',
traceDocumentLoad: true,
traceErrors: true,
traceLongTask: true,
traceUserInteraction: ['click'],
traceXmlHTTPRequest: true,
};
----
For the exact meter and span names produced by each feature, see the <<reference#,Reference>> page.

[discussion-id]`27B2E4EF-7AF3-41F8-9CFF-928963337D56`
Loading
Loading