Rename http.user_agent to user_agent.original (#3190)

Fixes #3180 ## Changes Renames `http.user_agent` to `user_agent.original`.
open-telemetry · Mar 2, 2023 · 0e19398 · 0e19398
1 parent ec84e5d
commit 0e19398
Show file tree

Hide file tree

Showing 7 changed files with 35 additions and 17 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -107,6 +107,8 @@ release.
   [#3158](https://github.com/open-telemetry/opentelemetry-specification/pull/3158)
 - `http.route` SHOULD contain the "application root" if there is one.
   ([#3164](https://github.com/open-telemetry/opentelemetry-specification/pull/3164))
+- Rename `http.user_agent` to `user_agent.original`.
+  ([#3190](https://github.com/open-telemetry/opentelemetry-specification/pull/3190))
 
 ### Compatibility
 

diff --git a/schemas/1.19.0 b/schemas/1.19.0
@@ -12,6 +12,16 @@ versions:
         - rename_attributes:
             attribute_map:
               faas.id: cloud.resource_id
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3190
+        - rename_attributes:
+            attribute_map:
+              http.user_agent: user_agent.original
+    resources:
+      changes:
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3190
+        - rename_attributes:
+            attribute_map:
+              browser.user_agent: user_agent.original
   1.18.0:
   1.17.0:
     spans:

diff --git a/semantic_conventions/resource/browser.yaml b/semantic_conventions/resource/browser.yaml
@@ -40,18 +40,17 @@ groups:
           [UA client hints API](https://wicg.github.io/ua-client-hints/#interface)
           (`navigator.userAgentData.mobile`). If unavailable, this attribute
           SHOULD be left unset.
-      - 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'
       - id: language
         type: string
         brief: 'Preferred language of the user using the browser'
         note: >
           This value is intended to be taken from the Navigator API
           `navigator.language`.
         examples: ["en", "en-US", "fr", "fr-FR"]
+      - ref: user_agent.original
+        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']
diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml
@@ -8,10 +8,6 @@ groups:
         These conventions can be used for http and https schemes
         and various HTTP versions like 1.1, 2 and SPDY.
     attributes:
-      - id: user_agent
-        type: string
-        brief: 'Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client.'
-        examples: ['CERN-LineMode/2.15 libwww/2.17b3']
       - id: request_content_length
         type: int
         brief: >
@@ -33,6 +29,7 @@ groups:
       - ref: net.sock.peer.name
       - ref: net.sock.family
         examples: ['inet', 'inet6']
+      - ref: user_agent.original
 
   - id: trace.http.client
     prefix: http

diff --git a/semantic_conventions/user-agent.yaml b/semantic_conventions/user-agent.yaml
@@ -0,0 +1,10 @@
+groups:
+  - id: attributes.user_agent
+    type: attribute_group
+    brief: "Describes user-agent attributes."
+    prefix: user_agent
+    attributes:
+      - id: original
+        type: string
+        brief: 'Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client.'
+        examples: ['CERN-LineMode/2.15 libwww/2.17b3']
diff --git a/specification/resource/semantic_conventions/browser.md b/specification/resource/semantic_conventions/browser.md
@@ -14,8 +14,8 @@ All of these attributes can be provided by the user agent itself in the form of
 | `browser.brands` | string[] | Array of brand name and version separated by a space [1] | `[ Not A;Brand 99, Chromium 99, Chrome 99]` | Recommended |
 | `browser.platform` | string | The platform on which the browser is running [2] | `Windows`; `macOS`; `Android` | Recommended |
 | `browser.mobile` | boolean | A boolean that is true if the browser is running on a mobile device [3] |  | Recommended |
-| `browser.user_agent` | string | Full user-agent string provided by the browser [4] | `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.language` | string | Preferred language of the user using the browser [5] | `en`; `en-US`; `fr`; `fr-FR` | Recommended |
+| `browser.language` | string | Preferred language of the user using the browser [4] | `en`; `en-US`; `fr`; `fr-FR` | Recommended |
+| `user_agent.original` | 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 |
 
 **[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`).
 
@@ -24,7 +24,7 @@ The list of possible values is defined in the [W3C User-Agent Client Hints speci
 
 **[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]:** 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.
+**[4]:** This value is intended to be taken from the Navigator API `navigator.language`.
 
-**[5]:** This value is intended to be taken from the Navigator API `navigator.language`.
+**[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.
 <!-- endsemconv -->
diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md
@@ -67,14 +67,14 @@ sections below.
 |---|---|---|---|---|
 | `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. |
 | `http.flavor` | string | Kind of HTTP protocol used. | `1.0` | Recommended |
-| `http.user_agent` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended |
 | `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
 | `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
 | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
 | [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet`; `inet6` | Conditionally Required: [1] |
 | [`net.sock.peer.addr`](span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended |
 | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [2] |
 | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [3] |
+| `user_agent.original` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended |
 
 **[1]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document.