From 162ad5e68832dfd84307bb7d60de3974ac249743 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Wed, 24 Sep 2025 21:05:41 -0700 Subject: [PATCH 1/5] added navigation event definition --- model/browser/events.yaml | 16 +++++++++++++ model/browser/registry.yaml | 47 +++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) diff --git a/model/browser/events.yaml b/model/browser/events.yaml index 00fedf7ee2..a7f8b19235 100644 --- a/model/browser/events.yaml +++ b/model/browser/events.yaml @@ -52,3 +52,19 @@ groups: brief: A unique ID representing this particular metric instance. requirement_level: required examples: ["v3-1677874579383-6381583661209"] + + - id: event.browser.navigation + stability: development + type: event + name: browser.navigation + brief: > + This event represents a browser navigation action. + attributes: + - ref: url.full + requirement_level: required + - ref: browser.navigation.same_document + requirement_level: required + - ref: browser.navigation.hash_change + requirement_level: recommended + - ref: browser.navigation.type + requirement_level: recommended diff --git a/model/browser/registry.yaml b/model/browser/registry.yaml index 040f2d6838..4b5c52f12c 100644 --- a/model/browser/registry.yaml +++ b/model/browser/registry.yaml @@ -50,3 +50,50 @@ groups: This value is intended to be taken from the Navigator API `navigator.language`. examples: ["en", "en-US", "fr", "fr-FR"] + - id: browser.navigation.type + stability: development + brief: 'The type of navigation' + note: > + The possible values are defined in the + [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigationActivation/navigationType). + type: + members: + - id: push + value: push + stability: development + brief: > + A new location was navigated to, causing a new entry to be pushed onto the history list. + - id: replace + value: replace + stability: development + brief: > + The current location was replaced, causing the current entry to be replaced in the history list. + - id: reload + value: reload + stability: development + brief: > + The current location was reloaded. + - id: traverse + value: traverse + stability: development + brief: > + The browser navigated from one existing history entry to another existing history entry. + examples: ["push", "replace", "reload", "traverse"] + - id: browser.navigation.same_document + type: boolean + stability: development + brief: 'A boolean that is true if the navigation is within the same document' + note: > + This value is intended to be taken from the + [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigationDestination/sameDocument). + examples: [true, false] + - id: browser.navigation.hash_change + type: boolean + stability: development + brief: 'A boolean that is true if the navigation is a fragment navigation.' + note: > + This value is intended to be taken from the + [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigateEvent/hashChange). + examples: [true, false] + + From 2e0864d1b893d08d20343a64354df3970b74fdb0 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Wed, 24 Sep 2025 21:06:20 -0700 Subject: [PATCH 2/5] updated browser markdown files --- docs/browser/browser-events.md | 69 ++++++++++++++++++++++++++++- docs/registry/attributes/browser.md | 24 +++++++++- 2 files changed, 90 insertions(+), 3 deletions(-) diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md index c1aec9abb0..396fd9b897 100644 --- a/docs/browser/browser-events.md +++ b/docs/browser/browser-events.md @@ -9,7 +9,7 @@ linkTitle: Events This document defines semantic conventions for browser (web) instrumentations that emit events. -## WebVital Event +## Event: `browser.web_vital` @@ -51,4 +51,71 @@ semantic convention tooling supports complex attributes +## Event: `browser.navigation` + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `browser.navigation`. + +This event represents a browser navigation action. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`browser.navigation.same_document`](/docs/registry/attributes/browser.md) | boolean | A boolean that is true if the navigation is within the same document [1] | `true`; `false` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`url.full`](/docs/registry/attributes/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [2] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`browser.navigation.hash_change`](/docs/registry/attributes/browser.md) | boolean | A boolean that is true if the navigation is a fragment navigation. [3] | `true`; `false` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`browser.navigation.type`](/docs/registry/attributes/browser.md) | string | The type of navigation [4] | `push`; `replace`; `reload`; `traverse` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `browser.navigation.same_document`:** This value is intended to be taken from the [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigationDestination/sameDocument). + +**[2] `url.full`:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment +is not transmitted over HTTP, but if it is known, it SHOULD be included nevertheless. + +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. +In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:REDACTED@www.example.com/`. + +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed). + +Sensitive content provided in `url.full` SHOULD be scrubbed when instrumentations can identify it. + +![Development](https://img.shields.io/badge/-development-blue) +Query string values for the following keys SHOULD be redacted by default and replaced by the +value `REDACTED`: + +* [`AWSAccessKeyId`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`Signature`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html#RESTAuthenticationQueryStringAuth) +* [`sig`](https://learn.microsoft.com/azure/storage/common/storage-sas-overview#sas-token) +* [`X-Goog-Signature`](https://cloud.google.com/storage/docs/access-control/signed-urls) + +This list is subject to change over time. + +When a query string value is redacted, the query string key SHOULD still be preserved, e.g. +`https://www.example.com/path?color=blue&sig=REDACTED`. + +**[3] `browser.navigation.hash_change`:** This value is intended to be taken from the [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigateEvent/hashChange). + +**[4] `browser.navigation.type`:** The possible values are defined in the [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigationActivation/navigationType). + +--- + +`browser.navigation.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `push` | A new location was navigated to, causing a new entry to be pushed onto the history list. | ![Development](https://img.shields.io/badge/-development-blue) | +| `reload` | The current location was reloaded. | ![Development](https://img.shields.io/badge/-development-blue) | +| `replace` | The current location was replaced, causing the current entry to be replaced in the history list. | ![Development](https://img.shields.io/badge/-development-blue) | +| `traverse` | The browser navigated from one existing history entry to another existing history entry. | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/registry/attributes/browser.md b/docs/registry/attributes/browser.md index d4f145a4bf..453d1fe457 100644 --- a/docs/registry/attributes/browser.md +++ b/docs/registry/attributes/browser.md @@ -12,7 +12,10 @@ The web browser attributes | `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[" Not A;Brand 99", "Chromium 99", "Chrome 99"]` | ![Development](https://img.shields.io/badge/-development-blue) | | `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | ![Development](https://img.shields.io/badge/-development-blue) | | `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | ![Development](https://img.shields.io/badge/-development-blue) | -| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.navigation.hash_change` | boolean | A boolean that is true if the navigation is a fragment navigation. [4] | `true`; `false` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.navigation.same_document` | boolean | A boolean that is true if the navigation is within the same document [5] | `true`; `false` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.navigation.type` | string | The type of navigation [6] | `push`; `replace`; `reload`; `traverse` | ![Development](https://img.shields.io/badge/-development-blue) | +| `browser.platform` | string | The platform on which the browser is running [7] | `Windows`; `macOS`; `Android` | ![Development](https://img.shields.io/badge/-development-blue) | **[1] `browser.brands`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`). @@ -20,5 +23,22 @@ The web browser attributes **[3] `browser.mobile`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.mobile`). If unavailable, this attribute SHOULD be left unset. -**[4] `browser.platform`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. +**[4] `browser.navigation.hash_change`:** This value is intended to be taken from the [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigateEvent/hashChange). + +**[5] `browser.navigation.same_document`:** This value is intended to be taken from the [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigationDestination/sameDocument). + +**[6] `browser.navigation.type`:** The possible values are defined in the [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigationActivation/navigationType). + +**[7] `browser.platform`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. + +--- + +`browser.navigation.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `push` | A new location was navigated to, causing a new entry to be pushed onto the history list. | ![Development](https://img.shields.io/badge/-development-blue) | +| `reload` | The current location was reloaded. | ![Development](https://img.shields.io/badge/-development-blue) | +| `replace` | The current location was replaced, causing the current entry to be replaced in the history list. | ![Development](https://img.shields.io/badge/-development-blue) | +| `traverse` | The browser navigated from one existing history entry to another existing history entry. | ![Development](https://img.shields.io/badge/-development-blue) | From c92972ba2ff78c90e2ee788e36d213eca70bb494 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Wed, 24 Sep 2025 21:14:04 -0700 Subject: [PATCH 3/5] changelog entry --- .chloggen/browser-navigation-event.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .chloggen/browser-navigation-event.yaml diff --git a/.chloggen/browser-navigation-event.yaml b/.chloggen/browser-navigation-event.yaml new file mode 100644 index 0000000000..e6923a2e8b --- /dev/null +++ b/.chloggen/browser-navigation-event.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: browser + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add browser navigation event + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [2806] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: \ No newline at end of file From 7062041f03e88f93b62a6c838a56f8f7220e4ea4 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Wed, 24 Sep 2025 21:16:20 -0700 Subject: [PATCH 4/5] yaml lint --- .chloggen/browser-navigation-event.yaml | 2 +- model/browser/registry.yaml | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/.chloggen/browser-navigation-event.yaml b/.chloggen/browser-navigation-event.yaml index e6923a2e8b..f5af63e0c9 100644 --- a/.chloggen/browser-navigation-event.yaml +++ b/.chloggen/browser-navigation-event.yaml @@ -19,4 +19,4 @@ issues: [2806] # (Optional) One or more lines of additional information to render under the primary note. # These lines will be padded with 2 spaces and then inserted directly into the document. # Use pipe (|) for multiline entries. -subtext: \ No newline at end of file +subtext: diff --git a/model/browser/registry.yaml b/model/browser/registry.yaml index 4b5c52f12c..486da943d2 100644 --- a/model/browser/registry.yaml +++ b/model/browser/registry.yaml @@ -95,5 +95,3 @@ groups: This value is intended to be taken from the [Navigation API specification](https://developer.mozilla.org/en-US/docs/Web/API/NavigateEvent/hashChange). examples: [true, false] - - From c7a4b0db61af6a95845735e284f6678c29b3643c Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Wed, 24 Sep 2025 21:32:37 -0700 Subject: [PATCH 5/5] trying to fix lint --- docs/browser/browser-events.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md index 396fd9b897..60b777d6a4 100644 --- a/docs/browser/browser-events.md +++ b/docs/browser/browser-events.md @@ -117,5 +117,6 @@ When a query string value is redacted, the query string key SHOULD still be pres + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status