Skip to content

docs: use cases for the navigation event #41

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
wants to merge 2 commits into
base: main
Choose a base branch
from
+33 −1
Open

docs: use cases for the navigation event #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
85161ec
capture use cases for the navigation event
martinkuba Oct 30, 2025
6be7374
fixed link from the observability model
martinkuba Oct 30, 2025
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
2 changes: 1 addition & 1 deletion docs/browser-observability-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Copy link

@vigneshshanmugam vigneshshanmugam Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| [`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`](navigation-event.md) | Captures a 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 |
Expand Down
32 changes: 32 additions & 0 deletions docs/navigation-event.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link

@vigneshshanmugam vigneshshanmugam Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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 the event might be lost if the user leaves the page early or if `load` event 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
Copy link
Contributor

@BenoitZugmeyer BenoitZugmeyer Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💬 suggestion: From my understanding, "soft navigations" are included in "same-document" navigations. It might be easier to understand if we had a structure like this:

  • Capturing hard navigations
  • Capturing same-document navigations
    • Soft navigations
    • Other URL changes


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
Copy link
Contributor

@joaquin-diaz joaquin-diaz Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that a query string change can lead to no modification of the page content (maybe is just a way of keeping internal state), should that be defined as navigation?

Copy link

@david-luna david-luna Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I recall correctly that was the issue that made us differentiate page_view events from navigation ones.
Ref: #3

Wasn't navigation event scoped to only URL changes? (sorry for my bad memory)

Copy link
Contributor

@joaquin-diaz joaquin-diaz Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also can't remember but I'm ok with it if that's what we agreed on

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