> Markdown version of [Reference](https://vaadin.com/docs/next/tools/observability/reference). Section index: [llms.txt](https://vaadin.com/docs/next/tools/llms.txt)
# Observability Kit Reference
Observability Kit instruments the Vaadin runtime and records everything into your application’s Micrometer `MeterRegistry`. Metrics are plain Micrometer meters; tracing spans are emitted through the Micrometer Observation API. Both flow to whatever backend you’ve configured — see the [Integrations](https://vaadin.com/docs/next/tools/observability/integrations.md) page.
Each group of meters and spans is controlled by a feature toggle (for example `vaadin.observability.sessions`). See the [Configuration](https://vaadin.com/docs/next/tools/observability/configuration.md) page for how to turn features on or off.
> **Note: Naming Conventions**
>
> Meter names follow Micrometer’s dotted, lowercase convention (for example `vaadin.request.duration`). How a name appears in your backend depends on the conventions of that backend — Prometheus, for instance, renders `vaadin.request.duration` as `vaadin_request_duration_seconds` with `_count`, `_sum`, and `_max` suffixes. Two renames are easy to trip over: `vaadin.sessions.created` appears in Prometheus as `vaadin_sessions_total`, and `vaadin.ui.created` as `vaadin_ui_total`, because `_created` is a reserved suffix in the OpenMetrics format and is stripped from the name.
>
> Timers export count, sum, and max only by default. The histogram buckets that percentile queries need are opt-in — see [Percentiles and Histogram Buckets](https://vaadin.com/docs/next/tools/observability/integrations.md#percentiles). With tracing on, each observed timer also publishes a parallel long-task timer — an `_active_seconds` family in Prometheus — that tracks operations still in flight.
## Metrics
A meter is a measurement recorded at runtime. Observability Kit records the meter types Micrometer provides:
- Counter
A value that only increases, such as the number of sessions created.
- Gauge
A value sampled at a point in time, such as the number of active sessions.
- Timer
Records both a count of events and the distribution of their durations.
- Distribution summary
Records both a count of events and the distribution of a non-time measurement, such as the number of rows read from a query.
### Session Metrics
Controlled by `vaadin.observability.sessions`.
| Meter | Type | Description |
| -------------------------- | ------- | -------------------------------------------------------------------- |
| `vaadin.sessions.active` | Gauge | Currently active sessions. |
| `vaadin.sessions.created` | Counter | Sessions created since startup. |
| `vaadin.sessions.duration` | Timer | Session lifetime, recorded when a session ends. |
| `vaadin.session.lock.wait` | Timer | Time spent waiting to acquire the session lock. Tagged by `context`. |
| `vaadin.session.lock.hold` | Timer | Time the session lock is held. Tagged by `context`. |
The `context` tag is `request` when the lock is taken during request handling, or `access` when it’s taken through `UI.access()`.
### UI Metrics
Controlled by `vaadin.observability.uis`.
| Meter | Type | Description |
| ------------------- | ------- | -------------------------- |
| `vaadin.ui.active` | Gauge | Currently active UIs. |
| `vaadin.ui.created` | Counter | UIs created since startup. |
### UI State Metrics
Controlled by `vaadin.observability.ui-state`, which is off by default. Session and UI counts tell you how many users are connected; these gauges tell you what each of them costs. See [UI State Size](#ui-state-size) for how the measurement is scheduled and how to read it.
| Meter | Type | Description |
| -------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vaadin.ui.state.nodes` | Gauge | State-tree nodes retained across all tracked UIs — how much UI state the server currently holds for live users. |
| `vaadin.ui.state.nodes.max` | Gauge | State-tree nodes held by the largest single UI. |
| `vaadin.ui.state.components` | Gauge | Server-side component instances retained across all UIs. |
| `vaadin.ui.state.views` | Gauge | Route-target and router-layout instances retained across all UIs. One navigation into a nested layout legitimately retains one per level, so this is a capacity figure rather than a leak signal. |
| `vaadin.ui.state.views.stale` | Gauge | Retained views that are no longer part of their UI’s active navigation — views that outlived it. Normally zero. |
| `vaadin.ui.state.size` | Gauge | Retained UI state in bytes, projected from the node count. Registered only when `vaadin.observability.ui-state-bytes-per-node` is set. |
| `vaadin.ui.state.sample.age.max` | Gauge | Age in seconds of the stalest per-UI measurement in the aggregate. |
| `vaadin.session.state.nodes.max` | Gauge | State-tree nodes held by the largest single session. |
| `vaadin.session.uis.max` | Gauge | Most UIs (browser tabs) held open by one session. |
These gauges are aggregates only — totals and maxima, never one series per session or per UI, which would grow unbounded with traffic. They carry no tags.
### Navigation Metrics
Controlled by `vaadin.observability.navigation`.
| Meter | Type | Description |
| ------------------- | ----- | -------------------------------------------------------------------------------------------------------- |
| `vaadin.navigation` | Timer | Navigation duration, from `beforeEnter` to `afterNavigation`. Tagged by `route`, `outcome`, and `error`. |
Every navigation that **starts** is recorded, including the ones that never complete — which would otherwise leave a span dangling. The `outcome` tag says how it ended:
| `outcome` | Recorded for |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success` | The navigation reached `afterNavigation`. |
| `rerouted` | A listener called `rerouteTo()`, so this navigation was replaced by another. This is a routing decision — an access guard sending the user elsewhere — not a failure. |
| `forwarded` | A listener called `forwardTo()` or `forwardToUrl()`, or handed off to a client-side route. |
| `error` | The navigation failed: `rerouteToError()`, or an exception while the view was being built. |
| `unknown` | The navigation was neither completed nor redirected. A re-entrant `UI.navigate()` from a view’s `beforeEnter()` or `onAttach()` superseded it, or its UI was detached while it was still open. |
> **Important: Building an Error Rate on This Timer**
>
> Two consequences follow from timing the router’s own chain — an error view is a navigation in its own right, and it’s one that succeeds:
>
> - An unknown URL never reaches a `beforeEnter()` that could fail, so it’s recorded as the error view rendering successfully: `route=RouteNotFoundError, outcome=success`. Alert on that route rather than on `outcome`.
>
> - A view that throws while being built produces **two** samples: the failed navigation to the view (`outcome=error`), and the navigation to the error view that replaces it (`route=InternalServerError, outcome=success`).
### Request Metrics
Controlled by `vaadin.observability.requests`.
| Meter | Type | Description |
| ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vaadin.request.duration` | Timer | Server-side request handling time. Tagged by `vaadin.request.type`, `vaadin.interaction`, `http.method`, `outcome`, and `error`. See [Request Types](#request-types) for what the type tag classifies. |
| `vaadin.rpc.duration` | Timer | Server-side RPC invocation time. Tagged by `type`, `outcome`, and `error`. |
> **Note: The Tags Are the Same With Tracing On or Off**
>
> With tracing on — the default — `vaadin.request.duration` is produced from the request observation, so it carries that span’s low-cardinality attributes as tags, plus the `error` tag Micrometer’s `DefaultMeterObservationHandler` adds. With tracing off, the binder records the timer directly and tags it with exactly the same keys. This is deliberate: Prometheus rejects same-named meters whose tag-key sets differ, so the two recording paths must never publish `vaadin.request.duration` under differing keys. The same holds for `vaadin.rpc.duration` and `vaadin.navigation`.
>
> The span’s `ui.id` and `vaadin.client.location` attributes are unbounded and are deliberately kept off the timer on both paths.
### Request Types
Every request Vaadin handles is classified before it’s timed, and the class becomes the `vaadin.request.type` tag on `vaadin.request.duration` — and, with tracing on, the `vaadin.request.` span name. The types differ so much in what they do that a single average across all of them means nothing.
| `vaadin.request.type` | What It Covers |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uidl` | A UI interaction: the request the client sends for a click, a poll, or a navigation. The one type broken down further, by the `vaadin.interaction` tag. |
| `bootstrap` | A page load: the HTML document request, and the `init` request the client engine follows it with to have the UI created. The server’s side of `vaadin.client.bootstrap.duration`. |
| `stream` | A download or an upload, served by Flow’s stream request handler. A transfer is expected to be long-running, which is why it’s kept out of the other buckets: averaged in with page loads, it both hides its own outliers and inflates theirs. |
| `push` | A push channel request, on any transport. |
| `heartbeat` | The keep-alive the browser sends for an open UI. |
| `static` | A static resource: `/VAADIN/`, `/static/`, `/themes/`, or `/sw.js`. |
| `other` | Everything left, an application’s own endpoints under the Vaadin servlet among them. |
A page load is recognized from the browser’s `Sec-Fetch-Dest` header, falling back to an `Accept` header that asks for `text/html` first for browsers old enough not to send it. A `fetch()` to an application endpoint that happens to sit under the Vaadin servlet is therefore not counted as one. The classification is deliberately conservative in that direction: a page load that can’t be told apart from application traffic stays `other` rather than diluting `bootstrap`.
An embedded route counts as a page load too. A request whose destination is an `iframe`, `frame`, `embed`, or `object` is served the same `index.html` and builds a UI of its own, and `vaadin.client.bootstrap.duration` records it from the browser’s end as well. A view that embeds another of its own routes therefore reports a second `bootstrap`, which is the second UI it really does build.
### Resync Metrics
Controlled by `vaadin.observability.resync`. These track UIDL message-recovery events, which indicate a flaky client-server connection.
| Meter | Type | Description |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vaadin.resync` | Counter | Client-server message-recovery events. Tagged by `type`: `resend` when the client re-sends a request it never got a response for (the server replays its cached response), or `resync` when the client gives up on a missing server message and asks for a full UI-state rebuild. |
### Error Metrics
Controlled by `vaadin.observability.errors`.
| Meter | Type | Description |
| --------------- | ------- | -------------------------------------------------------------------------------------------- |
| `vaadin.errors` | Counter | Every server-side failure the kit observes. Tagged by `exception`, `route`, and `component`. |
The counter covers both kinds of server-side failure:
- Exceptions that escape request handling
For example one thrown by a custom `RequestHandler`. These reach a `VaadinRequestInterceptor`.
- Failures Flow routes to the session’s error handler
For example a click or value-change listener that throws, a `UI.access()` body, or a detach listener. Flow catches these and hands them to `VaadinSession.getErrorHandler()` rather than letting them escape, so they never reach a request interceptor. The kit therefore decorates that handler, which is also what lets it attribute a failure to a component.
A failure during navigation — a `beforeEnter()` callback or a view constructor that throws — is neither kind. The router catches it and renders an error view in its place, so it never reaches the error handler and isn’t counted here. It shows up on the navigation timer instead, as described in [Navigation Metrics](#navigation-metrics).
All three tags derive from application classes and multiply with each other, so all three are capped at `vaadin.observability.route-cardinality-limit`. Values beyond the limit collapse to `_other`, and a `route` or `component` that can’t be resolved is `_unknown`.
> **Important: How the Error Handler Is Decorated**
>
> The decoration always delegates, so an application’s own error handler keeps receiving every error it received before. It’s applied at session init and re-applied at UI init and at the start of every RPC invocation, so installing your own handler after session init doesn’t switch error metrics off.
>
> One consequence: a handler read back from `VaadinSession.getErrorHandler()` is the kit’s wrapper rather than the instance you set. Delegating to it works as expected, and the failure is still counted exactly once. An `instanceof` check or a cast to your own type does not. Set `vaadin.observability.errors=false` to opt out of the decoration entirely.
### Client Metrics
Controlled by `vaadin.observability.client`. These are observed in the browser and reported back to the server, subject to a rate limit of `vaadin.observability.client-rate-per-session` samples per UI in each ten-second window.
| Meter | Type | Description |
| ----------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vaadin.client.bootstrap.duration` | Timer | Browser application bootstrap time. |
| `vaadin.client.navigation.duration` | Timer | Browser-observed navigation time. |
| `vaadin.client.request.duration` | Timer | One UIDL request as the browser saw it, from the moment the request was queued to the last byte of the response. The browser’s side of `vaadin.request.duration`; see [Interaction Timing From the Browser](#client-interaction-timing). |
| `vaadin.client.render.duration` | Timer | How long Flow’s client spent applying one UIDL response to the page. Recorded only when Flow’s `requestTiming` deployment setting is on, which is the default outside production mode. |
| `vaadin.client.web_vitals.lcp` | Timer | Largest Contentful Paint. |
| `vaadin.client.web_vitals.fcp` | Timer | First Contentful Paint. |
| `vaadin.client.errors` | Counter | Errors reported by the browser. Tagged by `kind`. What identifies one — the message, the script it came from, and the first stack frame — is kept as an insight rather than as tags; see [Interaction Insights](https://vaadin.com/docs/next/tools/observability/insights.md). |
| `vaadin.client.connection` | Counter | Transitions of the browser’s connection state, tagged by `state` with the state entered. The `loading` state Flow toggles around every request isn’t reported, so this counts real connection events rather than one per interaction. |
| `vaadin.client.connection.downtime` | Timer | How long the browser stayed unable to reach the server, recorded once per unreachable state it passed through and tagged by `state`. Time under `reconnecting` is a connection that hiccuped; time under `connection-lost` is a server the browser had given up on. The report can only be sent once the connection is back, so a browser that never reconnects contributes nothing — the timer under-reports total downtime by construction. |
| `vaadin.client.throttled` | Counter | Client samples rejected by the per-UI rate limit. Untagged. |
| `vaadin.client.dropped` | Counter | Client samples that reached ingest but never made it into a meter: one the registry refused, and one whose reported duration isn’t a measurement at all — negative, not finite, or over an hour. A timer’s sum only ever grows, so one saturating value would skew its average for the life of the process. Untagged. |
The client timers — except `vaadin.client.connection.downtime`, which carries `state` instead — are tagged by `route`, resolved from the browser location to a route template on the server and capped by the same cardinality limit as the server-side meters. `vaadin.client.navigation.duration` additionally carries `trigger`.
The browser buffers samples and flushes them every five seconds, and when the page is hidden. Only the meters in the table above are accepted; a sample under any other name is discarded at ingest without being recorded or counted, which caps the cardinality a buggy or malicious client can create.
### Interaction Timing From the Browser
When a user says a click took a second and `vaadin.request.duration` says the server took forty milliseconds, the other nine hundred and sixty are somewhere the server can’t see: on the wire, in the browser’s request queue, or in the browser applying the response. Two of the client meters make that remainder readable, with no configuration beyond `vaadin.observability.client`.
`vaadin.client.request.duration` is the same round trip as `vaadin.request.duration`, measured at the browser’s end. It’s read off the Resource Timing entry every UIDL `POST` leaves behind, so it needs nothing from Flow and works in production. Subtract the server’s figure for the same route, and what’s left is the network:
```text
rate(vaadin_client_request_duration_seconds_sum[5m])
/ rate(vaadin_client_request_duration_seconds_count[5m])
-
rate(vaadin_request_duration_seconds_sum{vaadin_request_type="uidl"}[5m])
/ rate(vaadin_request_duration_seconds_count{vaadin_request_type="uidl"}[5m])
```
`vaadin.client.render.duration` is the third segment, after the network and the server: how long Flow’s client spent applying the response to the page. A response that arrives in fifty milliseconds and takes four hundred to render is a browser problem — typically a heavy component tree or an expensive renderer — and neither of the other two timers can show it. The figure is Flow’s own, published through `getProfilingData()` on each client only when Flow’s `requestTiming` deployment setting is on. That’s the default outside production mode; in production, set `vaadin.requestTiming=true` to record this meter. Without it the meter is absent rather than zero.
Four things are worth knowing about both:
- Only UIDL requests are timed
Heartbeats, push, and static resources aren’t interactions and are left out. The collector’s own request that carries the samples to the server is left out too, so the kit doesn’t report itself.
- The request meter needs the default transport
It’s read from Resource Timing, which sees HTTP requests. With `@Push(transport = WEBSOCKET)` the UIDL rides the websocket and leaves no entry, so only the render meter is recorded.
- Bootstrap isn’t an interaction
The first UIDL response, which builds the page, is covered by `vaadin.client.bootstrap.duration` and excluded here.
- The route is the browser’s
Both meters carry the route the browser was on when the response arrived, which for a navigation request is the view navigated to, as on the server’s request span.
### Data Provider Metrics
Controlled by `vaadin.observability.data`. These measure the queries that lazy-loading components — `Grid`, `ComboBox`, `VirtualList`, and others — issue to their data providers. Where the database metrics below measure the persistence layer, these measure what the component asked for, so they apply whatever the data provider is backed by.
| Meter | Type | Description |
| ----------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vaadin.data.count.duration` | Timer | Duration of a count query — how many items a level holds. Tagged by `outcome` and `filtered`. A hierarchical component issues one count per expanded parent, so many counts within few requests is the signature of an expensive hierarchy. |
| `vaadin.data.fetch.duration` | Timer | Duration of a fetch query — loading one page of items. Tagged by `outcome` and `filtered`. Measured around consumption of the items, so it covers the backend round-trip of a lazily evaluated stream. |
| `vaadin.data.fetch.requested` | Distribution summary | Items a fetch query asked for. Tagged by `route`. |
| `vaadin.data.fetch.rows` | Distribution summary | Items a fetch query actually returned. Tagged by `route`. |
Compare `vaadin.data.fetch.rows` against `vaadin.data.fetch.requested` to spot a component asking for far more than it renders, or a data provider returning short pages. The two duration timers carry no `route` tag; use the `vaadin.data.component` span attribute or the [interaction insights](https://vaadin.com/docs/next/tools/observability/insights.md) to attribute a slow query to a view.
When tracing is enabled, each query also opens a span — see [Data Provider Spans](#data-spans).
### Database Metrics
Controlled by `vaadin.observability.database` (off by default, Spring Boot starter only). When enabled, every `DataSource` bean is wrapped so that JDBC access — Spring Data, `JdbcTemplate`, or raw JDBC — is measured, attributed to the Vaadin `route` that triggered it. See [Database Monitoring](#database-monitoring) for how this works and when to use it.
| Meter | Type | Description |
| ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vaadin.db.fetch.rows` | Distribution summary | Rows read from a JDBC result set. Tagged by `route`. Publishes p95 and p99 percentiles out of the box, so the alerting described in [Database Monitoring](#database-monitoring) needs no extra configuration. |
| `vaadin.db.query` | Timer | JDBC query duration. Tagged by `route`. Produced alongside the `vaadin.db.query` span when both database monitoring and tracing are enabled. |
### Common Tag Values
| Tag | Values |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcome` | `success` or `error`. On `vaadin.navigation`, also `rerouted`, `forwarded`, and `unknown` — see [Navigation Metrics](#navigation-metrics). |
| `error` | The simple class name of the exception that ended the operation, or `none` when it raised none. Distinct from `exception`, which tags the `vaadin.errors` counter. |
| `route` | The target route template. Distinct values are capped by `vaadin.observability.route-cardinality-limit`; beyond the limit they collapse to `_other`, and an unresolvable route is `_unknown`. |
| `component` | On `vaadin.errors`, the simple class name of the component the failure was thrown for. Capped by the same cardinality limit as `route`: `_unknown` when it can’t be resolved, `_other` beyond the limit. |
| `context` | `request` or `access`. |
| `type` | On RPC meters and spans, the RPC invocation type as reported by Flow — `event` for a DOM event, `mSync` for a property sync, `publishedEventHandler` for an `@ClientCallable` method, `channel` for a return channel, and `navigation`. On `vaadin.resync`, the recovery kind: `resend` or `resync`. |
| `exception` | The simple class name of the counted exception, capped by the same cardinality limit as `route`. Types beyond the limit are bucketed as `_other`. |
| `filtered` | On the data provider meters, whether the query carried a filter: `true` or `false`. This separates a combo box loading matches for typed text from one loading the whole data set. |
| `trigger` | On `vaadin.client.navigation.duration`, what moved the browser: `back` for history navigation, or `programmatic` for a `pushState`/`replaceState` call, with `_unknown` for a report that is neither. |
| `kind` | On `vaadin.client.errors`, the source of the browser error: `uncaught` or `promise`, with `_unknown` for a report that is neither. |
| `state` | On `vaadin.client.connection`, the state entered: `connected`, `reconnecting` (the first request failed, the client is retrying), or `connection-lost` (the client exhausted its retries). On `vaadin.client.connection.downtime`, only the two unreachable states appear — a browser only spends downtime being unreachable, so `connected` would be a contradiction there. Either meter buckets a value outside its set as `_unknown`. |
> **Note: JVM, Process, and Connection-Pool Metrics**
>
> Observability Kit doesn’t record JVM, process, or database connection-pool metrics itself. Those come from Micrometer’s standard binders — Spring Boot Actuator registers them out of the box, and you can add others as needed. The kit’s own database metrics above measure query behavior per route, not the connection pool.
## Tracing
When tracing is enabled (`vaadin.observability.traces`, the default) and an `ObservationRegistry` is available, the kit drives the core request lifecycle through the Observation API. Each observation produces a tracing span and, through Micrometer’s `DefaultMeterObservationHandler`, the matching timer above — one measurement, recorded two ways.
To export spans, add a Micrometer tracing bridge (for example OpenTelemetry or Zipkin); see the [Integrations](https://vaadin.com/docs/next/tools/observability/integrations.md) page.
The kit produces the following spans:
| Span | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vaadin.request.` | The root span for each Vaadin request. A UIDL request is named by its interaction — `vaadin.request.rpc`, `vaadin.request.poll`, or `vaadin.request.navigation` — and other requests by their type: `vaadin.request.bootstrap`, `vaadin.request.stream`, `vaadin.request.heartbeat`, `vaadin.request.push`, `vaadin.request.static`, or `vaadin.request.other`. See [Request Types](#request-types). Carries the request-level attributes below. |
| `vaadin.navigation ` | A navigation, nested under the request that triggered it. |
| `vaadin.rpc.` | A server-side RPC invocation (DOM event, `@ClientCallable`, property sync, or return channel), nested under the request. |
| `vaadin.executor.task` | One task run on the Vaadin service executor, nested under whatever trace was active when the task was submitted. See [Background Work](#background-work). |
| `vaadin.data.count` | A data provider count query, nested under the request or RPC span that triggered the load. Controlled by `vaadin.observability.data`. |
| `vaadin.data.fetch` | A data provider fetch query, nested under the request or RPC span that triggered the load. Controlled by `vaadin.observability.data`. |
| `vaadin.db.query` | A single JDBC query, nested under the request or RPC span that ran it. Emitted only when database monitoring is enabled (see [Database Monitoring](#database-monitoring)). |
With both data provider and database monitoring on, a slow interaction opens up in full: the `vaadin.rpc.` span that the user triggered, the `vaadin.data.fetch` span for the page the component asked for, and the individual `vaadin.db.query` spans that fetch ran.
### Background Work
With tracing enabled, the kit wraps the Vaadin service `Executor` so that the trace context active when a task is **submitted** is restored when the task **runs**. A background task started from a request thread therefore stays in the same trace across the thread hop, under its own `vaadin.executor.task` span, instead of appearing as an unrelated root span.
This covers the tasks submitted to that executor: the signal effects Vaadin re-evaluates on it, the signal result notifications it dispatches through it, and the background work applications are expected to hand to it — typically a task that ends by pushing its result through `UI.access()`. It isn’t every `UI.access()` call: a plain call from a background thread queues a command that whichever thread unlocks the session drains, so it never passes through the executor and gets no span of its own. A notification task is itself a `UI.access()` call, so its span always covers the dispatch, but covers the notification body only when the session lock happens to be free. Otherwise the task returns as soon as the command is enqueued, and the body runs later on the unlocking thread, outside the span.
Work you hand to an executor of your own isn’t wrapped. To keep such work in the trace, submit it through the Vaadin service executor, or propagate the context yourself with Micrometer’s `ContextSnapshot`.
### Span Attributes
The root `vaadin.request` span carries these attributes:
| Attribute | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vaadin.request.type` | The request type: `uidl`, `bootstrap`, `stream`, `push`, `heartbeat`, `static`, or `other`. See [Request Types](#request-types). |
| `vaadin.interaction` | What the request actually did: `poll`, `navigation`, or `rpc`, and `none` for requests where no interaction applies, such as heartbeats and static resources. |
| `http.method` | The HTTP method of the request. |
| `outcome` | `success` or `error`. |
| `ui.id` | The ID of the UI associated with the request, or `_unknown`. Span-only, since UI IDs are unbounded. |
| `vaadin.client.location` | The browser location the request was sent from, or `_unknown`. Span-only: it’s the literal path, not a route template. For templated, cardinality-capped view attribution, use the `route` tag on the navigation meters. |
The nested spans carry the tags of their corresponding meters: `vaadin.navigation ` carries `route` and `outcome`; `vaadin.rpc.` carries `type`.
The RPC span additionally carries two span-only, high-cardinality attributes when they can be resolved: `vaadin.rpc.event` (the invocation name, such as a DOM event name, invoked method name, or navigation location) and `vaadin.rpc.component` (the class name of the targeted `Component`). These are attached to the span only, never as timer tags, because of their cardinality. Together they let you trace a failure back to the interaction that caused it — which component, and which event.
Flow doesn’t report an invocation name for property syncs, which is how a field’s value change arrives at the server. Those spans carry `type` and `vaadin.rpc.component`, but no `vaadin.rpc.event`.
The `vaadin.db.query` span carries `route`, a `db.rows` attribute with the number of rows read, and — when `vaadin.observability.database-statement` is enabled — the parameterized SQL as `db.statement`.
The `vaadin.executor.task` span carries no attributes of its own. Its value is structural: it shows where a submitted task ran, under the trace it was submitted from.
### Data Provider Spans
The `vaadin.data.count` and `vaadin.data.fetch` spans carry `filtered` and `outcome` as low-cardinality attributes, alongside these span-only ones:
| Attribute | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vaadin.data.component` | The class name of the component whose data is being loaded. Span-only, because of its cardinality — this is what attributes a slow query to a view, since the duration timers carry no `route` tag. |
| `vaadin.data.offset` | Index of the first item a fetch query asked for. Fetch spans only. |
| `vaadin.data.limit` | Number of items a fetch query asked for. Fetch spans only. |
| `vaadin.data.rows` | Number of items a fetch query returned. Fetch spans only, and only when the query succeeded. |
### Errors
When a request or a nested operation fails, its observation is marked as error, so the span records the exception and the `outcome` tag becomes `error`.
For an exception thrown inside a component listener, this happens on the `vaadin.rpc.` span — the one that also carries the component and event. The enclosing `vaadin.request` span is marked `outcome=error` as well: Flow hands such an exception to the session’s `ErrorHandler` rather than letting it escape request handling, and the kit relays that back to the request observation, so the request doesn’t claim success for an interaction that failed. On Spring, the error is also propagated to the enclosing Spring HTTP observation, so the surrounding HTTP server span reports it too. The failure also increments the `vaadin.errors` counter; see [Error Metrics](#error-metrics).
The same failure is also retained as an interaction insight, which reports it without a tracing backend and points at the application stack frame behind it. See the [Interaction Insights](https://vaadin.com/docs/next/tools/observability/insights.md) page.
## UI State Size
Session and UI counts tell you how many users are connected; they say nothing about what each of them costs. Because Flow keeps every open tab’s component tree in server memory, **size** is the signal that predicts when a server-driven application has to scale: a hundred users on a dashboard with three grids cost nothing like a hundred users on a login form.
Turn the measurement on with:
`application.properties`
```properties
vaadin.observability.ui-state=true
```
Each UI then reports its own state-tree size, and the kit publishes the aggregates listed in [UI State Metrics](#ui-state-metrics). Charted next to `vaadin.sessions.active`, they answer a question the counts can’t: state climbing while the session count is flat means capacity is going into what users have open, not into how many of them there are.
Watch the maxima as much as the totals. `vaadin.ui.state.nodes.max` and `vaadin.session.state.nodes.max` describe the worst-case tab and the worst-case user, and it’s the tail that exhausts a heap, not the mean. `vaadin.ui.state.views.stale` is the one leak signal in the set: anything above zero means views are outliving their navigation. A plain view count can’t tell you that, because one navigation into a nested layout legitimately retains a view per level.
### How Measurement Is Scheduled
A component tree may only be read under its own session lock, so no UI is ever measured by another user’s request thread. Every UI measures itself: at UI init, after each navigation, and when an RPC invocation ends — the last of these throttled to one tree walk per UI per `vaadin.observability.ui-state-sample-interval` milliseconds.
This is why the feature is off by default: it costs a tree walk that ordinary request handling doesn’t. It’s also why an idle user contributes their state as of their last interaction, and why `vaadin.ui.state.sample.age.max` exists — it publishes how stale the oldest measurement in the aggregate is, so a reading can be judged rather than assumed current.
The cost of one walk is proportional to the size of the tree it measures, and it’s paid on the request thread while the session lock is held. The interval is therefore what bounds the overhead: tree size times interaction rate, capped at one walk per UI per interval. The default of ten seconds keeps a capacity trend legible on a grid-heavy application with many concurrent users. Lower it for a sharper signal, and raise it if the measurement becomes visible in `vaadin.session.lock.hold`.
### Nodes, Not Bytes
A node count is a proxy for retained heap, not a measurement of it: one `Grid` node backed by 100,000 rows counts as a single node. The kit therefore publishes no byte figure by default, because a guessed per-user cost is worse than a missing one.
If you measure the cost for your own application — settle the heap, build a number of copies of a representative view, keep them reachable, and read the difference from `MemoryMXBean` — set the result and the projection becomes available as `vaadin.ui.state.size`:
`application.properties`
```properties
vaadin.observability.ui-state-bytes-per-node=96
```
Divided into the heap headroom, that’s an estimate of how many more tabs the instance can hold.
## Database Monitoring
With the Spring Boot starter, the kit can watch how many rows your queries return and how long they take, without touching application code. Enable it with:
`application.properties`
```properties
vaadin.observability.database=true
```
Every `DataSource` bean is then wrapped so that each JDBC `ResultSet` reports its row count into the `vaadin.db.fetch.rows` distribution summary, **tagged by the Vaadin `route`** that triggered the fetch. This lets you see which view issues the large reads. Watch the p95/p99 of that summary and alert on it in your backend — for example a Prometheus rule on `vaadin_db_fetch_rows` — to catch runaway result sets in production.
This is off by default: it reaches outside the Vaadin runtime into the persistence layer and adds a small per-row cost. It covers all JDBC access — Spring Data, `JdbcTemplate`, and raw JDBC — that flows through a managed `DataSource`. Row counting is best-effort and attributes to `_unknown` when no view is active, such as for background tasks.
### Locating Slow or Large Queries in a Trace
When tracing is also enabled (`vaadin.observability.traces=true`, the default), each query additionally opens a `vaadin.db.query` span. Because it starts on the request-handling thread inside the Vaadin request span, it nests under that request or RPC span automatically. In Jaeger — or any backend fed by your Micrometer tracing bridge — you can open a slow interaction and see the individual queries it ran, each carrying the `route` and a `db.rows` attribute. The same observation also yields a `vaadin.db.query` duration timer: database time per view.
The span doesn’t include the SQL text by default. Set `vaadin.observability.database-statement=true` to attach the parameterized statement as `db.statement`. This is useful for pinpointing the offending query, but it’s opt-in because SQL is higher cardinality and can be sensitive.
## Extending Built-In Instrumentation
To record your own metrics and spans alongside these, see the [Custom Instrumentation](https://vaadin.com/docs/next/tools/observability/customization.md) page. Custom meters and spans share the same registry and backend, so keep your names and tag cardinality consistent with the conventions above.
`4E9CED65-0EA1-4590-956A-6198F0F90482`