Add Resource browser attributes (open-telemetry#2353)

CHANGELOG.md

@@ -78,7 +78,7 @@ release.
 
 ### Resource
 
-- No changes.
+- Add browser.* attributes ([#2353](https://github.com/open-telemetry/opentelemetry-specification/pull/2353)).
 
 ### Semantic Conventions
 

semantic_conventions/resource/browser.yaml

@@ -0,0 +1,41 @@
+groups:
+  - id: browser
+    prefix: browser
+    brief: >
+        The web browser in which the application represented by the resource is running.
+        The `browser.*` attributes MUST be used only for resources that represent applications
+        running in a web browser (regardless of whether running on a mobile or desktop device).
+    attributes:
+      - id: brands
+        type: string[]
+        brief: 'Array of brand name and version separated by a space'
+        note: >
+          This value is intended to be taken from the
+          [UA client hints API](https://wicg.github.io/ua-client-hints/#interface)
+          (navigator.userAgentData.brands).
+        examples: [" Not A;Brand 99", "Chromium 99", "Chrome 99"]
+      - id: platform
+        type: string
+        brief: 'The platform on which the browser is running'
+        note: >
+          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.
+        examples: ['Windows', 'macOS', 'Android']
+      - id: user_agent
+        type: string
+        brief: 'Full user-agent string provided by the browser'
+        note: >
+          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.
+        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'

specification/resource/semantic_conventions/README.md

@@ -156,6 +156,7 @@ Attributes defining a running environment (e.g. Operating System, Cloud, Data Ce
 - Deployment:
   - [Deployment Environment](./deployment_environment.md)
   - [Kubernetes](./k8s.md)
+- [Browser](./browser.md)
 
 ## Version attributes
 

specification/resource/semantic_conventions/browser.md

@@ -0,0 +1,24 @@
+# Browser
+
+**Status**: [Experimental](../../document-status.md)
+
+**type:** `browser`
+
+**Description**: The web browser in which the application represented by the resource is running. The `browser.*` attributes MUST be used only for resources that represent applications running in a web browser (regardless of whether running on a mobile or desktop device).
+
+All of these attributes can be provided by the user agent itself in the form of an HTTP header (e.g. Sec-CH-UA, Sec-CH-Platform, User-Agent). However, the headers could be removed by proxy servers, and are tied to calls from individual clients. In order to support batching through services like the Collector and to prevent loss of data (e.g. due to proxy servers removing headers), these attributes should be used when possible.
+
+<!-- semconv browser -->
+| Attribute  | Type | Description  | Examples  | Required |
+|---|---|---|---|---|
+| `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | No |
+| `browser.platform` | string | The platform on which the browser is running [2] | `Windows`; `macOS`; `Android` | No |
+| `browser.user_agent` | string | Full user-agent string provided by the browser [3] | `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` | No |
+
+**[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 [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.
+
+**[3]:** 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.
+<!-- endsemconv -->