diff --git a/docs/browser-observability-model.md b/docs/browser-observability-model.md index 082e59d..6b5129e 100644 --- a/docs/browser-observability-model.md +++ b/docs/browser-observability-model.md @@ -23,7 +23,7 @@ This structure ensures that browser-related events can be consistently interpret | Event | Description | Semantic Conventions Status | Instrumentation Status | |----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `browser.navigation` | Captures a page page navigation event (both hard navigations and soft SPA navigations). | In review [PR1910](https://github.com/open-telemetry/semantic-conventions/pull/1910) | In review [PR2386](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2386) | +| [`browser.navigation`](navigation-event.md) | Captures a page page navigation event (both hard navigations and soft SPA navigations). | In review [PR1910](https://github.com/open-telemetry/semantic-conventions/pull/1910) | In review [PR2386](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2386) | | `browser.navigation_timing` | Captures detailed technical milestones from the [PerformanceNavigationTiming](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming) API. | In review [PR1919](https://github.com/open-telemetry/semantic-conventions/pull/1919) | Not created | | `browser.resource_timing` | Captures information about individual resources loaded by the page, from the [PerformanceResourceTiming](https://developer.mozilla.org/docs/Web/API/PerformanceResourceTiming) API. | In review [PR1943](https://github.com/open-telemetry/semantic-conventions/pull/1943) | Merged (similar, as spans) [instrumentation-document-load](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-document-load) | | `browser.web_vital` | Captures Web Vitals metrics such as CLS, INP, LCP, and FID. | Merged [WebVitals](https://opentelemetry.io/docs/specs/semconv/browser/events/#webvital-event) | Not created | diff --git a/docs/navigation-event.md b/docs/navigation-event.md new file mode 100644 index 0000000..e2c9ec3 --- /dev/null +++ b/docs/navigation-event.md @@ -0,0 +1,32 @@ +# Navigation event + +## Purpose + +- Provide a reliable signal that a navigation occurred for analytics, session, and user-journey analysis. +- Complement (not replace) the `browser.navigation_timing` event, which is used for performance metrics. + +## Use cases + +### Reliable count of page loads (hard navigations) + +For full page loads, this event SHOULD be emitted as early as practical after the browser commits the new URL. Durations and detailed milestones for page load are captured separately by the Navigation Timing event (from the PerformanceNavigationTiming API). Navigation timing data is typically sent when timing fields are finalized (often after the `load` event), which means it may be missing if the user leaves early or if `load` never fires. The navigation event therefore provides a more reliable analytics signal, while navigation timing is used for performance analysis. + +Hard page loads MUST be distinguishable from other navigation types. Implementations MUST include the `same_document` attribute to indicate whether the navigation replaced the document (`same_document = false`) or not. + +### Capturing soft navigations + +The concept of soft navigation (e.g., SPA route changes) is not standardized and is typically implemented by framework routers. Practical heuristics include: initiated by a user action (for example, a click) and resulting in both a URL change (e.g., `history.pushState`/`replaceState`) and a visible change in page content. + +Since soft navigations are analyzed similarly to page loads, they SHOULD be represented using this navigation event as well. + +TODO: Define how soft navigations are identified and represented in semantic conventions. This is not standardized yet. + +### Capturing same-document navigations + +This event can also capture same-document navigations for deeper session and user-journey analysis. Examples can include: + +* Hash changes (for example, links to sections within the same document) +* Query/search parameter changes when application state is encoded in the URL +* Certain back/forward interactions that do not replace the document (depending on history state) + +The main purpose of the navigation event is to cover hard page loads and soft navigations. Other same-document navigations can introduce noise. Therefore, by default the instrumentation SHOULD NOT collect these additional events, but MAY allow them to be enabled via configuration.