> Markdown version of [Configuration](https://vaadin.com/docs/next/tools/observability/configuration). Section index: [llms.txt](https://vaadin.com/docs/next/tools/llms.txt)
# Configuring Observability Kit
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](https://vaadin.com/docs/next/tools/observability/reference.md#ui-state-size) and [database monitoring](https://vaadin.com/docs/next/tools/observability/reference.md#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](#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](https://vaadin.com/docs/next/tools/observability/getting-started.md#export-the-metrics).
## Spring Boot Properties
With the Spring Boot starter, configure the kit through `vaadin.observability.*` properties:
`application.properties`
```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](https://vaadin.com/docs/next/tools/observability/reference.md#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](https://vaadin.com/docs/next/tools/observability/insights.md#slow-query-sql), 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](https://vaadin.com/docs/next/tools/observability/reference.md#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.` 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](https://vaadin.com/docs/next/tools/observability/insights.md) 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](https://vaadin.com/docs/next/tools/observability/reference.md#nodes-not-bytes) 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](https://vaadin.com/docs/next/tools/observability/reference.md#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](https://vaadin.com/docs/next/tools/observability/getting-started.md#other-setups) 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.
```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)](https://vaadin.com/docs/next/tools/observability/getting-started.md#standalone).
## 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 — 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](https://vaadin.com/docs/next/tools/observability/insights.md) page. |
For the exact meter and span names produced by each feature, see the [Reference](https://vaadin.com/docs/next/tools/observability/reference.md) page.
`27B2E4EF-7AF3-41F8-9CFF-928963337D56`