Add browser navigation event #2806
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,7 +9,7 @@ linkTitle: Events | |
| This document defines semantic conventions for browser (web) instrumentations | ||
| that emit events. | ||
|
|
||
| ## Event: `browser.web_vital` | ||
|
|
||
| <!-- semconv event.browser.web_vital --> | ||
| <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. --> | ||
|
|
@@ -51,4 +51,72 @@ semantic convention tooling supports complex attributes | |
| <!-- END AUTOGENERATED TEXT --> | ||
| <!-- endsemconv --> | ||
|
|
||
| ## Event: `browser.navigation` | ||
|
|
||
| <!-- semconv event.browser.navigation --> | ||
| <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. --> | ||
| <!-- see templates/registry/markdown/snippet.md.j2 --> | ||
| <!-- prettier-ignore-start --> | ||
| <!-- markdownlint-capture --> | ||
| <!-- markdownlint-disable --> | ||
|
|
||
| **Status:**  | ||
|
|
||
| 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` |  | | ||
| | [`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` |  | | ||
| | [`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` |  | | ||
| | [`browser.navigation.type`](/docs/registry/attributes/browser.md) | string | The type of navigation [4] | `push`; `replace`; `reload`; `traverse` | `Recommended` |  | | ||
|
There was a problem hiding this comment. Not sure how much of a benefit we would have in resembling the Navigation event from Browser spec which is basically a History change activity. For Spec, we would be better off capturing this as I don't think we need to be in 1-1 with Browser Spec. If we take this route, it would be easier to group all the navigations that are associated within a Session in the backend. We can also eliminate all the other hashChange, sameDocument fields are the SDK can basically trigger a pageView event dictating whether it was a navigation event that happened due to this type. |
||
|
|
||
| **[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:[email protected]/`. | ||
| In such case username and password SHOULD be redacted and attribute's value SHOULD be `https://REDACTED:[email protected]/`. | ||
|
|
||
| `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. | ||
|
|
||
|  | ||
| 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. |  | | ||
| | `reload` | The current location was reloaded. |  | | ||
| | `replace` | The current location was replaced, causing the current entry to be replaced in the history list. |  | | ||
| | `traverse` | The browser navigated from one existing history entry to another existing history entry. |  | | ||
|
|
||
| <!-- markdownlint-restore --> | ||
| <!-- prettier-ignore-end --> | ||
| <!-- END AUTOGENERATED TEXT --> | ||
| <!-- endsemconv --> | ||
|
|
||
| [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
question: Any reason to set this attribute as required? I'm worried about browser support here, since the Navigation API is not yet supported in Firefox and Safari.
At the same time, I'm also wondering about the relevance of this attribute: are we expecting the SDK to collect navigation entries related to past documents? Shouldn't those entries already be collected when the past document was active, in which case this attribute would always be true?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This indicates whether the navigation resulted in loading a new document. I felt it was important to capture because it is the main indicator to specifically distinguish hard page loads.
For Firefox and Safari, we can instrument the History API. Any call to
history.pushStateorhistory.replaceStateshould be captured as same_document = true, while the event captured when the page is first loading should be same_document = false.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Forgive me if I'm wrong as I am new to the Navigation API, but from my tests it doesn't seem to be the case.
sameDocumentindicates that theNavigationHistoryEntrywas on the current document (also the doc seems to confirm this).Test:
navigation.currentEntry.sameDocument. It should betrue(even if it's a whole new document)history.pushState(null, '', 'foo')then look atnavigation.entries(). A new navigation entry was added to the list, and both entries havesameDocument: truelocation.href = '/'then look atnavigation.entries()again. A new navigation entry withsameDocument: truewas added to the list, and the first two entriessameDocumentbecamefalse.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ooh I understand your point of view as you are referring to the
navigateEvent.destination.sameDocumentproperty. In this case yes it distinguishes between soft and hard navigations, but I don't think we should collect hard navigations this way? The hard navigation should be collected after the page is loaded, no?