Skip to content

fix: update observability documentation (#5958) #6098

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
caalador wants to merge 1 commit into
base: v25.3
Choose a base branch
from
Open

fix: update observability documentation (#5958) #6098

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion articles/tools/observability/client-errors.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ It's the one insight type that can describe a failure the server never handled -

This page covers browser errors specifically.
For failed and slow server-side interactions, the endpoint itself, and the payload envelope they share, see the <<insights#,Interaction Insights>> page.
In development mode these insights also appear, alongside the server-side ones, in the <<insights#copilot,Copilot panel>>.


== Requirements
Expand Down Expand Up @@ -242,7 +243,7 @@ A report that survives a reload keeps the wait it had accrued -- it's written to
[NOTE]
====
The buffer holds at most 200 samples per tab, and both the buffer and the server's rate limit shed load by class rather than by age.
Browser errors rank second, behind the connection-state samples that explain an outage and ahead of bootstrap, navigation, and Web Vitals timing.
Browser errors rank second, behind the connection-state samples that explain an outage and ahead of every timing sample -- bootstrap, navigation, UIDL request and rendering, and Web Vitals.

Two consequences: a full buffer drops timing samples before it drops the error behind a user's report, and a post-outage flush that exceeds [propertyname]`vaadin.observability.client-rate-per-session` loses timing samples rather than errors.
A batch also stays in `sessionStorage` until the server has answered for it, and one nobody has answered for within 30 seconds is taken back and sent again, so a lost reply can't stall the collector for the life of the tab.
Expand Down
15 changes: 8 additions & 7 deletions articles/tools/observability/configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ When you need to turn features off or tune them, how you configure the kit depen
|`vaadin.observability.*` properties in [filename]`application.properties` (or any Spring property source).

|Plain Spring
|Most of the same `vaadin.observability.*` keys, read with `@Value`.
|Most of the same `vaadin.observability.*` keys, read from the Spring [classname]`Environment`.
See <<#plain-spring,Plain Spring>> for the ones it doesn't bind.

|Standalone
Expand Down Expand Up @@ -113,19 +113,20 @@ Off by default, since SQL is higher cardinality and can be sensitive.

|`vaadin.observability.insights`
|`true`
|Retain failed and over-budget user interactions for the insights endpoint.
Failures also need `errors`, and slow interactions also need `requests`.
|Retain failed and over-budget user interactions, and the errors browsers report, for the insights endpoint.
Failures also need `errors`, slow interactions also need `requests`, and browser errors also need `client`.
See the <<insights#,Interaction Insights>> page.

|`vaadin.observability.insights-details`
|`false`
|Allow retained interactions to carry the exception message, the top stack frames, and the raw session ID.
|Allow retained interactions to carry the exception message, the top stack frames, and the raw session ID, and retained browser errors their message and function name.
Off by default, since the insights payload is meant to be forwarded.
For a browser error it governs collection rather than only retention, and is read by a page when it loads.

|`vaadin.observability.insights-capacity`
|`100`
|Maximum number of retained records, applied to each buffer rather than shared.
Interactions and data provider queries are retained separately, so with both active the total is twice this.
Interactions, data provider queries, and browser errors are retained separately, so with all three active the total is three times this.
The oldest is evicted once a buffer's cap is reached.

|`vaadin.observability.route-cardinality-limit`
Expand Down Expand Up @@ -236,7 +237,7 @@ Also gates the data query insights.
Also decorates the session error handler, which is what makes the failures Flow routes there countable and attributable to a component.

|`client`
|Browser-observed signals -- bootstrap, navigation, and Web Vitals timing, client errors, and connection-state transitions with their downtime.
|Browser-observed signals -- bootstrap, navigation, UIDL request and rendering, and Web Vitals timing, client errors, and connection-state transitions with their downtime.

|`resync`
|A counter of UIDL message resends and client-requested resynchronizations, tagged by type.
Expand All @@ -249,7 +250,7 @@ Spring Boot starter only, off by default.
|Tracing spans for the request lifecycle, navigation, RPC, executor tasks, data provider queries, and -- with database monitoring on -- JDBC queries, emitted through the Observation API.

|`insights`
|Retained failed and over-budget interactions and data provider queries, served by the insights endpoint.
|Retained failed and over-budget interactions, data provider queries, and browser errors, served by the insights endpoint.
This one records no meters or spans; see the <<insights#,Interaction Insights>> page.
|===

Expand Down
6 changes: 4 additions & 2 deletions articles/tools/observability/getting-started.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,9 +96,11 @@

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

Check failure on line 101 in articles/tools/observability/getting-started.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'snapshotted'?

Raw Output:
{"message":"[Vale.Spelling] Did you really mean 'snapshotted'?","location":{"path":"articles/tools/observability/getting-started.adoc","range":{"start":{"line":101,"column":180},"end":{"line":101,"column":191}}},"severity":"ERROR","code":{"value":"Vale.Spelling"}}
This panel is development-mode only and has no effect in production.
See <<insights#copilot,The Copilot Panel>> for what it shows and how findings are ranked.

For the full list of built-in meters, see the <<reference#,Reference>> page.

Expand Down
Loading
Loading