From e3ed5e0020db3777f9f92b248fbd79851d256d31 Mon Sep 17 00:00:00 2001 From: Alexandra Konrad Date: Thu, 1 Feb 2024 15:18:15 +0100 Subject: [PATCH 1/5] update wording to support multiple apps; fix #662 --- docs/attributes-registry/user-agent.md | 10 +++++----- docs/http/http-spans.md | 4 ++-- model/registry/user-agent.yaml | 17 +++++++++++------ 3 files changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index f75c5d22ce..a005e6087a 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -8,11 +8,11 @@ | Attribute | Type | Description | Examples | |---|---|---|---| -| `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name [1] | `Safari` | -| `user_agent.original` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | -| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2` | +| `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name. [1] | `Safari`; `YourApp` | +| `user_agent.original` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | +| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2`; `1.0.0` | -**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string +**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple applications, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version` -**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string +**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple applications, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 9ed7173c1b..3e11eb8704 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -232,7 +232,7 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | [`server.port`](../attributes-registry/server.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [4] | `80`; `8080`; `443` | Required | | [`url.full`](../attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Opt-In | -| [`user_agent.original`](../attributes-registry/user-agent.md) | 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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | Opt-In | +| [`user_agent.original`](../attributes-registry/user-agent.md) | 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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | Opt-In | **[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information. The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. @@ -349,7 +349,7 @@ For an HTTP server span, `SpanKind` MUST be `Server`. | [`url.path`](../attributes-registry/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component | `/search` | Required | | [`url.query`](../attributes-registry/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [7] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | | [`url.scheme`](../attributes-registry/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. [8] | `http`; `https` | Required | -| [`user_agent.original`](../attributes-registry/user-agent.md) | 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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1` | Recommended | +| [`user_agent.original`](../attributes-registry/user-agent.md) | 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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | Recommended | **[1]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded#for](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#for), [X-Forwarded-For](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index 29e00ff6bc..215dd0e875 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -10,18 +10,23 @@ groups: 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', - 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'] + 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1', + 'YourApp/1.0.0 grpc-java-okhttp/1.27.2'] - id: name type: string brief: > - Name of the user-agent extracted from original. Usually refers to the browser's name - examples: ['Safari'] + Name of the user-agent extracted from original. Usually refers to the browser's name. + examples: ['Safari', 'YourApp'] note: > - [Example](https://www.whatsmyua.info) of extracting browser's name from original string + [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using + a user-agent for non-browser products, such as microservices with multiple applications, the most significant + name SHOULD be selected. In such a scenario it should align with `user_agent.version` - id: version type: string brief: > Version of the user-agent extracted from original. Usually refers to the browser's version - examples: ['14.1.2'] + examples: ['14.1.2', '1.0.0'] note: > - [Example](https://www.whatsmyua.info) of extracting browser's version from original string + [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of + using a user-agent for non-browser products, such as microservices with multiple applications, the most + significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` From 721fc517c28f6bd549aca6038cef098a72453ddb Mon Sep 17 00:00:00 2001 From: Alexandra Konrad Date: Mon, 5 Feb 2024 10:10:52 +0100 Subject: [PATCH 2/5] rephrase --- docs/attributes-registry/user-agent.md | 4 ++-- model/registry/user-agent.yaml | 10 ++++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index a005e6087a..4d905ab9cd 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -12,7 +12,7 @@ | `user_agent.original` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | | `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2`; `1.0.0` | -**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple applications, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version` +**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version` -**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple applications, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` +**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index 215dd0e875..81657b97f8 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -19,8 +19,9 @@ groups: examples: ['Safari', 'YourApp'] note: > [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using - a user-agent for non-browser products, such as microservices with multiple applications, the most significant - name SHOULD be selected. In such a scenario it should align with `user_agent.version` + a user-agent for non-browser products, such as microservices with multiple names/versions inside the + `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with + `user_agent.version` - id: version type: string brief: > @@ -28,5 +29,6 @@ groups: examples: ['14.1.2', '1.0.0'] note: > [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of - using a user-agent for non-browser products, such as microservices with multiple applications, the most - significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` + using a user-agent for non-browser products, such as microservices with multiple names/versions inside the + `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align + with `user_agent.name` From 37d1cb9cc91fb857c2b435a26ad42a457c6e6ccc Mon Sep 17 00:00:00 2001 From: Alexandra Konrad Date: Mon, 5 Feb 2024 12:16:50 +0100 Subject: [PATCH 3/5] rephrase --- docs/attributes-registry/user-agent.md | 2 +- model/registry/user-agent.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 4d905ab9cd..e9ae4564e1 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -14,5 +14,5 @@ **[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version` -**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` +**[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index 81657b97f8..3b38f4572d 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -29,6 +29,6 @@ groups: examples: ['14.1.2', '1.0.0'] note: > [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of - using a user-agent for non-browser products, such as microservices with multiple names/versions inside the + using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` From e6c5740cfe6bd0bb88f833e63cd2ade91ab5ddef Mon Sep 17 00:00:00 2001 From: Alexandra Konrad Date: Mon, 5 Feb 2024 12:34:24 +0100 Subject: [PATCH 4/5] make lint happt --- docs/attributes-registry/user-agent.md | 2 +- model/registry/user-agent.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index e9ae4564e1..3baeaaf931 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -12,7 +12,7 @@ | `user_agent.original` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)
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`; `Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1`; `YourApp/1.0.0 grpc-java-okhttp/1.27.2` | | `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [2] | `14.1.2`; `1.0.0` | -**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version` +**[1]:** [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version` **[2]:** [Example](https://www.whatsmyua.info) of extracting browser's version from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the `user_agent.original`, the most significant version SHOULD be selected. In such a scenario it should align with `user_agent.name` diff --git a/model/registry/user-agent.yaml b/model/registry/user-agent.yaml index 3b38f4572d..f783d379e5 100644 --- a/model/registry/user-agent.yaml +++ b/model/registry/user-agent.yaml @@ -20,7 +20,7 @@ groups: note: > [Example](https://www.whatsmyua.info) of extracting browser's name from original string. In the case of using a user-agent for non-browser products, such as microservices with multiple names/versions inside the - `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with + `user_agent.original`, the most significant name SHOULD be selected. In such a scenario it should align with `user_agent.version` - id: version type: string From f3a7980ffaf6949b2d3213837598f35c7cb13884 Mon Sep 17 00:00:00 2001 From: Alexandra Konrad Date: Tue, 6 Feb 2024 14:31:27 +0100 Subject: [PATCH 5/5] add chlog --- .chloggen/ua_wording.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100755 .chloggen/ua_wording.yaml diff --git a/.chloggen/ua_wording.yaml b/.chloggen/ua_wording.yaml new file mode 100755 index 0000000000..b8be0677f0 --- /dev/null +++ b/.chloggen/ua_wording.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: user-agent + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Update user_agent subfields wording to support it's usage for non-browser products with multiple names/versions + +# 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: [680] + +# (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: