Repository navigation
docs: fix inaccuracies and fill gaps in Observability Kit V5 docs - #5922
Conversation
Accuracy fixes, verified against the kit source at HEAD: - The reference and Prometheus pages implied timers publish histogram bucket suffixes by default; they export count/sum/max only, and buckets are opt-in per meter. - Prometheus strips the reserved `_created` suffix, so the counters appear as `vaadin_sessions_total` and `vaadin_ui_total`; noted in the naming conventions, the migration rename step, and the Grafana examples. - `vaadin.navigation` also carries the `error` tag. - The root request span is named `vaadin.request.<type>` (for example `vaadin.request.rpc`), not bare `vaadin.request`, per the kit's observation contract. - Grammar: "Three ways exists", "depends on that its conventions". New content: - Document the client connection meters added in observability-kit#385: `vaadin.client.connection` and `vaadin.client.connection.downtime`, with the `state` tag values, plus the `_unknown` error kind. - "Percentiles and Histogram Buckets" section on the Integrations page: percentile queries silently return no data until buckets are enabled via `management.metrics.distribution.percentiles-histogram.*`. - "Example Dashboard Queries" on the Grafana page: PromQL recipes for the most useful panels, derived from the observability use-case app. - Troubleshooting section in Getting Started: dev-mode license check silently skipping instrumentation, lazily registered `vaadin.errors`, Prometheus renames, and empty percentile queries. - Migration guide: v4 histogram queries break structurally (no buckets), parallel long-task timer series, and logs no longer exported. - Insights: the UX budget is fixed, endpoint access on restricted setups, in-process reads through the VaadinObservabilityEndpoint bean. - Error propagation to the enclosing Spring HTTP observation (#381), and a GraalVM native-image support note.
The Interaction Insights page said the payload is meant for AI agents (applicationFrame, replay, suggestion) but never showed how to use one. Add a worked example piping /actuator/vaadin/observability into a coding agent CLI, with the practicalities: match the revision that produced the insights, the default payload is safe to forward without detail collection, and query insights need the agent to locate the data provider itself.
The example queries on the Grafana page were derived from the dashboard provisioned in vaadin/use-cases/observability; point readers at it so they can import the JSON or run its compose stack instead of rebuilding the panels by hand.
github-project-automation
Bot
moved this to 🔎Iteration reviews
in Vaadin Flow | Hilla | Kits ongoing work
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-5922.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from a1bdc00 |
caalador
left a comment
caalador
left a comment
There was a problem hiding this comment.
vaadin.db.fetch.rows already publishes percentiles — DatabaseFetchMetrics.java:58 .publishPercentiles(0.95, 0.99). It's a DistributionSummary, so the new section's wording ("The kit's timers export their count, sum, and max only") is technically safe, but a reader comes away believing no percentile data exists anywhere without opting in.
This is the one meter that ships client-side quantiles by default, and it's documented nowhere. One sentence in the new Percentiles section would close it.
| |On `vaadin.client.errors`, the source of the browser error: `uncaught` or `promise`, with `_unknown` for a report that is neither. | ||
|
|
||
| |`state` | ||
| |On the client connection meters, the connection state: `connected`, `reconnecting` (the first request failed, the client is retrying), or `connection-lost` (the client exhausted its retries), with `_unknown` for a reported state outside that set. |
There was a problem hiding this comment.
The state tag row is wrong for the downtime timer.
ClientMetricNames.downtimeState() admits only OFFLINE_STATES, with the javadoc spelling it out: "a browser only spends time being unreachable, so STATE_CONNECTED on this meter would be a contradiction and is bucketed with the rest." So on vaadin.client.connection.downtime, a reported connected becomes _unknown. The counter takes all three; the timer takes two.
There was a problem hiding this comment.
Fixed in f2ea140. The state row now separates the two meters: the counter takes all three states, the downtime timer takes only the two unreachable ones, and both bucket anything else as _unknown.
| |On the data provider meters, whether the query carried a filter: `true` or `false`. | ||
| This separates a combo box loading matches for typed text from one loading the whole data set. | ||
|
|
||
| |`trigger` |
There was a problem hiding this comment.
trigger was left behind. The PR added _unknown to the kind and state rows, but MeterNames.TRIGGER_UNKNOWN = "_unknown" exists too, and reference.adoc:452 still lists only back and programmatic. Same fallback, same table, now inconsistent within itself.
There was a problem hiding this comment.
Fixed in f2ea140. The trigger row now lists _unknown as the fallback, same as kind and state.
There was a problem hiding this comment.
configuration.adoc wasn't updated alongside reference.adoc. The navigation row still reads "tagged by route and outcome" while the PR added error to the same meter at reference.adoc:162.
The errors row right below it does list all three of its tags, so the omission reads as a fact, not a summary.
There was a problem hiding this comment.
Fixed in f2ea140. The navigation row now lists route, outcome, and error, matching the reference table.
| Version 5 timers publish count, sum, and max only, so a `histogram_quantile()` query or a latency alert finds no `_bucket` series until you enable them per meter -- and it fails silently, returning no data rather than an error. | ||
| See <<integrations#percentiles,Percentiles and Histogram Buckets>>. | ||
| * Prometheus strips the reserved `_created` suffix, so `vaadin.sessions.created` and `vaadin.ui.created` appear as `vaadin_sessions_total` and `vaadin_ui_total`. | ||
| * With tracing on, each observed timer also publishes a parallel long-task timer (`_active` series in Prometheus), which roughly doubles the series count for those meters. |
There was a problem hiding this comment.
_active is explained only here; reference.adoc:24 and prometheus.adoc:93 enumerate suffixes without it.
There was a problem hiding this comment.
Fixed in f2ea140. The _active_seconds family is now also mentioned in the reference naming note and on the Prometheus page, where the suffixes are listed.
| |`sum(vaadin_ui_active)` | ||
|
|
||
| |Requests handled | ||
| |`sum(vaadin_request_duration_seconds_count)` |
There was a problem hiding this comment.
"Requests handled" uses a raw cumulative counter while the neighbouring row uses rate()
There was a problem hiding this comment.
Fixed in f2ea140. Changed to a rate query and renamed the row to "Request rate", consistent with the neighboring rows.
Review feedback on the new Percentiles section: the kit's one exception is the database fetch summary, which calls publishPercentiles(0.95, 0.99) and therefore needs no bucket configuration for the alerting the reference page describes. Note it in both places, including the per-instance, non-aggregatable nature of pre-computed percentiles.
|
Good catch — verified: |
…tency - The state tag row now distinguishes the two connection meters: the downtime timer admits only the unreachable states, so a reported connected is bucketed as _unknown there (ClientMetricNames.downtimeState). - trigger also falls back to _unknown, like kind and state. - The configuration page's navigation row now lists the error tag, matching the reference table. - The _active long-task series is now mentioned where suffixes are enumerated (reference naming note, Prometheus page), not only in the migration guide. - The Grafana "Requests handled" row is now a rate, consistent with the neighboring queries.
github-project-automation
Bot
moved this from 🔎Iteration reviews
to Done
in Vaadin Flow | Hilla | Kits ongoing work
Follow-up to #5769, cross-checking the V5 documentation against the kit source at
vaadin/observability-kitHEAD (4f98221) and thevaadin/use-cases/observabilitydemo application.Accuracy fixes
_bucketsuffixes by default. They export count/sum/max only; buckets are opt-in per meter, and ahistogram_quantile()query over a bucket-less timer silently returns no data._createdis a reserved OpenMetrics suffix, sovaadin.sessions.createdandvaadin.ui.createdexport asvaadin_sessions_totalandvaadin_ui_total. Noted in the naming conventions, the migration rename step, and the Grafana examples.vaadin.navigationalso carries theerrortag.vaadin.request.<type>(e.g.vaadin.request.rpc), per the kit's observation contract test — not barevaadin.request.New content
vaadin.client.connectionandvaadin.client.connection.downtimewith thestatetag values, plus the_unknownerror kind.management.metrics.distribution.*properties and the series-count caveat.vaadin.errors, Prometheus renames, empty percentile queries._activeseries, logs no longer exported by the kit.management.endpoint.vaadin.access=unrestricted); in-process reads via theVaadinObservabilityEndpointbean; and a worked "Fixing Insights with an AI Agent" example piping the endpoint payload into a coding agent.Deliberately not documented:
traces-session-id(currently a no-op) and HTTP route templating (observability-kit#384, unmerged).Vale is clean for the changed lines; remaining warnings in these files predate this branch.