> Markdown version of [Getting Started](https://vaadin.com/docs/next/tools/observability/getting-started). Section index: [llms.txt](https://vaadin.com/docs/next/tools/llms.txt)

# Getting Started with Observability Kit

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](https://micrometer.io). 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](https://vaadin.com/docs/next/tools/observability/migrating-to-v5.md) page.

## <a id="requirements"></a>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](#other-setups).

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

## <a id="add-the-dependency"></a>Add the Dependency

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

`pom.xml`

```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](https://vaadin.com/docs/next/tools/observability/reference.md#ui-state-size), which predicts when a server-driven application has to scale, and [database monitoring](https://vaadin.com/docs/next/tools/observability/reference.md#database-monitoring).

## <a id="export-the-metrics"></a>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](https://prometheus.io):

`pom.xml`

```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:

`application.properties`

```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](https://vaadin.com/docs/next/tools/observability/integrations.md) page for vendor-specific setup.

## <a id="run-verify"></a>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](https://start.vaadin.com), add the dependencies above, and run it.

During development you can also inspect what the kit collected without a backend. When the application runs in development mode, the kit contributes an **Observability** panel to Vaadin Copilot. It leads with the findings — the interactions that failed or ran over budget, the slow data queries, the errors browsers reported — and keeps every `vaadin.*` meter below them, snapshotted straight from the running registry and grouped by the route it was recorded on. This panel is development-mode only and has no effect in production. See the [Copilot Panel](https://vaadin.com/docs/next/tools/observability/copilot-panel.md) page for what it shows, how findings are ranked, and how it announces new ones.

For the full list of built-in meters, see the [Reference](https://vaadin.com/docs/next/tools/observability/reference.md) page.

## <a id="see-what-users-ran-into"></a>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:

`application.properties`

```properties
management.endpoints.web.exposure.include=prometheus,vaadin
```

Then read them at `GET /actuator/vaadin/observability`. See the [Interaction Insights](https://vaadin.com/docs/next/tools/observability/insights.md) page for the payload and its options.

## <a id="other-setups"></a>Other Setups

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

### <a id="plain-spring-without-spring-boot"></a>Plain Spring (Without Spring Boot)

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

`pom.xml`

```xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>observability-kit-spring</artifactId>
</dependency>
```

`ObservabilityConfig.java`

```java
@Configuration
@Import(ObservabilityConfiguration.class)
class ObservabilityConfig {

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

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

### <a id="standalone"></a>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](https://vaadin.com/docs/next/flow/advanced/application-lifecycle.md).

`pom.xml`

```xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>observability-kit-micrometer</artifactId>
</dependency>
```

`ObservabilitySetup.java`

```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:

Inside `contextInitialized()`

```java
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](https://vaadin.com/docs/next/tools/observability/customization.md).

## <a id="troubleshooting"></a>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](https://vaadin.com/docs/next/tools/observability/insights.md) 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](https://vaadin.com/docs/next/tools/observability/reference.md) 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](https://vaadin.com/docs/next/tools/observability/integrations.md#percentiles).

## <a id="next-steps"></a>Next Steps

- [Configuration](https://vaadin.com/docs/next/tools/observability/configuration.md) — turn features on or off and tune the kit.

- [Custom Instrumentation](https://vaadin.com/docs/next/tools/observability/customization.md) — record your own metrics and traces alongside the built-in ones.

- [Interaction Insights](https://vaadin.com/docs/next/tools/observability/insights.md) — backtrack a user report to the interaction that caused it.

- [Client Error Insights](https://vaadin.com/docs/next/tools/observability/client-errors.md) — name the script behind an error that never reached the server.

- [Copilot Panel](https://vaadin.com/docs/next/tools/observability/copilot-panel.md) — see the findings and the live meters while you develop.

- [Reference](https://vaadin.com/docs/next/tools/observability/reference.md) — the full list of meters and spans.

- [Integrations](https://vaadin.com/docs/next/tools/observability/integrations.md) — export to Prometheus, Grafana, Datadog, New Relic, and others.

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