Docs

Docs

Configuring Observability Kit

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

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

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

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

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
Java
ObservabilitySettings 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
Java
FilterRegistration.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

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, data provider queries, and browser errors, 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

Updated –