Docs

Docs

Observability Kit Reference

The metrics and tracing spans Observability Kit records, with their types, tags, and attributes.

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

Each group of meters and spans is controlled by a feature toggle (for example vaadin.observability.sessions). See the Configuration 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 that its conventions — Prometheus, for instance, renders vaadin.request.duration as vaadin_request_duration_seconds with a _count, _sum, and bucket suffixes.

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.

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.

Controlled by vaadin.observability.navigation.

Meter Type Description

vaadin.navigation

Timer

Navigation duration, from beforeEnter to afterNavigation. Tagged by route and outcome.

Request Metrics

Controlled by vaadin.observability.requests.

Meter Type Description

vaadin.request.duration

Timer

Server-side request handling time. Tagged by outcome.

vaadin.rpc.duration

Timer

Server-side RPC invocation time. Tagged by type and outcome.

Error Metrics

Controlled by vaadin.observability.errors.

Meter Type Description

vaadin.errors

Counter

Server-side errors handled during a request. Tagged by exception (the exception’s simple class name).

Client Metrics

Controlled by vaadin.observability.client. These are observed in the browser and reported back to the server, subject to the per-session rate limit (see vaadin.observability.client-rate-per-session).

Meter Type Description

vaadin.client.bootstrap.duration

Timer

Browser application bootstrap time.

vaadin.client.navigation.duration

Timer

Browser-observed navigation time.

vaadin.client.rpc.duration

Timer

Browser-observed server round trip.

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.

vaadin.client.dropped

Counter

Client samples dropped before recording.

vaadin.client.throttled

Counter

Client samples rejected by the per-session rate limit.

Common Tag Values

Tag Values

outcome

success or error.

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.

context

request or access.

type

The RPC invocation type, as reported by Flow.

exception

The simple class name of the handled exception.
Note
JVM, Process, and Database Metrics
Observability Kit no longer records 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.

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

The kit produces the following spans:

Span Description

vaadin.request

The root span for each Vaadin request. Carries the request-level attributes below.

vaadin.navigation <route>

A navigation, nested under the request that triggered it.

vaadin.rpc.<type>

A server-side RPC invocation (DOM event, @ClientCallable, property sync, or return channel), nested under the request.

vaadin.ui.access

Work executed through UI.access().

Span Attributes

The root vaadin.request span carries these attributes:

Attribute Description

vaadin.request.type

The protocol-level request type: uidl, heartbeat, push, static, or other.

vaadin.interaction

What the request actually did, when it can be determined: poll, navigation, or rpc.

http.method

The HTTP method of the request.

ui.id

The ID of the UI associated with the request, or _unknown.

vaadin.client.location

The browser location associated with the request, or _unknown.

outcome

success or error.

vaadin.session.id

The Vaadin session ID. Added only when vaadin.observability.traces-session-id is enabled.

The nested spans carry the tags of their corresponding meters: vaadin.navigation <route> carries route and outcome; vaadin.rpc.<type> carries type.

Errors

When a request or a nested operation handles an exception, the observation is marked as error, so the span records the error and the outcome tag becomes error. A server-side error also increments the vaadin.errors counter, tagged by exception type.

Extending Built-In Instrumentation

To record your own metrics and spans alongside these, see the Custom Instrumentation 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

Updated –