diff --git a/articles/tools/observability/copilot-panel.adoc b/articles/tools/observability/copilot-panel.adoc new file mode 100644 index 0000000000..39948523ac --- /dev/null +++ b/articles/tools/observability/copilot-panel.adoc @@ -0,0 +1,149 @@ +--- +title: Copilot Panel +page-title: Viewing Vaadin Observability Kit insights in Copilot +description: The development-mode panel that shows what went wrong and the live Vaadin meters, without a monitoring backend. +meta-description: Use the Observability Kit panel in Vaadin Copilot to see failed and slow interactions, browser errors, and the live vaadin.* meters as you develop. +order: 38 +--- + + += Copilot Panel + +Metrics and insights normally need a backend, a dashboard, or at least a `curl` against an Actuator endpoint. +During development, Observability Kit skips all of that. +It contributes an *Observability* panel to Vaadin Copilot that shows the same findings the <> publishes, with the live `vaadin.*` meters underneath them. + +The panel is development-mode only. +In production, Copilot and the development tools connection don't exist, so the panel is never loaded and the server never answers for it. + + +== Opening the Panel + +Start the application in development mode and open it in a browser. +The panel is registered with Copilot under the heading *Observability*, behind a bar chart icon in the Copilot toolbar, and it's available in edit, inspect, and test modes. + +Nothing needs to be configured to get it. +The kit injects the panel once per UI whenever it runs outside production mode, provided the license check passed. + + +== Findings First + +The panel opens on the findings rather than on the numbers, because a meter is a number: `vaadin.errors 3` doesn't say which route, which component, or which line to open. + +The findings are the insights described on the <> page -- failed interactions, interactions that ran over the UX budget, failed and slow data provider queries, and browser errors -- and they're the endpoint's own payload, unaltered. +The same service, the same grouping, and the same withholding of sensitive detail apply, so a finding read here and one served to an agent can't drift apart. + +The panel ranks them for display: errors before warnings, then the most-reported first, then the most recent. +An error that ten users hit outranks one that happened once. + +The header says how many findings need attention. +When there are none, it reads *Insights* and the body explains which of two things that means: + +- *No problems detected yet*, when the collectors are bound and nothing has gone wrong. +- *Insights are not being collected*, when nothing was watching in the first place. + +See <<#requirements,What the Panel Needs>> for the settings behind the second case. + +Before the first payload arrives the panel says it's waiting, rather than claiming that nothing is wrong. + + +== Reading a Finding + +Each row shows the summary, a severity dot, and a line of context underneath: the route, the component or script, how many occurrences the group has, and when it was last seen. + +Select a row to expand it. +The expanded row shows the finding's full evidence, the [propertyname]`replay` steps that reproduce it, and the [propertyname]`suggestion` -- exactly as the server wrote them. +Rows stay expanded while their occurrence count climbs, and while you close the panel to look at the code and open it again. + +The *Copy* button on a row puts the whole finding on the clipboard as JSON. +That's the shortest path from noticing a problem to handing it to an AI agent that has the codebase checked out; see <> for what an agent does with it. +Copying needs the browser's clipboard API, which is available on `localhost` and over HTTPS; the button confirms with *Copied*, or reports *Failed* where the browser denies access. + + +== New Findings Announce Themselves + +The panel keeps watching while its window is closed, and writes a line to the Copilot log for each finding the payload didn't have before. +This is the point of the panel for most of a working day: you don't have to have it open to learn that something broke. + +Announcements are deduplicated on the same grouping key the endpoint uses, so one problem notifies once, however often it recurs. +Only findings that the current page raised are announced -- anything first seen since the page loaded, including during the load itself, so a slow query on the landing view is reported. +The retained records outlive a reload, and those older findings are not announced again. + +Errors are logged as errors and everything else as a warning, each prefixed with `Observability:`. +The message is a summary, and the server cuts anything longer than 300 characters. + +[NOTE] +Announcements are best-effort. +Copilot's plugin API has no notification of its own, so the line is written by asking the server to send Copilot's own log command; a Copilot that drops it costs you a notification, never the panel. + + +== Live Meters by Route + +Below the findings is the *Metrics* section, holding every `vaadin.*` meter in the running registry. +Its header carries the meter count and the time of the last snapshot. + +The section is folded away when there's something to look at above it and unfolded when there isn't. +That's decided once, by the first payload that reaches the panel; after you fold or unfold it yourself, your choice stands. + +Meters are *grouped by the route they were recorded on*, and each group is headed by its route template: + +[cols="1,3"] +|=== +|Heading |Contents + +|The route template +|The meters recorded on that route. +The root view, whose template is the empty string, appears as *Root*. + +|Other routes +|Meters carrying the `_other` sentinel, which the kit aggregated rather than tagged per route. + +|Route not resolved +|Meters carrying the `_unknown` sentinel, recorded where no route could be determined. + +|General +|The application-wide meters that carry no `route` tag at all. +|=== + +The route the browser is on comes first, marked _current page_. +Every other route follows alphabetically, then the two sentinel groups, and *General* last. + +Route groups are matched against the browser's location by route template, so `orders/:orderId` is the current group while you're on `/orders/17`. +An application served under a context path has that path in front of every location and in none of the templates, so nothing matches and the groups stay alphabetical. + +Each row shows the meter name, its remaining tags, its value, and a sparkline of the last twenty polls. +The value column is derived per meter type rather than raw: + +[cols="1,3"] +|=== +|Meter type |Shown as + +|Timer, distribution summary +|The cumulative mean, the maximum when it's non-zero, and the count as `n=`. +Timers are in milliseconds. + +|Counter, function counter +|The count. + +|Gauge +|The current value. +|=== + +The panel refreshes the meters every three seconds while it's open, and asks for nothing while it's closed. +Insights are polled either way, less often when the panel is closed, which is what makes the announcements possible. + +[NOTE] +Only meters whose name starts with `vaadin.` are exposed to the panel. +Your own meters, including the ones described on the <> page, are recorded into the same registry but aren't shown here. + + +[[requirements]] +== What the Panel Needs + +The meter table needs nothing beyond the kit being installed and licensed. + +The findings need [propertyname]`vaadin.observability.insights`, which is on by default, together with the instrumentation that feeds it: `errors` for failures, `requests` for over-budget records, and `client` for browser errors. +With any of those off, the panel says that insights aren't being collected instead of showing an empty list that reads like "nothing is wrong". + +The panel is loaded only outside production mode, and only when the license check passed. +Nothing about it reaches a production deployment. diff --git a/articles/tools/observability/getting-started.adoc b/articles/tools/observability/getting-started.adoc index b396d28349..e6f0184454 100644 --- a/articles/tools/observability/getting-started.adoc +++ b/articles/tools/observability/getting-started.adoc @@ -97,8 +97,9 @@ Then open `http://localhost:8080/actuator/prometheus` and look for the Vaadin me If you don't have an application yet, you can download one from https://start.vaadin.com[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. +When the application runs in development mode, the kit contributes an *Observability* panel to Vaadin Copilot that shows what went wrong, and below it 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. +See the <> page for what it shows and how it announces new findings. For the full list of built-in meters, see the <> page. @@ -237,6 +238,7 @@ See <>. * <> -- turn features on or off and tune the kit. * <> -- record your own metrics and traces alongside the built-in ones. * <> -- backtrack a user report to the interaction that caused it. +* <> -- see the findings and the live meters while you develop. * <> -- the full list of meters and spans. * <> -- export to Prometheus, Grafana, Datadog, New Relic, and others. diff --git a/articles/tools/observability/insights.adoc b/articles/tools/observability/insights.adoc index 9b3c279e30..1ccd0ab961 100644 --- a/articles/tools/observability/insights.adoc +++ b/articles/tools/observability/insights.adoc @@ -20,6 +20,7 @@ Every insight carries a [propertyname]`replay` list a person can follow to repro An interaction insight also carries a [propertyname]`suggestion` and an [propertyname]`applicationFrame` that an AI agent with access to the codebase can open to verify the problem and propose a fix. Insight collection is on by default and works in production mode. +During development, the same findings are shown in the <>, which also announces new ones as they appear. == What Gets Captured