Docs

Docs

Getting Started with Observability Kit

Step-by-step guide on how to use Observability Kit in an application.

Observability is the ability to answer questions about an application and its infrastructure. The Vaadin Observability Kit implements this for Flow-based applications, giving you actionable insight into applications running in production.

Observability Kit is built on Micrometer. It instruments the Vaadin runtime — sessions, UIs, navigation, requests, data provider queries, errors, and real browser-side timing — and records everything into your application’s Micrometer MeterRegistry, so it shows up in whatever backend you already use (Prometheus, OTLP, Graphite, and so on). Tracing spans are emitted through the Micrometer Observation API.

With Spring Boot, the kit is a drop-in: you add one dependency and you’re done. There’s no agent to download, no -javaagent flag, and no separate configuration file.

Note
Migrating From Version 4?
Earlier versions of Observability Kit were a standalone OpenTelemetry Java agent. If you’re upgrading an existing project, see the Migrating to Version 5 page.

Requirements

  • Java 21 or newer.

  • Vaadin 25.3 or newer (Flow 25.3+).

  • A Micrometer MeterRegistry — the Spring Boot starter provides one out of the box.

  • Spring Boot 4, for the observability-kit-starter. Plain-Spring and standalone setups are also supported; see Other Setups.

GraalVM native images are supported out of the box: the kit ships the native-image metadata its resources need.

Add the Dependency

For a Spring Boot application, add the starter to your pom.xml:

Source code
pom.xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>observability-kit-starter</artifactId>
</dependency>

That’s the whole setup. On startup the kit auto-configures a MeterRegistry through Spring Boot’s Micrometer support and wires the Vaadin instrumentation onto it. Sessions, UIs, navigation, request handling, data provider queries, errors, and client-side timing all start recording automatically.

Two features are left off by default because they cost more than ordinary instrumentation: UI state size, which predicts when a server-driven application has to scale, and database monitoring.

Export the Metrics

The kit only records into a registry. To export the metrics to a backend, add Spring Boot Actuator and the registry of your choice. For example, for Prometheus:

Source code
pom.xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Then expose the Prometheus endpoint:

Source code
application.properties
management.endpoints.web.exposure.include=prometheus

The metrics are then available at GET /actuator/prometheus.

For traces, add a Micrometer tracing bridge — for example OpenTelemetry or Zipkin — as you would for any Micrometer-instrumented application. See the Integrations page for vendor-specific setup.

Run & Verify

Start your application and exercise a few views. Then open http://localhost:8080/actuator/prometheus and look for the Vaadin meters — for example vaadin_sessions_active or vaadin_request_duration_seconds_count.

If you don’t have an application yet, you can download one from Vaadin Start, add the dependencies above, and run it.

During development you can also inspect the live meters without a backend. When the application runs in development mode, the kit contributes a metrics panel to Vaadin Copilot that snapshots every vaadin.* meter — counts, means, and current values — straight from the running registry. This panel is development-mode only and has no effect in production.

For the full list of built-in meters, see the Reference page.

See What Users Ran Into

Metrics need a backend and a dashboard before they tell you anything. Interaction insights don’t: the kit retains the user interactions that failed or ran over the UX budget, and serves them grouped — with the route, the component, the event, and the application stack frame behind them — from a single Actuator endpoint.

Expose it alongside whatever else you already expose:

Source code
application.properties
management.endpoints.web.exposure.include=prometheus,vaadin

Then read them at GET /actuator/vaadin/observability. See the Interaction Insights page for the payload and its options.

Other Setups

The starter is the easiest path, but the kit also runs without Spring Boot.

Plain Spring (Without Spring Boot)

Add the Spring module, import the configuration, and provide a MeterRegistry bean:

Source code
pom.xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>observability-kit-spring</artifactId>
</dependency>
Source code
ObservabilityConfig.java
@Configuration
@Import(ObservabilityConfiguration.class)
class ObservabilityConfig {

    @Bean
    MeterRegistry meterRegistry() {
        return new SimpleMeterRegistry();
    }
}

An ObservationRegistry is used for tracing if a bean is present.

Standalone (Without Spring)

Add the core module and install the kit at servlet-context startup — for example from a ServletContextListener — so the registry is in place before VaadinService initializes. For background on when this happens during deployment, see Application Lifecycle.

Source code
pom.xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>observability-kit-micrometer</artifactId>
</dependency>
Source code
ObservabilitySetup.java
@WebListener
public class ObservabilitySetup implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent event) {
        MeterRegistry registry = new SimpleMeterRegistry();
        ObservabilityKit.install(registry,
                ObservabilitySettings.builder().build());
    }
}

As long as tracing is left enabled, this two-argument overload creates an ObservationRegistry for you and wires it to the meter registry, so the observation-backed timers are recorded. It doesn’t register a tracing handler, so no spans leave the application. With traces turned off, it creates no observation registry at all and the binders record their timers directly.

To export spans — or to write your own Observations, which needs a registry you can reach — create the ObservationRegistry yourself and pass it to the three-argument overload:

Source code
Inside contextInitialized()
MeterRegistry registry = new SimpleMeterRegistry();

ObservationRegistry observationRegistry = ObservationRegistry.create();
observationRegistry.observationConfig()
        // Produces the timers from the kit's observations.
        .observationHandler(new DefaultMeterObservationHandler(registry))
        // Exports the spans; tracer comes from your tracing bridge.
        .observationHandler(new DefaultTracingObservationHandler(tracer));

ObservabilityKit.install(registry, observationRegistry,
        ObservabilitySettings.builder().build());

With this overload the kit registers no handlers of its own, so the registry needs at least DefaultMeterObservationHandler for the timers. Keep a reference to both registries — for example in a static holder — if you want to use them for custom instrumentation.

Troubleshooting

No vaadin.* meters appear at all

In development mode the kit validates your commercial license at startup. If validation fails, the application keeps running but the kit registers no instrumentation — it logs a warning rather than failing the build or the deployment. Check the application log; the insights endpoint also reports instrumentation: inactive in this state.

vaadin.errors is missing

The counter is registered lazily, on the first error it counts. An application that hasn’t failed yet publishes no vaadin.errors series — absence means zero, not a broken setup.

The names look different in the backend

Backends render Micrometer’s dotted names in their own conventions, and Prometheus also renames the .created counters to vaadin_sessions_total and vaadin_ui_total. See the naming note on the Reference page.

Percentile queries return no data

Timers publish no histogram buckets by default; a histogram_quantile() query or a p95 panel silently comes up empty until you enable them. See Percentiles and Histogram Buckets.

Next Steps

  • Configuration — turn features on or off and tune the kit.

  • Custom Instrumentation — record your own metrics and traces alongside the built-in ones.

  • Interaction Insights — backtrack a user report to the interaction that caused it.

  • Reference — the full list of meters and spans.

  • Integrations — export to Prometheus, Grafana, Datadog, New Relic, and others.

336FFD66-12AC-466E-AA92-993809F623C6

Updated –