Skip to content
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

Adding a few browser related attribute conventions #559

Closed
wants to merge 2 commits into from
Closed

Adding a few browser related attribute conventions #559

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
95663bd
Adding a few browser related attribute conventions
scheler Nov 23, 2023
4720af9
Added browser instance visibiity_state
scheler Nov 30, 2023
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
23 changes: 19 additions & 4 deletions docs/resource/browser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,36 @@ All of these attributes can be provided by the user agent itself in the form of
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended |
| `browser.instance.id` | string | Represents a browser instance, either a window or a tab | `ec34d777-1daf-416b-98b0-05beddfaa199` | Recommended |
| `browser.instance.visibility_state` | string | Visibility status of the browser instance | `visible`; `hidden` | Recommended |
| `browser.language` | string | Preferred language of the user using the browser [2] | `en`; `en-US`; `fr`; `fr-FR` | Recommended |
| `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] | | Recommended |
| `browser.platform` | string | The platform on which the browser is running [4] | `Windows`; `macOS`; `Android` | Recommended |
| [`user_agent.original`](../attributes-registry/user-agent.md) | string | Full user-agent string provided by the browser [5] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Recommended |
| `browser.page.instance.id` | string | Represents an instance of a page in the browser [4] | `4e58989a-4e4d-4f62-bf4f-ac5cd49b4b9a` | Recommended |
| `browser.page.url` | string | Full URL of a page [5] | `https://www.netflix.com/Login` | Recommended |
| `browser.platform` | string | The platform on which the browser is running [6] | `Windows`; `macOS`; `Android` | Recommended |
| [`user_agent.original`](../attributes-registry/user-agent.md) | string | Full user-agent string provided by the browser [7] | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36` | Recommended |

**[1]:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.brands`).

**[2]:** This value is intended to be taken from the Navigator API `navigator.language`.

**[3]:** 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]:** 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]:** The same page when visited at a different time represents a new instance and should get a new id.

**[5]:** Represents the url of the current page in the browser.

**[6]:** 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.

**[5]:** The user-agent value SHOULD be provided only from browsers that do not have a mechanism to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the value, the legacy `navigator.userAgent` API can be used.
**[7]:** The user-agent value SHOULD be provided only from browsers that do not have a mechanism to retrieve brands and platform individually from the User-Agent Client Hints API. To retrieve the value, the legacy `navigator.userAgent` API can be used.

`browser.instance.visibility_state` MUST be one of the following:

| Value | Description |
|---|---|
| `visible` | Browser instance is visible |
| `hidden` | Browser instance is hidden |
<!-- endsemconv -->

[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
28 changes: 28 additions & 0 deletions model/resource/browser.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,31 @@ groups:
to retrieve brands and platform individually from the User-Agent Client Hints API.
To retrieve the value, the legacy `navigator.userAgent` API can be used.
examples: ['Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36']
- id: page.url
Copy link
Member

@AlexanderWert AlexanderWert Nov 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

Is page.* really an attribute of the resource browser? Shouldn't that be rather a signal-level attribute?

In particular: if a user navigates to a different page would that also imply that there's a new instance of the OTel SDK in the browser? If not, the page.* must not be a resource attribute, because resource attributes must not change during the lifetime of a resource / SDK instance.

Apart from the above, can we use browser.page.url.full instead? To be consistent with the url.* namespace. Once we have a solution for #339, we will be able to simply replace it with a reuse of the url.full attribute under the browser.page.* namespace

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@AlexanderWert yes, in my intended usage of these attributes they are not at the resource level - I added them here so that all attributes under browser namespace are at one place. I realize this one place is in registry, which didn't exist when this namespace was introduced. I can create the registry entry for browser now, but have one question - these attribute are intended to be added by sdk level processors into both spans and events. Do you want me to create both model/trace/browser.yaml and model/logs/browser.yaml, duplicated?

cc: @martinkuba

Copy link
Contributor

@trisch-me trisch-me Dec 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

@scheler FYI I have opened a PR with browser moved to the registry. I would like in the future to change your PR to add new attributes to the registry directly

type: string
brief: 'Full URL of a page'
note: >
Represents the url of the current page in the browser.
examples: ["https://www.netflix.com/Login"]
- id: page.instance.id
type: string
brief: 'Represents an instance of a page in the browser'
note: >
The same page when visited at a different time represents a new instance and should get a new id.
examples: ["4e58989a-4e4d-4f62-bf4f-ac5cd49b4b9a"]
- id: instance.id
type: string
brief: 'Represents a browser instance, either a window or a tab'
examples: ["ec34d777-1daf-416b-98b0-05beddfaa199"]
- id: instance.visibility_state
type:
allow_custom_values: false
members:
- id: 'visible'
value: 'visible'
brief: 'Browser instance is visible'
- id: 'hidden'
value: 'hidden'
brief: 'Browser instance is hidden'
brief: 'Visibility status of the browser instance'
examples: ["visible", "hidden"]