Observability Kit 5: Agent-less Micrometer Rebuild

[mshabarov]

PRD: Observability Kit 5

Tier: Commercial
License: Commercial

Description

Observability Kit 5 is an agent-less rebuild of Vaadin's Observability Kit on top of Micrometer (metrics) and Micrometer Observation/Tracing, replacing the OpenTelemetry Java-agent architecture of 4.x. It ships as a plain library — a Spring Boot version and a non-Spring version — so a Vaadin application becomes observable by adding a dependency, with no -javaagent and no separate collector required to get started.

Motivation

Background

Observability Kit 4.x is built around an OpenTelemetry Java agent (-javaagent:…) plus an OTel-JS browser bundle that round-trips frontend spans through a Vaadin request handler back into the agent. The agent is load-bearing: the starters emit nothing without it. This works, but the agent is the single biggest source of friction in adoption and deployment.

Problem

For developers: 4.x's -javaagent is hard to deploy on Kubernetes, managed runtimes, and GraalVM native image — adoption drops at the deployment step, exactly where the kit should start paying off.

For Spring Boot teams: 4.x integration is shallow — no Micrometer Observation, no Actuator surface, no AOT/native story — so the kit doesn't behave like a first-class Spring Boot citizen.

For evaluators: the kit requires a lot of setup of various tools, plus running the application with the right parameters, just to see what it is about. It should be doable in a few minutes.

For anyone diagnosing a live application: locating a problem takes more Vaadin-specific metrics and the ability to trace the full request chain — from an event in the browser to the server and back. It also takes visibility into memory consumption, so the source of large memory usage can be pinpointed.

Solution

A library-only, Micrometer-native kit with a Spring (Boot) version and a non-Spring version. Alongside it, a publicly deployed reference setup — a (fake) production application wired to the kit, a live dashboard over its telemetry, and an AI workflow that watches that telemetry and files issues automatically — demonstrates the three core scenarios the kit is meant to solve:

1. Pinpoint the source of client and/or server slowness when opening a view or performing another UI operation. Typical problems:

• a. Network delays
• b. Dropped packets needing re-sending
• c. Too many components in the view, or components involving slow JS operations
• d. Server-side slowness from calling external services, fetching the full database, etc.
• e. Vaadin bugs causing slowness in request handling

2. Pinpoint the source of exceptions, client or server side — including which UI event or interaction triggered them, not just a server-side stack trace. Typical problems:

• a. Empty data not handled properly on the server → NPE
• b. Other server-side exceptions that end up in the Vaadin error handler
• c. Client-side error caused by a bug in a component
• d. Client-side error caused by a bug in Vaadin

3. Pinpoint the source of excessive memory usage on the server. Typical problems:

• a. Not lazy-loading data for a grid
• b. Accidentally fetching the full database and storing a reference in a field
• c. Memory leaks — keeping old views or other objects in memory after they are no longer needed

Requirements

• A Vaadin application becomes observable by adding a single dependency — no JVM agent, no -javaagent flag.
• Out-of-the-box Vaadin-aware metrics: active sessions and UIs, navigation/route timing, request and error counts and timings, session-lock contention, and client/RPC interaction timing.
• Distributed tracing of the request chain, including across UI.access(...) asynchronous thread boundaries, so a single operation can be followed end to end on the server.
• Exceptions and interactions are attributed to the UI event that triggered them — which component and which event (a button click, a value change, a navigation) — so a failure can be traced back to what the user did, not just a server-side stack trace.
• Collection of client-side (browser) timings, delivered to the server without developer-written JavaScript and rate-limited per session.
• First-class Spring Boot integration: auto-configuration and properties under vaadin.observability.*, instrumented by adding one dependency.
• Support for plain Spring applications (opt-in configuration) and standalone servlet deployments.
• A documented public API for custom instrumentation, available at each integration layer (annotation-based, fluent helpers, and raw beans).
• Works on GraalVM native image / Spring AOT, verified end to end.
• Runtime license check
• Documentation, including a 4.x → 5.x migration guide that replaces the -javaagent setup and OTel spans with the Micrometer-based approach.
• Per-UI state-size / component-tree-size metric for capacity planning.
• A fake production application with typical problematic scenarios running at http://observability-cases.fly.dev/
• A live, public dashboard connected to the above app running at http://observability-cases-dashboard.fly.dev/
• A demonstrated AI workflow that continuously tracks the live observability data from the reference application, detects issues in real time, formulates them into written problem reports, and files them as GitHub issues. (The reference application lives in vaadin/use-cases/observability, and issues are filed against the vaadin/use-cases repository for now.)
• Tested reference dashboards: Prometheus + Grafana, plus Datadog / New Relic / Dynatrace.

Nice-to-haves

• A Vaadin-owned frontend client (@vaadin/observability-kit) capturing browser long tasks and optional web-vitals, replacing the OTel-JS bundle.
• A Vaadin Copilot observability panel showing live per-route render time, server round-trip, data-provider call counts, errors, and long tasks — usable in dev mode with no external backend.
• Vaadin-specific Actuator endpoints (sessions, routes, insights).
• A single correlated browser → server → backend trace via a per-interaction correlation id / W3C traceparent.
• Push/WebSocket client instrumentation and a connection-state metric.

Release plan

Release as part of Vaadin 25.3

Risks, limitations and breaking changes

Risks

• Building blocks vs. evaluator-visible value. Risk of spending the budget on internal refactoring and extension points and never reaching the things an evaluator actually sees — the DevTools tab, reference dashboards, and a fast time-to-first-trace.
• AI insights may mislead. AI-driven performance analysis can drift into wrong suggestions, so insights must be opt-in, grounded in real meters, and clearly framed as advisory. The auto-filed-issue workflow raises the stakes: it must avoid flooding the tracker with false, noisy, or duplicate reports.

Limitations

• Agent-less instrumentation cannot auto-instrument arbitrary existing code the way the 4.x agent could; coverage is bounded by what Vaadin exposes.
• Spring Boot is the first-class target; standalone servlet and plain-Spring deployments are supported but with a thinner surface (no Actuator, no auto-config).

Breaking changes

• No backward compatibility with the 4.x agent-based architecture. Observability Kit 5 is a clean-room replacement: the -javaagent extension and the OTel-JS browser bundle are removed, and OpenTelemetry becomes an optional Micrometer bridge. 4.x remains supported for the lifetime of Vaadin 25.x, and a migration guide covers the move.
• New major version (5.0), new package (com.vaadin.observability.*) and configuration namespace (vaadin.observability.*).

Out of scope

• Reimplementing an APM dashboard — visualization is delegated to the customer's backend (or a future add-on).
• Acting as a generic observability library — the kit stays Vaadin-aware (routes, UIs, sessions, components, data providers).
• A Vaadin-hosted observability backend as a managed service

Metrics

Success criteria:

• The kit can be evaluated in ~5 minutes against the developer's own application, with no JVM agent.
• Time-to-first-trace on a fresh Vaadin project drops from "after Prometheus/Jaeger/Datadog are in place" to seconds (dependency).
• Ratio of evaluators who find that the kit provides useful and actionable information to those who do not

Pre-implementation checklist

• Product Manager sign-off
• Engineering Manager sign-off

Pre-release checklist

• Verified with pilot customer
• Documented (migration guide + custom-instrumentation API + reference dashboards)
• UX/DX tests conducted and blockers addressed
• Approved for release by Product Manager

Security review

Required. The kit collects telemetry (request/route/session/UI metrics and client-side timings) into the application's MeterRegistry and exposes it through Micrometer registries, optional Vaadin Actuator endpoints, and opt-in AI insights.

[knoobie]

@mshabarov how about back porting the missing SPI into 25.2 while still in early beta? This could ease testing down the line for customer with a stable 25.2.x and the upcoming kit

[mshabarov]

@mshabarov how about back porting the missing SPI into 25.2 while still in early beta? This could ease testing down the line for customer with a stable 25.2.x and the upcoming kit

Yes, if you mean these event listeners (session lock and RPC) - they have been back ported to 25.2, thanks for asking.

[knoobie]

Exactly! Thanks for considering!