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, 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.2 or newer (Flow 25.2+).

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

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, errors, and client-side timing all start recording automatically.

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.

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

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());
    }
}

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.

  • Reference — the full list of meters and spans.

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

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

Updated –