From e5794790f16052dcaa7662010776c3b3a8761738 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Mon, 28 Oct 2024 13:48:09 -0700 Subject: [PATCH 01/26] Add synthetic source. --- .chloggen/add-synthetic-source.yaml | 22 ++++++++++++ docs/attributes-registry/http.md | 18 +++++++--- docs/http/http-metrics.md | 54 ++++++++++++++++++++++------- docs/http/http-spans.md | 18 +++++++--- model/http/metrics.yaml | 2 ++ model/http/registry.yaml | 18 ++++++++++ model/http/spans.yaml | 2 ++ 7 files changed, 114 insertions(+), 20 deletions(-) create mode 100644 .chloggen/add-synthetic-source.yaml diff --git a/.chloggen/add-synthetic-source.yaml b/.chloggen/add-synthetic-source.yaml new file mode 100644 index 0000000000..081cfce0d5 --- /dev/null +++ b/.chloggen/add-synthetic-source.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: http + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add the http.request.synthetic attribute to track if spans and metrics are the result of real users, synthetic testing, or bots. + +# 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: [1127] + +# (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: \ No newline at end of file diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md index 57953b39be..dd0b538b08 100644 --- a/docs/attributes-registry/http.md +++ b/docs/attributes-registry/http.md @@ -22,11 +22,12 @@ This document defines semantic convention attributes in the HTTP namespace. | `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `http.request.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `http.request.size` | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `http.request.synthetic` | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [4] | `bot`; `synthetic test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `http.response.body.size` | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [5] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `http.response.size` | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `http.route` | string | The matched route, that is, the path template in the format used by the respective server framework. [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.route` | string | The matched route, that is, the path template in the format used by the respective server framework. [6] | `/users/:userID?`; `{controller}/{action}/{id?}` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[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. @@ -49,11 +50,13 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[3]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). -**[4]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +**[4]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +**[5]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[5]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +**[6]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. `http.connection.state` 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. @@ -78,6 +81,13 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`http.request.synthetic` 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 | +|---|---|---| +| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + ## Deprecated HTTP Attributes Describes deprecated HTTP attributes. diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index ead391ef70..9f7f05b0f2 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -87,8 +87,9 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.synthetic`](/docs/attributes-registry/http.md) | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [8] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [10] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -133,12 +134,14 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[8]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[10]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. @@ -164,6 +167,13 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`http.request.synthetic` 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 | +|---|---|---| +| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -262,8 +272,9 @@ This metric is optional. | [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.synthetic`](/docs/attributes-registry/http.md) | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [8] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [10] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -308,12 +319,14 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[8]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[10]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. @@ -339,6 +352,13 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`http.request.synthetic` 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 | +|---|---|---| +| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -370,8 +390,9 @@ This metric is optional. | [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.synthetic`](/docs/attributes-registry/http.md) | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [8] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [10] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -416,12 +437,14 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[8]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[10]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. @@ -447,6 +470,13 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`http.request.synthetic` 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 | +|---|---|---| +| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 9104b13bf2..dda228b92b 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -378,12 +378,13 @@ For an HTTP server span, `SpanKind` MUST be `SERVER`. | [`http.request.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [15] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.request.size`](/docs/attributes-registry/http.md) | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`http.request.synthetic`](/docs/attributes-registry/http.md) | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [16] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.response.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [16] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [17] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.response.size`](/docs/attributes-registry/http.md) | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`network.local.address`](/docs/attributes-registry/network.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.local.port`](/docs/attributes-registry/network.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [18] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -446,11 +447,13 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin 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. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[16]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +**[16]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +**[17]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[17]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. +**[18]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): @@ -486,6 +489,13 @@ and SHOULD be provided **at span creation time** (if provided at all): | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`http.request.synthetic` 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 | +|---|---|---| +| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + `network.transport` 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 | diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index 78283fdf75..fc35377228 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -18,6 +18,8 @@ groups: > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. + - ref: http.request.synthetic + requirement_level: opt_in - id: metric_attributes.http.client type: attribute_group brief: 'HTTP client attributes' diff --git a/model/http/registry.yaml b/model/http/registry.yaml index ff0a002d39..44759d557f 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -170,3 +170,21 @@ groups: brief: State of the HTTP connection in the HTTP connection pool. stability: experimental examples: ["active", "idle"] + - id: http.request.synthetic + stability: experimental + brief: > + A flag indicating that the request was synthetically created and did not originate from genuine client traffic. + note: > + This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, + and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + type: + members: + - id: bot + value: "bot" + brief: 'bot source.' + stability: experimental + - id: test + value: "synthetic test" + brief: 'synthetic test source.' + stability: experimental + diff --git a/model/http/spans.yaml b/model/http/spans.yaml index 79fa21f22f..b8167d1324 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -113,3 +113,5 @@ groups: requirement_level: opt_in - ref: http.response.body.size requirement_level: opt_in + - ref: http.request.synthetic + requirement_level: opt_in From 984fbee2db71ca2183e2146bab349dad7e0c1435 Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Tue, 29 Oct 2024 10:23:29 -0700 Subject: [PATCH 02/26] Update model/http/registry.yaml Co-authored-by: Trask Stalnaker --- model/http/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/http/registry.yaml b/model/http/registry.yaml index 44759d557f..5271e44b48 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -181,7 +181,7 @@ groups: members: - id: bot value: "bot" - brief: 'bot source.' + brief: 'Bot source.' stability: experimental - id: test value: "synthetic test" From 4d1b110f065b5ef1e2b4adc426f091720c33093e Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Tue, 29 Oct 2024 10:23:34 -0700 Subject: [PATCH 03/26] Update model/http/registry.yaml Co-authored-by: Trask Stalnaker --- model/http/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/http/registry.yaml b/model/http/registry.yaml index 5271e44b48..c5109bfb5a 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -185,6 +185,6 @@ groups: stability: experimental - id: test value: "synthetic test" - brief: 'synthetic test source.' + brief: 'Synthetic test source.' stability: experimental From f925b65daa6f7e853d1c59c947c5429c23c1f28c Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Wed, 30 Oct 2024 21:32:36 -0700 Subject: [PATCH 04/26] Begin refactoring. --- model/http/metrics.yaml | 2 +- model/http/registry.yaml | 18 ------------------ model/http/spans.yaml | 2 +- model/user-agent/registry.yaml | 17 +++++++++++++++++ 4 files changed, 19 insertions(+), 20 deletions(-) diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index fc35377228..fa4e3cb527 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -18,7 +18,7 @@ groups: > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. - - ref: http.request.synthetic + - ref: user_agent.synthetic requirement_level: opt_in - id: metric_attributes.http.client type: attribute_group diff --git a/model/http/registry.yaml b/model/http/registry.yaml index c5109bfb5a..ff0a002d39 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -170,21 +170,3 @@ groups: brief: State of the HTTP connection in the HTTP connection pool. stability: experimental examples: ["active", "idle"] - - id: http.request.synthetic - stability: experimental - brief: > - A flag indicating that the request was synthetically created and did not originate from genuine client traffic. - note: > - This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, - and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. - type: - members: - - id: bot - value: "bot" - brief: 'Bot source.' - stability: experimental - - id: test - value: "synthetic test" - brief: 'Synthetic test source.' - stability: experimental - diff --git a/model/http/spans.yaml b/model/http/spans.yaml index b8167d1324..cf4d98647a 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -113,5 +113,5 @@ groups: requirement_level: opt_in - ref: http.response.body.size requirement_level: opt_in - - ref: http.request.synthetic + - ref: user_agent.synthetic requirement_level: opt_in diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index 2b856ecdf5..74eeb4e4c0 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -35,3 +35,20 @@ groups: 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` + - id: user_agent.synthetic + stability: experimental + brief: > + A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. + note: > + This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, + and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + type: + members: + - id: bot + value: "bot" + brief: 'Bot source.' + stability: experimental + - id: test + value: "synthetic test" + brief: 'Synthetic test source.' + stability: experimental From 6b48773fcaa8645e9bb7727893d35edb7e48568c Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Wed, 30 Oct 2024 21:44:37 -0700 Subject: [PATCH 05/26] Update md files. --- docs/attributes-registry/http.md | 18 ++------ docs/attributes-registry/user-agent.md | 14 +++++- docs/http/http-metrics.md | 60 +++++++++++++------------- docs/http/http-spans.md | 28 ++++++------ 4 files changed, 60 insertions(+), 60 deletions(-) diff --git a/docs/attributes-registry/http.md b/docs/attributes-registry/http.md index dd0b538b08..57953b39be 100644 --- a/docs/attributes-registry/http.md +++ b/docs/attributes-registry/http.md @@ -22,12 +22,11 @@ This document defines semantic convention attributes in the HTTP namespace. | `http.request.method_original` | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `http.request.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `http.request.size` | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `http.request.synthetic` | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [4] | `bot`; `synthetic test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `http.response.body.size` | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [5] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `http.response.size` | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `http.route` | string | The matched route, that is, the path template in the format used by the respective server framework. [6] | `/users/:userID?`; `{controller}/{action}/{id?}` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `http.route` | string | The matched route, that is, the path template in the format used by the respective server framework. [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | **[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. @@ -50,13 +49,11 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[3]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). -**[4]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. - -**[5]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +**[4]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[6]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +**[5]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. `http.connection.state` 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. @@ -81,13 +78,6 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`http.request.synthetic` 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 | -|---|---|---| -| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ## Deprecated HTTP Attributes Describes deprecated HTTP attributes. diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 6afe7b8549..6c5d579e29 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -14,8 +14,18 @@ Describes user-agent attributes. |---|---|---|---|---| | `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name. [1] | `Safari`; `YourApp` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `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`; `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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user_agent.synthetic` | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [2] | `bot`; `synthetic test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [3] | `14.1.2`; `1.0.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[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]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +**[3]:** [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` + +`user_agent.synthetic` 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 | +|---|---|---| +| `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 9f7f05b0f2..94bfba3fd7 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -87,9 +87,9 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`http.request.synthetic`](/docs/attributes-registry/http.md) | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [8] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [10] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.synthetic`](/docs/attributes-registry/user-agent.md) | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [10] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -134,18 +134,18 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. - -**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. +**[10]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + `error.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 | @@ -167,12 +167,12 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`http.request.synthetic` 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. +`user_agent.synthetic` 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 | |---|---|---| -| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -272,9 +272,9 @@ This metric is optional. | [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`http.request.synthetic`](/docs/attributes-registry/http.md) | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [8] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [10] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.synthetic`](/docs/attributes-registry/user-agent.md) | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [10] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -319,18 +319,18 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. - -**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. +**[10]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + `error.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 | @@ -352,12 +352,12 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`http.request.synthetic` 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. +`user_agent.synthetic` 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 | |---|---|---| -| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -390,9 +390,9 @@ This metric is optional. | [`http.route`](/docs/attributes-registry/http.md) | string | The matched route, that is, the path template in the format used by the respective server framework. [4] | `/users/:userID?`; `{controller}/{action}/{id?}` | `Conditionally Required` If and only if it's available | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.name`](/docs/attributes-registry/network.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [5] | `http`; `spdy` | `Conditionally Required` [6] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`http.request.synthetic`](/docs/attributes-registry/http.md) | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [8] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [10] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.synthetic`](/docs/attributes-registry/user-agent.md) | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [10] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -437,18 +437,18 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin **[7]:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[8]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. - -**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[8]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). +**[9]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. +**[10]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + `error.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 | @@ -470,12 +470,12 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`http.request.synthetic` 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. +`user_agent.synthetic` 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 | |---|---|---| -| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index dda228b92b..024649fc18 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -378,13 +378,13 @@ For an HTTP server span, `SpanKind` MUST be `SERVER`. | [`http.request.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [15] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.request.size`](/docs/attributes-registry/http.md) | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`http.request.synthetic`](/docs/attributes-registry/http.md) | string | A flag indicating that the request was synthetically created and did not originate from genuine client traffic. [16] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.response.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [17] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [16] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.response.size`](/docs/attributes-registry/http.md) | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`network.local.address`](/docs/attributes-registry/network.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.local.port`](/docs/attributes-registry/network.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [18] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.synthetic`](/docs/attributes-registry/user-agent.md) | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [18] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -447,13 +447,13 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin 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. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[16]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. - -**[17]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +**[16]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[18]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. +**[17]:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. + +**[18]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): @@ -489,13 +489,6 @@ and SHOULD be provided **at span creation time** (if provided at all): | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`http.request.synthetic` 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 | -|---|---|---| -| `bot` | bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - `network.transport` 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 | @@ -506,6 +499,13 @@ and SHOULD be provided **at span creation time** (if provided at all): | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`user_agent.synthetic` 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 | +|---|---|---| +| `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + From 583710657a9e8608e847ee1605985ac1b95491cb Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Fri, 1 Nov 2024 10:04:02 -0700 Subject: [PATCH 06/26] Clarify synthetic meaning. Co-authored-by: Liudmila Molkova --- model/user-agent/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index 74eeb4e4c0..d71fe60b0c 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -38,7 +38,7 @@ groups: - id: user_agent.synthetic stability: experimental brief: > - A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. + Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. note: > This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. From b4686fffd1e5ba364d764eb7fc853751ee3d8ed1 Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Fri, 1 Nov 2024 10:05:15 -0700 Subject: [PATCH 07/26] Shorten id value. Co-authored-by: Liudmila Molkova --- model/user-agent/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index d71fe60b0c..e350ddd114 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -49,6 +49,6 @@ groups: brief: 'Bot source.' stability: experimental - id: test - value: "synthetic test" + value: "test" brief: 'Synthetic test source.' stability: experimental From 568cefca1d62efbafae487774e6a4eb1360d6f78 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Fri, 1 Nov 2024 10:06:20 -0700 Subject: [PATCH 08/26] Update user_agent synthetic value. --- .chloggen/add-synthetic-source.yaml | 4 ++-- model/http/metrics.yaml | 2 +- model/http/spans.yaml | 2 +- model/user-agent/registry.yaml | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.chloggen/add-synthetic-source.yaml b/.chloggen/add-synthetic-source.yaml index 081cfce0d5..51e41a4421 100644 --- a/.chloggen/add-synthetic-source.yaml +++ b/.chloggen/add-synthetic-source.yaml @@ -7,10 +7,10 @@ change_type: enhancement # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: http +component: user_agent # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). -note: Add the http.request.synthetic attribute to track if spans and metrics are the result of real users, synthetic testing, or bots. +note: Add the user_agent.synthetic.type attribute to track if spans and metrics are the result of real users, testing, or bots. # 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. diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index fa4e3cb527..90f74a7656 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -18,7 +18,7 @@ groups: > **Warning** > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. - - ref: user_agent.synthetic + - ref: user_agent.synthetic.type requirement_level: opt_in - id: metric_attributes.http.client type: attribute_group diff --git a/model/http/spans.yaml b/model/http/spans.yaml index cf4d98647a..720aaa03de 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -113,5 +113,5 @@ groups: requirement_level: opt_in - ref: http.response.body.size requirement_level: opt_in - - ref: user_agent.synthetic + - ref: user_agent.synthetic.type requirement_level: opt_in diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index 74eeb4e4c0..76f2047bb1 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -35,7 +35,7 @@ groups: 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` - - id: user_agent.synthetic + - id: user_agent.synthetic.type stability: experimental brief: > A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. From 40a7d3b346ab2317b1f10715bcaa78f2307985d8 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Fri, 1 Nov 2024 10:08:37 -0700 Subject: [PATCH 09/26] Update docs. --- docs/attributes-registry/user-agent.md | 6 +++--- docs/http/http-metrics.md | 18 +++++++++--------- docs/http/http-spans.md | 6 +++--- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 6c5d579e29..5bf0a5695a 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -14,7 +14,7 @@ Describes user-agent attributes. |---|---|---|---|---| | `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name. [1] | `Safari`; `YourApp` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `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`; `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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `user_agent.synthetic` | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [2] | `bot`; `synthetic test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user_agent.synthetic.type` | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [2] | `bot`; `test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [3] | `14.1.2`; `1.0.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[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` @@ -23,9 +23,9 @@ Describes user-agent attributes. **[3]:** [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` -`user_agent.synthetic` 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. +`user_agent.synthetic.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 | |---|---|---| | `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 94bfba3fd7..5f49ce1280 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -89,7 +89,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic`](/docs/attributes-registry/user-agent.md) | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [10] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -167,12 +167,12 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`user_agent.synthetic` 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. +`user_agent.synthetic.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 | |---|---|---| | `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -274,7 +274,7 @@ This metric is optional. | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic`](/docs/attributes-registry/user-agent.md) | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [10] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -352,12 +352,12 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`user_agent.synthetic` 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. +`user_agent.synthetic.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 | |---|---|---| | `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -392,7 +392,7 @@ This metric is optional. | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic`](/docs/attributes-registry/user-agent.md) | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [10] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -470,12 +470,12 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`user_agent.synthetic` 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. +`user_agent.synthetic.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 | |---|---|---| | `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 024649fc18..f6d1069e7c 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -384,7 +384,7 @@ For an HTTP server span, `SpanKind` MUST be `SERVER`. | [`network.local.address`](/docs/attributes-registry/network.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.local.port`](/docs/attributes-registry/network.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic`](/docs/attributes-registry/user-agent.md) | string | A flag indicating that the user agent represents a synthetic source and did not originate from genuine client traffic. [18] | `bot`; `synthetic test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [18] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -499,12 +499,12 @@ and SHOULD be provided **at span creation time** (if provided at all): | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -`user_agent.synthetic` 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. +`user_agent.synthetic.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 | |---|---|---| | `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `synthetic test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | From 48668f3f7780e2d1499da84c0bb2a5ddcda02cd5 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Mon, 18 Nov 2024 16:53:18 -0800 Subject: [PATCH 10/26] Add info regarding self-id. --- model/user-agent/registry.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index e0d9549737..c54fe86076 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -41,7 +41,8 @@ groups: Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. note: > This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, - and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result + of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. type: members: - id: bot From 91ef4ba5da5277cba50394117f6187a999687157 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Tue, 19 Nov 2024 11:20:14 -0800 Subject: [PATCH 11/26] Update md files. --- docs/attributes-registry/user-agent.md | 6 ++---- docs/http/http-metrics.md | 6 +++--- docs/http/http-spans.md | 2 +- 3 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 81074e1363..87ce27c59f 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -19,9 +19,9 @@ Describes user-agent attributes. **[1] `user_agent.name`:** [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]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[2] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. -**[3]:** [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` +**[3] `user_agent.version`:** [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` `user_agent.synthetic.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. @@ -29,5 +29,3 @@ Describes user-agent attributes. |---|---|---| | `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[2] `user_agent.version`:** [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` \ No newline at end of file diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index d39e409250..16b854ad2c 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -144,7 +144,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. @@ -329,7 +329,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. @@ -447,7 +447,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 62b2d7afda..ef651b1835 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -486,7 +486,7 @@ The attribute value MUST consist of either multiple header values as an array of **[17] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. -**[18]:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[18] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): From 2d64e9611fd31e87b9ce3a76a1b131960567c707 Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Tue, 19 Nov 2024 11:39:33 -0800 Subject: [PATCH 12/26] Generalize about what components could possibly set the synthetic attribute. Co-authored-by: Liudmila Molkova --- model/user-agent/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index c54fe86076..8766e02c46 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -40,7 +40,7 @@ groups: brief: > Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. note: > - This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, + This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. type: From ac73e9763f99951096f904398111af80bb35d285 Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Tue, 19 Nov 2024 13:46:23 -0800 Subject: [PATCH 13/26] Update description wording. --- model/user-agent/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index 8766e02c46..7926bce18e 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -41,7 +41,7 @@ groups: Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. note: > This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, - and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result + and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. type: members: From c87095726a0723cd14f8d8ce821399dcebe495cf Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Tue, 19 Nov 2024 13:57:40 -0800 Subject: [PATCH 14/26] Update docs and add synthetic to client spans. --- docs/attributes-registry/user-agent.md | 2 +- docs/http/http-metrics.md | 6 +++--- docs/http/http-spans.md | 12 +++++++++++- model/http/spans.yaml | 2 ++ 4 files changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 87ce27c59f..ec3d744cf6 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -19,7 +19,7 @@ Describes user-agent attributes. **[1] `user_agent.name`:** [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] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[2] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. **[3] `user_agent.version`:** [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/docs/http/http-metrics.md b/docs/http/http-metrics.md index 16b854ad2c..3e8a35b95b 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -144,7 +144,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. @@ -329,7 +329,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. @@ -447,7 +447,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index ef651b1835..40c46bc6e0 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -162,6 +162,7 @@ For an HTTP client span, `SpanKind` MUST be `CLIENT`. | [`url.scheme`](/docs/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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`url.template`](/docs/attributes-registry/url.md) | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). [14] | `/users/{id}`; `/users/:id`; `/users?id={id}` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`user_agent.original`](/docs/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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [15] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -245,6 +246,8 @@ The attribute value MUST consist of either multiple header values as an array of **[14] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation. +**[15] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): @@ -284,6 +287,13 @@ and SHOULD be provided **at span creation time** (if provided at all): | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +`user_agent.synthetic.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 | +|---|---|---| +| `bot` | Bot source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test` | Synthetic test source. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + @@ -486,7 +496,7 @@ The attribute value MUST consist of either multiple header values as an array of **[17] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. -**[18] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Instrumentations should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set on client spans for self-identification purposes, or on server spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[18] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/model/http/spans.yaml b/model/http/spans.yaml index 5b3aee6ece..86ee3154c4 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -45,6 +45,8 @@ groups: requirement_level: opt_in - ref: http.response.body.size requirement_level: opt_in + - ref: user_agent.synthetic.type + requirement_level: opt_in - id: span.http.server type: span From 7dac0c5a4dcbb7fe6591753d502c35817d6cfcbe Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Tue, 19 Nov 2024 14:28:42 -0800 Subject: [PATCH 15/26] Update wording on user-agent registry. --- docs/attributes-registry/user-agent.md | 2 +- docs/http/http-metrics.md | 6 +++--- docs/http/http-spans.md | 4 ++-- model/user-agent/registry.yaml | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index ec3d744cf6..825a8eca85 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -19,7 +19,7 @@ Describes user-agent attributes. **[1] `user_agent.name`:** [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] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[2] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. **[3] `user_agent.version`:** [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/docs/http/http-metrics.md b/docs/http/http-metrics.md index 3e8a35b95b..59b5b04262 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -144,7 +144,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. @@ -329,7 +329,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. @@ -447,7 +447,7 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. -**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[10] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. `error.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. diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 40c46bc6e0..0b5be8a9d2 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -246,7 +246,7 @@ The attribute value MUST consist of either multiple header values as an array of **[14] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation. -**[15] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[15] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): @@ -496,7 +496,7 @@ The attribute value MUST consist of either multiple header values as an array of **[17] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. -**[18] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[18] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index 7926bce18e..86bc134055 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -41,7 +41,7 @@ groups: Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. note: > This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, - and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on spans detected to be generated as a result + and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. type: members: From 1b804df258196107229547a63574ff1694280551 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Wed, 20 Nov 2024 16:09:06 -0800 Subject: [PATCH 16/26] Update requirement level of synthetic.type for client spans. --- model/http/spans.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/model/http/spans.yaml b/model/http/spans.yaml index 86ee3154c4..697c75ff07 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -46,7 +46,8 @@ groups: - ref: http.response.body.size requirement_level: opt_in - ref: user_agent.synthetic.type - requirement_level: opt_in + requirement_level: + conditionally recommendeed: When the client knows it is sending synthetic or bot traffic. - id: span.http.server type: span From 86f3396702c9b9e3769391d766ca4be046f6f495 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Wed, 20 Nov 2024 16:10:33 -0800 Subject: [PATCH 17/26] Update requirement level of client spans. --- docs/http/http-spans.md | 24 +++++++++++++----------- model/http/spans.yaml | 2 +- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 0b5be8a9d2..c49f292bbe 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -152,17 +152,17 @@ For an HTTP client span, `SpanKind` MUST be `CLIENT`. | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [10] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [11] | `bot`; `test` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.request.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [11] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [13] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.request.size`](/docs/attributes-registry/http.md) | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.response.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [12] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [14] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.response.size`](/docs/attributes-registry/http.md) | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [13] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [15] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`url.scheme`](/docs/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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`url.template`](/docs/attributes-registry/url.md) | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). [14] | `/users/{id}`; `/users/:id`; `/users?id={id}` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`url.template`](/docs/attributes-registry/url.md) | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). [16] | `/users/{id}`; `/users/:id`; `/users?id={id}` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`user_agent.original`](/docs/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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [15] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -234,19 +234,21 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro **[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[11] `http.request.header`:** 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. +**[11] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +**[12] `user_agent.synthetic.type`:** When the client knows it is sending synthetic or bot traffic. + +**[13] `http.request.header`:** 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. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[12] `http.response.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +**[14] `http.response.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[13] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. - -**[14] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation. +**[15] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. -**[15] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[16] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/model/http/spans.yaml b/model/http/spans.yaml index 697c75ff07..c5fbb68148 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -47,7 +47,7 @@ groups: requirement_level: opt_in - ref: user_agent.synthetic.type requirement_level: - conditionally recommendeed: When the client knows it is sending synthetic or bot traffic. + recommended: When the client knows it is sending synthetic or bot traffic. - id: span.http.server type: span From 03c8ea86435c441d5555e385c99a8381af71e81b Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:11:08 -0800 Subject: [PATCH 18/26] Specify the types of synthetic traffic possible. Co-authored-by: Trask Stalnaker --- .chloggen/add-synthetic-source.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/add-synthetic-source.yaml b/.chloggen/add-synthetic-source.yaml index 51e41a4421..30634834df 100644 --- a/.chloggen/add-synthetic-source.yaml +++ b/.chloggen/add-synthetic-source.yaml @@ -10,7 +10,7 @@ change_type: enhancement component: user_agent # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). -note: Add the user_agent.synthetic.type attribute to track if spans and metrics are the result of real users, testing, or bots. +note: Add the user_agent.synthetic.type attribute to specify the category of synthetic traffic, such as tests or bots. # 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. From 54dcdd397463ca5056ea340ef6fd98f5d2f47d95 Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:11:24 -0800 Subject: [PATCH 19/26] Make the enum values more clear. Co-authored-by: Trask Stalnaker --- model/user-agent/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index 86bc134055..4ce9ed73b8 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -38,7 +38,7 @@ groups: - id: user_agent.synthetic.type stability: experimental brief: > - Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. + Specifies the category of synthetic traffic, such as tests or bots. note: > This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result From a136fbdf2ae2413f92ee39134a9444188fcda747 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Wed, 20 Nov 2024 16:13:51 -0800 Subject: [PATCH 20/26] Update markdown. --- docs/attributes-registry/user-agent.md | 2 +- docs/http/http-metrics.md | 6 +++--- docs/http/http-spans.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 825a8eca85..0b53c22d97 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -14,7 +14,7 @@ Describes user-agent attributes. |---|---|---|---|---| | `user_agent.name` | string | Name of the user-agent extracted from original. Usually refers to the browser's name. [1] | `Safari`; `YourApp` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `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`; `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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `user_agent.synthetic.type` | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [2] | `bot`; `test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `user_agent.synthetic.type` | string | Specifies the category of synthetic traffic, such as tests or bots. [2] | `bot`; `test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `user_agent.version` | string | Version of the user-agent extracted from original. Usually refers to the browser's version [3] | `14.1.2`; `1.0.0` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `user_agent.name`:** [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` diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 59b5b04262..43089208c1 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -89,7 +89,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -274,7 +274,7 @@ This metric is optional. | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -392,7 +392,7 @@ This metric is optional. | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [7] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.address`](/docs/attributes-registry/server.md) | string | Name of the local HTTP server that received the request. [8] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`server.port`](/docs/attributes-registry/server.md) | int | Port of the local HTTP server that received the request. [9] | `80`; `8080`; `443` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [10] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index c49f292bbe..f4c9357d52 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -152,7 +152,7 @@ For an HTTP client span, `SpanKind` MUST be `CLIENT`. | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [10] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [11] | `bot`; `test` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [11] | `bot`; `test` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.request.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [13] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.request.size`](/docs/attributes-registry/http.md) | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -416,7 +416,7 @@ For an HTTP server span, `SpanKind` MUST be `SERVER`. | [`network.local.address`](/docs/attributes-registry/network.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.local.port`](/docs/attributes-registry/network.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [17] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as monitoring, crawler, bot, or another automation. [18] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [18] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) From 48cca0b341af51b73f69074fff6d91b5b5f2db7e Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:34:58 -0800 Subject: [PATCH 21/26] Add formatting. Co-authored-by: Trask Stalnaker --- .chloggen/add-synthetic-source.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/add-synthetic-source.yaml b/.chloggen/add-synthetic-source.yaml index 30634834df..4eb9ccea8a 100644 --- a/.chloggen/add-synthetic-source.yaml +++ b/.chloggen/add-synthetic-source.yaml @@ -10,7 +10,7 @@ change_type: enhancement component: user_agent # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). -note: Add the user_agent.synthetic.type attribute to specify the category of synthetic traffic, such as tests or bots. +note: Add the `user_agent.synthetic.type` attribute to specify the category of synthetic traffic, such as tests or bots. # 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. From 8ce8320638d17730f4b8bad6c9d7d6e8164c222b Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:35:49 -0800 Subject: [PATCH 22/26] Wording update. Co-authored-by: Trask Stalnaker --- model/http/spans.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/http/spans.yaml b/model/http/spans.yaml index c5fbb68148..b618df0de1 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -47,7 +47,7 @@ groups: requirement_level: opt_in - ref: user_agent.synthetic.type requirement_level: - recommended: When the client knows it is sending synthetic or bot traffic. + recommended: When the client knows it is sending synthetic traffic, such as tests or bots. - id: span.http.server type: span From 101e662a353d7d1d19acbdf58df6de805e602da8 Mon Sep 17 00:00:00 2001 From: Jackson Weber <47067795+JacksonWeber@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:37:22 -0800 Subject: [PATCH 23/26] Update should vs. may wording. Co-authored-by: Trask Stalnaker --- model/user-agent/registry.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/model/user-agent/registry.yaml b/model/user-agent/registry.yaml index 4ce9ed73b8..369aad35cd 100644 --- a/model/user-agent/registry.yaml +++ b/model/user-agent/registry.yaml @@ -40,8 +40,9 @@ groups: brief: > Specifies the category of synthetic traffic, such as tests or bots. note: > - This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, - and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result + This attribute MAY be derived from the contents of the `user_agent.original` attribute. + Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. + This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. type: members: From 87e6c4e6aaded133b50f67a2b36870ba7a1760d1 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Thu, 21 Nov 2024 11:40:01 -0800 Subject: [PATCH 24/26] Update markdown. --- docs/attributes-registry/user-agent.md | 4 +++- docs/http/http-metrics.md | 18 ++++++++++++++++++ docs/http/http-spans.md | 10 +++++++--- 3 files changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/attributes-registry/user-agent.md b/docs/attributes-registry/user-agent.md index 0b53c22d97..3952005cd9 100644 --- a/docs/attributes-registry/user-agent.md +++ b/docs/attributes-registry/user-agent.md @@ -19,10 +19,12 @@ Describes user-agent attributes. **[1] `user_agent.name`:** [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] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[2] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. **[3] `user_agent.version`:** [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` +--- + `user_agent.synthetic.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 | diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 7d8b8a730f..a5136e6d5e 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -144,6 +144,10 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. +**[10] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +--- + `error.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 | @@ -167,6 +171,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + `user_agent.synthetic.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 | @@ -331,6 +337,10 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. +**[10] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +--- + `error.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 | @@ -354,6 +364,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + `user_agent.synthetic.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 | @@ -449,6 +461,10 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. +**[10] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. + +--- + `error.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 | @@ -472,6 +488,8 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin | `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + `user_agent.synthetic.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 | diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index bd0135a703..e340aff2f7 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -234,9 +234,9 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro **[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[11] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[11] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. -**[12] `user_agent.synthetic.type`:** When the client knows it is sending synthetic or bot traffic. +**[12] `user_agent.synthetic.type`:** When the client knows it is sending synthetic traffic, such as tests or bots. **[13] `http.request.header`:** 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. @@ -295,6 +295,8 @@ and SHOULD be provided **at span creation time** (if provided at all): | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + `user_agent.synthetic.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 | @@ -504,7 +506,7 @@ The attribute value MUST consist of either multiple header values as an array of **[17] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. -**[18] `user_agent.synthetic.type`:** This flag can primarily be determined by the contents of the `user_agent.original` attribute. Components that populate the attribute should determine what they consider synthetic or bot traffic, and set this attribute accordingly. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. +**[18] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): @@ -556,6 +558,8 @@ and SHOULD be provided **at span creation time** (if provided at all): | `udp` | UDP | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | `unix` | Unix domain socket | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +--- + `user_agent.synthetic.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 | From 25cc8f44a14f9421e73e26bb9b942983ecb73c8b Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Thu, 21 Nov 2024 14:12:03 -0800 Subject: [PATCH 25/26] Add new line. --- .chloggen/add-synthetic-source.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/add-synthetic-source.yaml b/.chloggen/add-synthetic-source.yaml index 4eb9ccea8a..935eb5529e 100644 --- a/.chloggen/add-synthetic-source.yaml +++ b/.chloggen/add-synthetic-source.yaml @@ -19,4 +19,4 @@ issues: [1127] # (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: \ No newline at end of file +subtext: From 6c21f04ab5723bfdfec8351bd09652d15b17d7c0 Mon Sep 17 00:00:00 2001 From: Jackson Weber Date: Thu, 21 Nov 2024 14:51:33 -0800 Subject: [PATCH 26/26] Update attribute on client spans to opt_in. --- docs/http/http-spans.md | 24 +++++++++++------------- model/http/spans.yaml | 3 +-- 2 files changed, 12 insertions(+), 15 deletions(-) diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index e340aff2f7..37781049ea 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -152,17 +152,17 @@ For an HTTP client span, `SpanKind` MUST be `CLIENT`. | [`network.peer.address`](/docs/attributes-registry/network.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.peer.port`](/docs/attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | `Recommended` If `network.peer.address` is set. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`network.protocol.version`](/docs/attributes-registry/network.md) | string | The actual version of the protocol used for network communication. [10] | `1.0`; `1.1`; `2`; `3` | `Recommended` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [11] | `bot`; `test` | `Recommended` [12] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.request.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [13] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.request.header.`](/docs/attributes-registry/http.md) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [11] | `http.request.header.content-type=["application/json"]`; `http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.request.size`](/docs/attributes-registry/http.md) | int | The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and request body if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`http.response.body.size`](/docs/attributes-registry/http.md) | 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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [14] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`http.response.header.`](/docs/attributes-registry/http.md) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [12] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`http.response.size`](/docs/attributes-registry/http.md) | int | The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1), framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any. | `1437` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [15] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`network.transport`](/docs/attributes-registry/network.md) | string | [OSI transport layer](https://wikipedia.org/wiki/Transport_layer) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [13] | `tcp`; `udp` | `Opt-In` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`url.scheme`](/docs/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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| [`url.template`](/docs/attributes-registry/url.md) | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). [16] | `/users/{id}`; `/users/:id`; `/users?id={id}` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`url.template`](/docs/attributes-registry/url.md) | string | The low-cardinality template of an [absolute path reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2). [14] | `/users/{id}`; `/users/:id`; `/users?id={id}` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`user_agent.original`](/docs/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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`user_agent.synthetic.type`](/docs/attributes-registry/user-agent.md) | string | Specifies the category of synthetic traffic, such as tests or bots. [15] | `bot`; `test` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `http.request.method`:** HTTP request method value SHOULD be "known" to the instrumentation. By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods) @@ -234,21 +234,19 @@ If the request has completed successfully, instrumentations SHOULD NOT set `erro **[10] `network.protocol.version`:** If protocol version is subject to negotiation (for example using [ALPN](https://www.rfc-editor.org/rfc/rfc7301.html)), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set. -**[11] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. - -**[12] `user_agent.synthetic.type`:** When the client knows it is sending synthetic traffic, such as tests or bots. - -**[13] `http.request.header`:** 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. +**[11] `http.request.header`:** 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. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[14] `http.response.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. +**[12] `http.response.header`:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -**[15] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. +**[13] `network.transport`:** Generally `tcp` for `HTTP/1.0`, `HTTP/1.1`, and `HTTP/2`. Generally `udp` for `HTTP/3`. Other obscure implementations are possible. + +**[14] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation. -**[16] `url.template`:** The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation. +**[15] `user_agent.synthetic.type`:** This attribute MAY be derived from the contents of the `user_agent.original` attribute. Components that populate the attribute are responsible for determining what they consider to be synthetic bot or test traffic. This attribute can either be set for self-identification purposes, or on telemetry detected to be generated as a result of a synthetic request. This attribute is useful for distinguishing between genuine client traffic and synthetic traffic generated by bots or tests. The following attributes can be important for making sampling decisions and SHOULD be provided **at span creation time** (if provided at all): diff --git a/model/http/spans.yaml b/model/http/spans.yaml index b618df0de1..86ee3154c4 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -46,8 +46,7 @@ groups: - ref: http.response.body.size requirement_level: opt_in - ref: user_agent.synthetic.type - requirement_level: - recommended: When the client knows it is sending synthetic traffic, such as tests or bots. + requirement_level: opt_in - id: span.http.server type: span