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 from the Spring `Environment`. 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 from the Spring Environment. 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`	Count client message resends, client-requested resynchronizations, and messages with an unexpected ID.
`vaadin.observability.database`	`false`	Wrap `DataSource` beans to record JDBC result-set row counts per route, report the SQL work behind each slow data query insight, 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.database-span-limit`	`100`	Maximum number of `vaadin.db.query` spans under any one parent span — a request, an RPC, or a data provider fetch. Queries beyond it are still timed and counted, but get no span. `0` spans no query that has a parent span. At most `10000`. See N+1 Loads and the Span Limit.
`vaadin.observability.traces`	`true`	Emit tracing spans through the Observation API.
`vaadin.observability.traces-session-id`	`false`	Include the HTTP session ID as the `vaadin.session.id` attribute of the `vaadin.request.<type>` span. Span-only; it never becomes a metric tag.
`vaadin.observability.insights`	`true`	Retain failed and over-budget user interactions, and the errors browsers report, for the insights endpoint. Failures also need `errors`, slow interactions also need `requests`, and browser errors also need `client`. 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, and retained browser errors their message and function name. Off by default, since the insights payload is meant to be forwarded. For a browser error it governs collection rather than only retention, and is read by a page when it loads.
`vaadin.observability.insights-capacity`	`100`	Maximum number of retained records, applied to each buffer rather than shared. Interactions, data provider queries, and browser errors are retained separately, so with all three active the total is three times this. The oldest is evicted once a buffer’s cap is reached. At most `10000`.
`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. With tracing off, it also caps the `error` tag of `vaadin.request.duration` and `vaadin.rpc.duration`. At most `1000`.
`vaadin.observability.client-rate-per-session`	`100`	Client-sample throttling guard: the maximum number of browser samples accepted per session in each ten-second window. All tabs of a session share the budget. 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.ui-state-growth-samples`	`5`	Number of measurements a collection held in a view field has to grow in, without shrinking, before it’s reported as growing. `0` doesn’t read view collections at all. Takes effect only with `ui-state` on. See State Outside the Tree.

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

Count client message resends, client-requested resynchronizations, and messages with an unexpected ID.

vaadin.observability.database

false

Wrap DataSource beans to record JDBC result-set row counts per route, report the SQL work behind each slow data query insight, 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.database-span-limit

100

Maximum number of vaadin.db.query spans under any one parent span — a request, an RPC, or a data provider fetch. Queries beyond it are still timed and counted, but get no span. 0 spans no query that has a parent span. At most 10000. See N+1 Loads and the Span Limit.

vaadin.observability.traces

true

Emit tracing spans through the Observation API.

vaadin.observability.traces-session-id

false

Include the HTTP session ID as the vaadin.session.id attribute of the vaadin.request.<type> span. Span-only; it never becomes a metric tag.

vaadin.observability.insights

true

Retain failed and over-budget user interactions, and the errors browsers report, for the insights endpoint. Failures also need errors, slow interactions also need requests, and browser errors also need client. 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, and retained browser errors their message and function name. Off by default, since the insights payload is meant to be forwarded. For a browser error it governs collection rather than only retention, and is read by a page when it loads.

vaadin.observability.insights-capacity

100

Maximum number of retained records, applied to each buffer rather than shared. Interactions, data provider queries, and browser errors are retained separately, so with all three active the total is three times this. The oldest is evicted once a buffer’s cap is reached. At most 10000.

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. With tracing off, it also caps the error tag of vaadin.request.duration and vaadin.rpc.duration. At most 1000.

vaadin.observability.client-rate-per-session

100

Client-sample throttling guard: the maximum number of browser samples accepted per session in each ten-second window. All tabs of a session share the budget. 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.ui-state-growth-samples

5

Number of measurements a collection held in a view field has to grow in, without shrinking, before it’s reported as growing. 0 doesn’t read view collections at all. Takes effect only with ui-state on. See State Outside the Tree.

Values outside the allowed range of a numeric property are rejected at startup with an IllegalArgumentException, rather than silently clamped.

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.

The database keys — vaadin.observability.database, vaadin.observability.database-statement, and vaadin.observability.database-span-limit — have no effect outside Spring Boot. Database monitoring wraps the DataSource beans through a Boot bean post-processor, so it’s available only with the starter.

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

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 — and of the collections views hold in their own fields. With `insights` on, also reports view fields that keep growing as insights. 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, UIDL request and rendering, and Web Vitals timing, client errors, and connection-state transitions with their downtime.
`resync`	A counter of client message resends, client-requested resynchronizations, and messages with an unexpected ID, tagged by type.
`database`	JDBC result-set row counts per route, the SQL work behind slow data query insights, 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, data provider queries, and browser errors, and — with `ui-state` on — growing view state, 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 — and of the collections views hold in their own fields. With insights on, also reports view fields that keep growing as insights. 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, UIDL request and rendering, and Web Vitals timing, client errors, and connection-state transitions with their downtime.

resync

A counter of client message resends, client-requested resynchronizations, and messages with an unexpected ID, tagged by type.

database

JDBC result-set row counts per route, the SQL work behind slow data query insights, 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, data provider queries, and browser errors, and — with ui-state on — growing view state, 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