diff --git a/.chloggen/browser-navigation-event.yaml b/.chloggen/browser-navigation-event.yaml new file mode 100644 index 0000000000..f5af63e0c9 --- /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: diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md index c1aec9abb0..60b777d6a4 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,72 @@ 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) | 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..486da943d2 100644 --- a/model/browser/registry.yaml +++ b/model/browser/registry.yaml @@ -50,3 +50,48 @@ 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]