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.

The three retained gauges are registered only when vaadin.observability.ui-state-growth-samples is above zero, which it is by default.

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.

The http.method tag accepts only the standard HTTP methods; any other method a client sends is recorded as _other, so a request can’t create a new series by inventing one.

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.<type> span name. The types differ so much in what they do that a single average across all of them means nothing.

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.

Controlled by vaadin.observability.resync. These track client message-recovery events, over both HTTP and push.

The type tag says what happened:

resend and resync mean the client lost a server message, which points at a flaky connection. out_of_sync usually means the UI continued on a server that held an older state of it. All three types are registered at startup, so each reports zero before its first event.

The counter is driven by events Flow fires, so it needs no servlet filter and works the same in every setup.

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 session in each ten-second window. All tabs of a session share that budget.

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.

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:

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:

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.

In Spring deployments the kit also enriches Spring’s own HTTP server observation. Each Vaadin request gets its type lifted into the HTTP span, and a UIDL request additionally gets the active view’s route template set as the path pattern. The uri tag on http.server.requests and the HTTP span name then read /orders/:id, instead of bucketing all UI traffic into a single /vaadin/uidl entry, so per-view HTTP latency stays answerable from the standard Spring metrics. A UIDL request whose view’s route template can’t be resolved stays under /vaadin/uidl; the kit never falls back to the view’s class name or to the literal browser path there.

Every other request type keeps the type itself as its path pattern — /vaadin/bootstrap, /vaadin/stream, and so on. This also keeps the per-transfer URLs of downloads and uploads, each carrying a UI ID and a one-time security key, out of the uri tag.

The templates pass the same vaadin.observability.route-cardinality-limit cap as the kit’s own route tags, and at most 50 distinct view templates ever reach the uri tag, regardless of configuration. The rest collapse into /_other. The fixed budget is half of the default of Spring Boot’s management.metrics.web.server.max-uri-tags (100). Once that cap is crossed, Spring Boot denies new http.server.requests series outright, first come first served across every endpoint of the application, so the kit stays well clear of it. Raise max-uri-tags when Actuator endpoints and REST controllers need more room, not to get more view templates through.

The enrichment is independent of the traces setting: it also applies when only metrics are collected.

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.

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. A request, RPC, or data fetch span under which more queries ran than vaadin.observability.database-span-limit allows carries vaadin.db.queries.unspanned, the number of queries that got no span of their own; see N+1 Loads and the Span Limit.

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.

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.

The tree gauges can’t see what a view keeps in its own fields. A view that appends each refresh to a List — to show what changed since the last one, say — grows on the heap every time, while its component tree, and every gauge above, stays flat. Only the heap shows it, and the heap can’t say which view is to blame.

So with ui-state on, each measurement also reads the collections that views hold: the instance fields of every route target and router layout in the tree, and of their superclasses up to the first Flow class, whose declared type is a Collection, a Map, or an array. A field’s size includes the collections nested directly inside it, so a List<List<T>> that gains a whole result set per refresh grows by that result set. The kit publishes the totals as vaadin.ui.state.retained.elements and vaadin.ui.state.retained.elements.max.

It then follows each field of each view instance from one measurement of its UI to the next. A field that has grown at vaadin.observability.ui-state-growth-samples measurements (5 by default) without shrinking in between is counted in vaadin.ui.state.retained.growing. A measurement that finds the size unchanged neither counts nor breaks the run, because measurements follow interactions, not the code that adds to the field. The gauge is normally zero, so it can be alerted on directly:

Which view and field is growing isn’t a tag, since that would add a series per view class. The insights endpoint reports it instead, as a growing-view-state insight: one per field, naming the class and the field, how large it is in the worst UI, what it started from, and how many open UIs show the same growth.

What’s deliberately not read: only java.util implementations are asked for their size, because another collection may do work to answer — a lazy JPA association loads itself on size() — and nothing reachable from an element is followed. These figures count what a field holds, not how many bytes that is.

Some collections legitimately grow for a while, like a chat log or rows a user keeps adding. Raise ui-state-growth-samples if they’re reported too early, or set it to 0 to turn the collection reading off.

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.

An N+1 load — one query for a list, then one more per row, typically an eagerly or lazily loaded JPA relation — can issue tens of thousands of queries for a single click. A span for each would overflow the tracing exporter’s queue (OpenTelemetry’s BatchSpanProcessor holds 2048 by default), and the exporter then drops spans from every request, not only the one at fault.

At most vaadin.observability.database-span-limit (100 by default) query spans are therefore started under any one parent span — a Vaadin request, an RPC, or a data provider fetch. Past that, a query:

In a trace, an N+1 load therefore looks like a request or fetch span with vaadin.db.queries.unspanned set, the first 100 query spans under it — most with db.rows=1 — and one query with a large db.rows near their start. A query with no enclosing span, such as one on an application thread with no observation, has nothing to count against and isn’t limited.

The handler is registered only when Micrometer Tracing is on the classpath, which is the case whenever the application exports spans.