Observability Kit Reference

Controlled by vaadin.observability.sessions.

The context tag is request when the lock is taken during request handling, or access when it’s taken through UI.access().

Controlled by vaadin.observability.uis.

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 for how the measurement is scheduled and how to read it.

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.

Controlled by vaadin.observability.navigation.

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:

Controlled by vaadin.observability.requests.

Controlled by vaadin.observability.resync. These track UIDL message-recovery events, which indicate a flaky client-server connection.

Controlled by vaadin.observability.errors.

The counter covers both kinds of server-side failure:

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.

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.

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.

Server round-trip timing isn’t collected in the browser. Use the server-side vaadin.request.duration and vaadin.rpc.duration timers for that.

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 dropped at ingest, which caps the cardinality a buggy or malicious client can create.

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.

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 to attribute a slow query to a view.

When tracing is enabled, each query also opens a span — see Data Provider Spans.

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 for how this works and when to use it.

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.ui.access span, instead of appearing as an unrelated root span.

This covers the executor Vaadin dispatches signal effects and result notifications on, and that applications are expected to use for their own background work — typically a task that ends by pushing its result through UI.access(). It isn’t UI.access() itself: a command queued with UI.access() runs on whichever thread unlocks the session, and is recorded there.

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.

The root vaadin.request span carries these attributes:

The nested spans carry the tags of their corresponding meters: vaadin.navigation <route> carries route and outcome; vaadin.rpc.<type> 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.ui.access 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.

The vaadin.data.count and vaadin.data.fetch spans carry filtered and outcome as low-cardinality attributes, alongside these span-only ones:

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

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

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.

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:

Divided into the heap headroom, that’s an estimate of how many more tabs the instance can hold.

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.