Configuring Observability Kit

How to configure Observability Kit and what its default settings are.

Spring Boot Properties
Plain Spring
Standalone
What the Features Control

Everything that instruments ordinary request handling is enabled by default, so most applications need no configuration at all. Four groups of features are opt-in: the two that reach beyond ordinary request handling — UI state size and database monitoring — and the two that would add sensitive or high-cardinality detail to what leaves the application, database-statement and insights-details.

When you need to turn features off or tune them, how you configure the kit depends on how it’s set up.

Setup How to configure

Setup	How to configure
Spring Boot starter	`vaadin.observability.*` properties in `application.properties` (or any Spring property source).
Plain Spring	Most of the same `vaadin.observability.*` keys, read with `@Value`. See Plain Spring for the ones it doesn’t bind.
Standalone	An `ObservabilitySettings` instance, built with its builder and passed to `ObservabilityKit.install()`.

Spring Boot starter

vaadin.observability.* properties in application.properties (or any Spring property source).

Plain Spring

Most of the same vaadin.observability.* keys, read with @Value. See Plain Spring for the ones it doesn’t bind.

Standalone

An ObservabilitySettings instance, built with its builder and passed to ObservabilityKit.install().

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 Export the Metrics.

Spring Boot Properties

With the Spring Boot starter, configure the kit through vaadin.observability.* properties:

Source code

application.properties
# Turn the whole kit off
vaadin.observability.enabled=false

# Or toggle individual feature groups
vaadin.observability.client=false
vaadin.observability.traces=false

The full set of properties:

Property Default Description

Property	Default	Description
`vaadin.observability.enabled`	`true`	Master switch for the auto-configuration. Spring Boot only.
`vaadin.observability.sessions`	`true`	Session count, lifetime, and lock metrics.
`vaadin.observability.uis`	`true`	UI count metrics.
`vaadin.observability.ui-state`	`false`	Per-UI state size: how much component-tree state the server holds for live users. Opt-in, because it costs a tree walk that ordinary request handling doesn’t. See UI State Size.
`vaadin.observability.navigation`	`true`	Navigation timing.
`vaadin.observability.requests`	`true`	Server-side request and RPC timing.
`vaadin.observability.data`	`true`	Data provider count and fetch query timing, plus the page sizes lazy-loading components ask for.
`vaadin.observability.errors`	`true`	Error counters.
`vaadin.observability.client`	`true`	Browser-side timing, errors, and connection state collected from the client.
`vaadin.observability.resync`	`true`	Observe UIDL message resends and client-requested resynchronizations.
`vaadin.observability.database`	`false`	Wrap `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.
`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.
`vaadin.observability.traces`	`true`	Emit tracing spans through the Observation API.
`vaadin.observability.insights`	`true`	Retain failed and over-budget user interactions for the insights endpoint. Failures also need `errors`, and slow interactions also need `requests`. See the Interaction Insights page.
`vaadin.observability.insights-details`	`false`	Allow retained interactions to carry the exception message, the top stack frames, and the raw session ID. Off by default, since the insights payload is meant to be forwarded.
`vaadin.observability.insights-capacity`	`100`	Maximum number of retained records, applied to each buffer rather than shared. Interactions and data provider queries are retained separately, so with both active the total is twice this. The oldest is evicted once a buffer’s cap is reached.
`vaadin.observability.route-cardinality-limit`	`200`	Maximum number of distinct `route` tag values before they collapse to `_other`. Also caps the `component` and `exception` tag values of `vaadin.errors`, since all three derive from application classes and multiply with each other.
`vaadin.observability.client-rate-per-session`	`100`	Client-sample throttling guard: the maximum number of browser samples accepted per UI in each ten-second window. Samples beyond it are rejected and counted in `vaadin.client.throttled`. Set it to `0` to accept every sample.
`vaadin.observability.ui-state-sample-interval`	`10000`	Minimum milliseconds between two measurements of the same UI. One measurement walks that UI’s whole component tree under its session lock, so this is the knob that bounds the cost of `ui-state`.
`vaadin.observability.ui-state-bytes-per-node`	`0`	Bytes per state-tree node, used to project `vaadin.ui.state.size`. `0` publishes no byte figure. See the reference for how to measure a value for your own application.

vaadin.observability.enabled

true

Master switch for the auto-configuration. Spring Boot only.

vaadin.observability.sessions

true

Session count, lifetime, and lock metrics.

vaadin.observability.uis

true

UI count metrics.

vaadin.observability.ui-state

false

Per-UI state size: how much component-tree state the server holds for live users. Opt-in, because it costs a tree walk that ordinary request handling doesn’t. See UI State Size.

vaadin.observability.navigation

true

Navigation timing.

vaadin.observability.requests

true

Server-side request and RPC timing.

vaadin.observability.data

true

Data provider count and fetch query timing, plus the page sizes lazy-loading components ask for.

vaadin.observability.errors

true

Error counters.

vaadin.observability.client

true

Browser-side timing, errors, and connection state collected from the client.

vaadin.observability.resync

true

Observe UIDL message resends and client-requested resynchronizations.

vaadin.observability.database

false

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

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.

vaadin.observability.traces

true

Emit tracing spans through the Observation API.

vaadin.observability.insights

true

Retain failed and over-budget user interactions for the insights endpoint. Failures also need errors, and slow interactions also need requests. See the Interaction Insights page.

vaadin.observability.insights-details

false

Allow retained interactions to carry the exception message, the top stack frames, and the raw session ID. Off by default, since the insights payload is meant to be forwarded.

vaadin.observability.insights-capacity

100

Maximum number of retained records, applied to each buffer rather than shared. Interactions and data provider queries are retained separately, so with both active the total is twice this. The oldest is evicted once a buffer’s cap is reached.

vaadin.observability.route-cardinality-limit

200

Maximum number of distinct route tag values before they collapse to _other. Also caps the component and exception tag values of vaadin.errors, since all three derive from application classes and multiply with each other.

vaadin.observability.client-rate-per-session

100

Client-sample throttling guard: the maximum number of browser samples accepted per UI in each ten-second window. Samples beyond it are rejected and counted in vaadin.client.throttled. Set it to 0 to accept every sample.

vaadin.observability.ui-state-sample-interval

10000

Minimum milliseconds between two measurements of the same UI. One measurement walks that UI’s whole component tree under its session lock, so this is the knob that bounds the cost of ui-state.

vaadin.observability.ui-state-bytes-per-node

0

Bytes per state-tree node, used to project vaadin.ui.state.size. 0 publishes no byte figure. See the reference for how to measure a value for your own application.

Plain Spring

In a plain-Spring (non-Boot) application, ObservabilityConfiguration reads every vaadin.observability.* key from the Spring Environment, so you set them the same way in your property source and the defaults match the Spring Boot ones. The vaadin.observability.enabled master switch is the exception: it’s specific to the Boot auto-configuration. To disable the kit in plain Spring, don’t import ObservabilityConfiguration.

Three keys are read but have no consumer outside Spring Boot, because the features behind them are wired by the auto-configuration rather than by the instrumentation itself:

vaadin.observability.database and vaadin.observability.database-statement: Database monitoring wraps the DataSource beans through a Boot bean post-processor, so it’s available only with the starter. Setting these in plain Spring has no effect.
vaadin.observability.resync: The property gates the servlet filter that the starter registers. In plain Spring, register SpringResyncDetectionFilter yourself, mapped to /* at the highest precedence, and leave it out to turn the feature off — the property alone won’t switch it on or off.

See the Getting Started page for the plain-Spring setup.

Standalone

In a standalone (non-Spring) deployment, build an ObservabilitySettings instance and pass it to ObservabilityKit.install(). Each builder method matches one of the properties above, except that the database toggles have no effect here: wrapping the DataSource beans is Spring Boot work.

Source code

JavaObservabilitySettings settings = ObservabilitySettings.builder()
        .client(false)
        .traces(false)
        .routeCardinalityLimit(500)
        .build();

ObservabilityKit.install(meterRegistry, settings);

For standalone no enabled flag exists; to disable the kit, don’t call install().

This two-argument overload creates an ObservationRegistry internally — but only when traces is left on — and doesn’t expose it. To use your own, which you need for exporting spans or for writing custom Observations, pass it explicitly; see Standalone (Without Spring).

Resync detection has no auto-configuration outside Spring. Register the portable ResyncDetectionFilter yourself against /*, early enough that it precedes anything else reading the request body:

Source code

JavaFilterRegistration.Dynamic registration = servletContext.addFilter(
        "vaadinResyncDetection", new ResyncDetectionFilter(meterRegistry));
// isMatchAfter=false, so it precedes already-registered filters.
registration.addMappingForUrlPatterns(null, false, "/*");

What the Features Control

The feature toggles map directly to the built-in meters and spans:

Feature What it records

Feature	What it records
`sessions`	Active session gauge, session-created counter, session-lifetime timer, and session-lock wait/hold timers.
`uis`	Active UI gauge and UI-created counter.
`ui-state`	Aggregate gauges of retained UI state — state-tree nodes, components, and views, as totals and per-UI and per-session maxima. Off by default.
`navigation`	Server-side navigation timing, tagged by route, outcome, and error.
`requests`	Server-side request and RPC timing.
`data`	Data provider count and fetch query timing, and the items each fetch asked for against what it returned. Also gates the data query insights.
`errors`	Server-side error counter, tagged by exception, route, and component. Also decorates the session error handler, which is what makes the failures Flow routes there countable and attributable to a component.
`client`	Browser-observed signals — bootstrap, navigation, and Web Vitals timing, client errors, and connection-state transitions with their downtime.
`resync`	A counter of UIDL message resends and client-requested resynchronizations, tagged by type.
`database`	JDBC result-set row counts per route and, when tracing is on, a span per query. Spring Boot starter only, off by default.
`traces`	Tracing spans for the request lifecycle, navigation, RPC, executor tasks, data provider queries, and — with database monitoring on — JDBC queries, emitted through the Observation API.
`insights`	Retained failed and over-budget interactions and data provider queries, served by the insights endpoint. This one records no meters or spans; see the Interaction Insights 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.

ui-state

Aggregate gauges of retained UI state — state-tree nodes, components, and views, as totals and per-UI and per-session maxima. Off by default.

navigation

Server-side navigation timing, tagged by route, outcome, and error.

requests

Server-side request and RPC timing.

data

Data provider count and fetch query timing, and the items each fetch asked for against what it returned. Also gates the data query insights.

errors

Server-side error counter, tagged by exception, route, and component. Also decorates the session error handler, which is what makes the failures Flow routes there countable and attributable to a component.

client

Browser-observed signals — bootstrap, navigation, and Web Vitals timing, client errors, and connection-state transitions with their downtime.

resync

A counter of UIDL message resends and client-requested resynchronizations, tagged by type.

database

JDBC result-set row counts per route and, when tracing is on, a span per query. Spring Boot starter only, off by default.

traces

Tracing spans for the request lifecycle, navigation, RPC, executor tasks, data provider queries, and — with database monitoring on — JDBC queries, emitted through the Observation API.

insights

Retained failed and over-budget interactions and data provider queries, served by the insights endpoint. This one records no meters or spans; see the Interaction Insights page.

For the exact meter and span names produced by each feature, see the Reference page.

27B2E4EF-7AF3-41F8-9CFF-928963337D56

Docs

Docs

Configuring Observability Kit

Spring Boot Properties

Plain Spring

Standalone

What the Features Control