diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index fe14538747..fd800b973e 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -44,7 +44,7 @@ groups: type: string brief: Remote socket peer name. requirement_level: - recommended: If available and different than `net.peer.name` and if `net.sock.peer.addr` is set. + recommended: If available and different from `net.peer.name` and if `net.sock.peer.addr` is set. examples: proxy.example.com - id: sock.peer.addr type: string @@ -74,8 +74,8 @@ groups: requirement_level: conditionally_required: > If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. - Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` - without `net.sock.family` coming from instrumentations that follow previous versions + Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` + if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. brief: > Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. @@ -100,7 +100,7 @@ groups: examples: 8080 - id: sock.host.addr type: string - brief: Local socket address. Useful in case of a multi-IP host.' + brief: Local socket address. Useful in case of a multi-IP host. examples: '192.168.0.1' - id: sock.host.port type: int diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index f4626b1203..0f38daaf17 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -13,39 +13,6 @@ groups: brief: 'HTTP request method.' sampling_relevant: true examples: ["GET", "POST", "HEAD"] - - id: url - type: string - brief: > - Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. - Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. - note: > - `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. - In such case the attribute's value should be `https://www.example.com/`. - sampling_relevant: true - examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] - - id: target - type: string - brief: 'The full request target as passed in a HTTP request line or equivalent.' - sampling_relevant: true - examples: ['/path/12314/?q=ddds#123'] - - id: host - type: string - brief: > - The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). - An empty Host header should also be reported, see note. - note: > - When the header is present but empty the attribute SHOULD be set to - the empty string. Note that this is a valid situation that is expected - in certain cases, according the aforementioned - [section of RFC 7230](https://tools.ietf.org/html/rfc7230#section-5.4). - When the header is not set the attribute MUST NOT be set. - sampling_relevant: true - examples: ['www.example.org'] - - id: scheme - type: string - brief: 'The URI scheme identifying the used protocol.' - sampling_relevant: true - examples: ["http", "https"] - id: status_code type: int requirement_level: @@ -82,44 +49,27 @@ groups: is `QUIC`, in which case `IP.UDP` is assumed. - id: user_agent type: string - brief: 'Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client.' + brief: 'Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client.' examples: ['CERN-LineMode/2.15 libwww/2.17b3'] - id: request_content_length type: int brief: > 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://tools.ietf.org/html/rfc7230#section-3.3.2) + 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. examples: 3495 - - id: request_content_length_uncompressed - type: int - brief: > - The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. - examples: 5493 - id: response_content_length type: int brief: > 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://tools.ietf.org/html/rfc7230#section-3.3.2) + 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. examples: 3495 - - id: response_content_length_uncompressed - type: int - brief: > - The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. - examples: 5493 - - id: retry_count - type: int - brief: > - The ordinal number of request re-sending attempt. - requirement_level: - recommended: If and only if a request was retried. - examples: 3 - ref: net.sock.peer.addr - ref: net.sock.peer.port - ref: net.sock.peer.name - ref: net.sock.family - + examples: ['inet', 'inet6'] constraints: - include: network @@ -130,31 +80,47 @@ groups: span_kind: client brief: 'Semantic Convention for HTTP Client' attributes: + - id: url + type: string + requirement_level: required + brief: > + Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. + Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. + note: > + `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. + In such case the attribute's value should be `https://www.example.com/`. + sampling_relevant: true + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] - ref: net.peer.name + requirement_level: required sampling_relevant: true brief: > - Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. - note: > - When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set - `net.peer.name` to the provided host component. - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` SHOULD match - URI host component, otherwise `Host` header host component SHOULD be used. + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: | + Determined by using the first of the following that applies + + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form + - Host identifier of the `Host` header + + SHOULD NOT be set if capturing it would require an extra DNS lookup. - ref: net.peer.port sampling_relevant: true requirement_level: - conditionally_required: if not default for request scheme. + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). brief: > - Port identifier of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. note: > When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match - URI port component, otherwise it MUST match `Host` header port component. + URI port identifier, otherwise it MUST match `Host` header port identifier. + - id: retry_count + type: int + brief: > + The ordinal number of request re-sending attempt. + requirement_level: + recommended: if and only if request was retried. + examples: 3 - constraints: - - any_of: - - [http.url] - - [http.scheme, http.host, http.target] - - [http.scheme, net.peer.name, net.peer.port, http.target] - - [http.scheme, net.sock.peer.addr, net.sock.peer.port, http.target] - id: http.server prefix: http type: span @@ -162,21 +128,27 @@ groups: span_kind: server brief: 'Semantic Convention for HTTP Server' attributes: - - id: server_name + - id: scheme type: string - brief: > - The primary server name of the matched virtual host. This should be obtained via configuration. - If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). - note: > - `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and - sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). - It is thus preferred to supply the raw data that is available. - examples: ['example.com'] + brief: 'The URI scheme identifying the used protocol.' + requirement_level: required + sampling_relevant: true + examples: ["http", "https"] + - id: target + type: string + brief: 'The full request target as passed in a HTTP request line or equivalent.' + requirement_level: required + sampling_relevant: true + examples: ['/path/12314/?q=ddds'] - id: route type: string + requirement_level: + conditionally_required: If and only if it's available brief: > - The matched route (path template). - examples: '/users/:userID?' + The matched route (path template in the format used by the respective server framework). See note below + examples: ['/users/:userID?', '{controller}/{action}/{id?}'] + note: > + 'http.route' 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. - id: client_ip type: string brief: > @@ -196,26 +168,35 @@ groups: the closest proxy. examples: '83.164.160.102' - ref: net.host.name + requirement_level: required sampling_relevant: true brief: > - Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. - note: > - When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set - `net.host.name` to the IP address provided in the host component. - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.name` SHOULD match - URI host component, otherwise `Host` header host component SHOULD be used. + Name of the local HTTP server that received the request. + note: | + Determined by using the first of the following that applies + + - The [primary server name](#http-server-definitions) of the matched virtual host. MUST only + include host identifier. + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. + - Host identifier of the `Host` header + + SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. + - ref: net.host.port sampling_relevant: true + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). brief: > - Port component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.port` SHOULD match - URI port component, otherwise `Host` header port component SHOULD be used. + Port of the local HTTP server that received the request. + note: | + Determined by using the first of the following that applies + + - Port identifier of the [primary server host](#http-server-definitions) of the matched virtual host. + - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. + - Port identifier of the `Host` header + - ref: net.sock.host.addr + requirement_level: optional - ref: net.sock.host.port - constraints: - - any_of: - - [http.scheme, http.host, http.target] - - [http.scheme, http.server_name, net.host.port, http.target] - - [http.scheme, net.host.name, net.host.port, http.target] - - [http.url] diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index e8008e8b97..f9c9d8a655 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -44,43 +44,40 @@ Below is a table of the attributes that SHOULD be included on `duration` and `si and whether they should be on server, client, or both types of HTTP metric events: | Name | Type | Requirement Level | Notes and examples | -|--------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `http.method` | `client` & `server` | Required | The HTTP request method. E.g. `"GET"` | -| `http.host` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same. | -| `http.scheme` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | -| `http.status_code` | `client` & `server` | Conditionally required | [HTTP response status code][]. E.g. `200` (String) | -| `http.flavor` | `client` & `server` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | -| `net.peer.name` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.peer.port` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.sock.peer.addr` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `http.server_name` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | -| `net.host.name` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.host.port` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +|----------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `http.method` | `client` & `server` | Required | The HTTP request method. E.g. `"GET"` | +| `http.scheme` | `server` | Required | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | +| `http.status_code` | `client` & `server` | Conditionally Required: if and only if one was received/sent. | [HTTP response status code][]. E.g. `200` (String) | +| `http.flavor` | `client` & `server` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | +| `net.peer.name` | `client` | Required | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | +| `net.peer.port` | `client` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | +| `net.sock.peer.addr` | `client` | Recommended | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.host.name` | `server` | Required | Host of the local HTTP server that received the request. | +| `net.host.port` | `server` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port of the local HTTP server that received the request. | The following attributes SHOULD be included in the `http.server.active_requests` observation: -| Name | Requirement Level | Notes and examples | -|--------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `http.method` | Required | The HTTP request method. E.g. `"GET"` | -| `http.host` | see [attribute alternatives](#attribute-alternatives) | The value of the [HTTP host header][]. When the header is empty or not present, this attribute should be the same | -| `http.scheme` | see [attribute alternatives](#attribute-alternatives) | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | -| `http.flavor` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"` | -| `http.server_name` | see [2] in [attribute alternatives](#attribute-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | +| Name | Requirement Level | Notes and examples | +|--------------------|-------------------|----------------------------------------------------------------------------------| +| `http.method` | Required | The HTTP request method. E.g. `"GET"` | +| `http.scheme` | Required | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` | +| `http.flavor` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"` | +| `net.host.name` | Required | Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. | -[HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4 -[HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 -[HTTP reason phrase]: https://tools.ietf.org/html/rfc7230#section-3.1.2 +[HTTP host header]: https://www.rfc-editor.org/rfc/rfc9110.html#name-host-and-authority +[HTTP response status code]: https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes +[HTTP reason phrase]: https://www.rfc-editor.org/rfc/rfc9110.html#section-15.1 ### Parameterized attributes To avoid high cardinality the following attributes SHOULD substitute any parameters when added as attributes to http metric events as described below: -| Attribute name | Type | Requirement Level | Notes and examples | -|----------------|---------------------|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------| -| `http.url` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The originally requested URL | -| `http.target` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The full request target as passed in a [HTTP request line][] or equivalent, e.g. `"/path/{id}/?q={}"`. | +| Attribute name | Type | Requirement Level | Notes and examples | +|----------------|---------|-------------------|--------------------------------------------------------------------------------------------------------| +| `http.url` | `client` | Required | The originally requested URL | +| `http.target` | `server` | Required | The full request target as passed in a [HTTP request target][] or equivalent, e.g. `"/path/{id}/?q={}"`. | -[HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1 +[Http request target]: https://www.rfc-editor.org/rfc/rfc9110.html#name-determining-the-target-reso Many REST APIs encode parameters into the URI path, e.g. `/api/users/123` where `123` is a user id, which creates high cardinality value space not suitable for attributes on metric events. @@ -93,21 +90,3 @@ are formed. Therefore, HTTP client attributes SHOULD be using conservative, low cardinality names formed from the available parameters of an HTTP request, such as `"HTTP {METHOD_NAME}"`. These attributes MUST NOT default to using URI path. - -### Attribute alternatives - -**[1]** For client metric attributes, one of the following sets of attributes is RECOMMENDED (in order of usual preference unless for a particular web client/framework it is known that some other set is preferable for some reason; all strings must be non-empty): - -* `http.url` -* `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target` -* `http.scheme`, `net.sock.peer.addr`, `net.sock.peer.port`, `http.target` - -**[2]** For server metric attributes, `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. ). -It is thus preferred to supply the raw data that _is_ available. -Namely, one of the following sets is RECOMMENDED (in order of usual preference unless for a particular web server/framework it is known that some other set is preferable for some reason; all strings must be non-empty): - -* `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `http.server_name`, `net.host.port`, `http.target` -* `http.scheme`, `net.host.name`, `net.host.port`, `http.target` -* `http.url` diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 0ded661e66..23358a56e0 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -53,7 +53,7 @@ Some database systems may allow a connection to switch to a different `db.user`, **[2]:** If using a port other than the default port for this DBMS and if `net.peer.name` is set. -**[3]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. +**[3]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. **[4]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 0466acef3a..a9b4240834 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -14,8 +14,8 @@ and various HTTP versions like 1.1, 2 and SPDY. - [Status](#status) - [Common Attributes](#common-attributes) * [HTTP request and response headers](#http-request-and-response-headers) - * [HTTP request retries and redirects](#http-request-retries-and-redirects) - [HTTP client](#http-client) + * [HTTP request retries and redirects](#http-request-retries-and-redirects) - [HTTP server](#http-server) * [HTTP server definitions](#http-server-definitions) * [HTTP Server semantic conventions](#http-server-semantic-conventions) @@ -62,34 +62,23 @@ Don't set the span status description if the reason can be inferred from `http.s | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Recommended | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds#123` | Recommended | -| `http.host` | string | The value of the [HTTP host header](https://tools.ietf.org/html/rfc7230#section-5.4). An empty Host header should also be reported, see note. [2] | `www.example.org` | Recommended | -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Recommended | | `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | -| `http.flavor` | string | Kind of HTTP protocol used. [3] | `1.0` | Recommended | -| `http.user_agent` | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | -| `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.request_content_length_uncompressed` | int | The size of the uncompressed request payload body after transport decoding. Not set if transport encoding not used. | `5493` | Recommended | -| `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | -| `http.response_content_length_uncompressed` | int | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | Recommended | -| `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: If and only if a request was retried. | -| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [4] | +| `http.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | +| `http.user_agent` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | +| `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | +| `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | +| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet`; `inet6` | Conditionally Required: [2] | | [`net.sock.peer.addr`](span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [5] | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [6] | - -**[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`. - -**[2]:** When the header is present but empty the attribute SHOULD be set to the empty string. Note that this is a valid situation that is expected in certain cases, according the aforementioned [section of RFC 7230](https://tools.ietf.org/html/rfc7230#section-5.4). When the header is not set the attribute MUST NOT be set. +| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [3] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [4] | -**[3]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. +**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. -**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. +**[2]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. -**[5]:** If available and different than `net.peer.name` and if `net.sock.peer.addr` is set. +**[3]:** If available and different from `net.peer.name` and if `net.sock.peer.addr` is set. -**[6]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. +**[4]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. `http.flavor` 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. @@ -105,14 +94,12 @@ Don't set the span status description if the reason can be inferred from `http.s Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: * `http.method` -* `http.url` -* `http.target` -* `http.host` -* `http.scheme` It is recommended to also use the general [socket-level attributes][] - `net.sock.peer.addr` when available, `net.sock.peer.name` and `net.sock.peer.port` when don't match `net.peer.name` and `net.peer.port` (if [intermediary](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.7) is detected). +[socket-level attributes]: span-general.md#netsock-attributes + ### HTTP request and response headers | Attribute | Type | Description | Examples | Requirement Level | @@ -123,24 +110,11 @@ It is recommended to also use the general [socket-level attributes][] - `net.soc **[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request/response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. -Some HTTP headers - `Host` and `User-Agent` - are already captured in the `http.host` and `http.user_agent` attributes. +The `User-Agent` header is already captured in the `http.user_agent` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended. **[2]:** 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. -[socket-level attributes]: span-general.md#netsock-attributes - -### HTTP request retries and redirects - -Retries and redirects cause more than one physical HTTP request to be sent. -A CLIENT span SHOULD be created for each one of these physical requests. -No span is created corresponding to the "logical" (encompassing) request. - -For retries, `http.retry_count` attribute SHOULD be added to each retry span -with the value that reflects the ordinal number of request retry attempt. - -See [examples](#http-retries-examples) for more details. - ## HTTP client This span type represents an outbound HTTP request. @@ -153,32 +127,44 @@ before any HTTP-redirects that may happen when executing the request. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`net.peer.name`](span-general.md) | string | Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [1] | `example.com` | See below | -| [`net.peer.port`](span-general.md) | int | Port identifier of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [2] | `80`; `8080`; `443` | Conditionally Required: if not default for request scheme. | +| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Required | +| `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: if and only if request was retried. | +| [`net.peer.name`](span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | +| [`net.peer.port`](span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -**[1]:** When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `net.peer.name` to the provided host component. When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` SHOULD match URI host component, otherwise `Host` header host component SHOULD be used. +**[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`. -**[2]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port component, otherwise it MUST match `Host` header port component. +**[2]:** Determined by using the first of the following that applies -**Additional attribute requirements:** At least one of the following sets of attributes is required: +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form +- Host identifier of the `Host` header -* `http.url` -* `http.scheme`, `http.host`, `http.target` -* `http.scheme`, [`net.peer.name`](span-general.md), [`net.peer.port`](span-general.md), `http.target` -* `http.scheme`, [`net.sock.peer.addr`](span-general.md), [`net.sock.peer.port`](span-general.md), `http.target` +SHOULD NOT be set if capturing it would require an extra DNS lookup. + +**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. + +**[4]:** If not default (`80` for `http` scheme, `443` for `https`). Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: +* `http.url` * [`net.peer.name`](span-general.md) * [`net.peer.port`](span-general.md) -It is recommended to also use the general [socket-level attributes][] - `net.sock.host.addr` when available, `net.sock.host.port` when it doesn't match `net.host.port` (if [intermediary](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.7) is detected). +Note that in some cases host and port identifiers in the `Host` header might be different from the `net.peer.name` and `net.peer.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. + +### HTTP request retries and redirects + +Retries and redirects cause more than one physical HTTP request to be sent. +A CLIENT span SHOULD be created for each one of these physical requests. +No span is created corresponding to the "logical" (encompassing) request. + +For retries, `http.retry_count` attribute SHOULD be added to each retry span +with the value that reflects the ordinal number of request retry attempt. -Note that in some cases `http.host` might be different -from the `net.peer.name` -used to look up the `net.sock.peer.addr` that is actually connected to. -In that case it is strongly recommended to set the `net.peer.name` attribute in addition to `http.host`. +See [examples](#http-retries-examples) for more details. ## HTTP server @@ -243,15 +229,16 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.server_name` | string | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). [1] | `example.com` | See below | -| `http.route` | string | The matched route (path template). | `/users/:userID?` | Recommended | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds` | Required | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | Recommended | -| [`net.host.name`](span-general.md) | string | Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [3] | `localhost` | See below | -| [`net.host.port`](span-general.md) | int | Port component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [4] | `8080` | See below | -| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | -| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [5] | +| [`net.host.name`](span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | +| [`net.host.port`](span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | +| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Optional | +| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [6] | -**[1]:** `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available. +**[1]:** 'http.route' 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. **[2]:** This is not necessarily the same as `net.sock.peer.addr`, which would identify the network-level peer, which may be a proxy. @@ -265,29 +252,38 @@ comes from a proxy, reverse proxy, or the actual client. Setting one is at least somewhat confident that the address is not that of the closest proxy. -**[3]:** When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `net.host.name` to the IP address provided in the host component. When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.name` SHOULD match URI host component, otherwise `Host` header host component SHOULD be used. +**[3]:** Determined by using the first of the following that applies -**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.port` SHOULD match URI port component, otherwise `Host` header port component SHOULD be used. +- The [primary server name](#http-server-definitions) of the matched virtual host. MUST only + include host identifier. +- Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. +- Host identifier of the `Host` header -**[5]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. +SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**Additional attribute requirements:** At least one of the following sets of attributes is required: +**[4]:** Determined by using the first of the following that applies -* `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `http.server_name`, [`net.host.port`](span-general.md), `http.target` -* `http.scheme`, [`net.host.name`](span-general.md), [`net.host.port`](span-general.md), `http.target` -* `http.url` +- Port identifier of the [primary server host](#http-server-definitions) of the matched virtual host. +- Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. +- Port identifier of the `Host` header + +**[5]:** If not default (`80` for `http` scheme, `443` for `https`). + +**[6]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: +* `http.scheme` +* `http.target` * [`net.host.name`](span-general.md) * [`net.host.port`](span-general.md) -Of course, more than the required attributes can be supplied, but this is recommended only if they cannot be inferred from the sent ones. -For example, `http.server_name` has shown great value in practice, as bogus HTTP Host headers occur often in the wild. +`http.route` MUST be provided at span creation time if and only if it's already available. If it becomes available after span starts, instrumentation MUST populate it anytime before span ends. -It is strongly recommended to set `http.server_name` to allow associating requests with some logical server entity. +Note that in some cases host and port identifiers in the `Host` header might be different from the `net.host.name` and `net.host.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. ## HTTP client-server example @@ -300,6 +296,8 @@ Span name: `HTTP GET` | `http.method` | `"GET"` | | `http.flavor` | `"1.1"` | | `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` | +| `net.peer.name` | `example.com` | +| `net.peer.port` | 8080 | | `net.sock.peer.addr` | `"192.0.2.5"` | | `http.status_code` | `200` | @@ -312,8 +310,7 @@ Span name: `/webshop/articles/:article_id`. | `http.method` | `"GET"` | | `http.flavor` | `"1.1"` | | `http.target` | `"/webshop/articles/4?s=1"` | -| `http.host` | `"example.com:8080"` | -| `http.server_name` | `"example.com"` | +| `net.host.name` | `"example.com"` | | `net.host.port` | `8080` | | `http.scheme` | `"https"` | | `http.route` | `"/webshop/articles/:article_id"` | @@ -322,13 +319,6 @@ Span name: `/webshop/articles/:article_id`. | `net.sock.peer.addr` | `"192.0.2.5"` (the client goes through a proxy) | | `http.user_agent` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | -Note that following the recommendations above, `http.url` is not set in the above example. -If set, it would be -`"https://example.com:8080/webshop/articles/4?s=1"` -but due to `http.scheme`, `http.host` and `http.target` being set, it would be redundant. -As explained above, these separate values are preferred but if for some reason the URL is available but the other values are not, -URL can replace `http.scheme`, `http.host` and `http.target`. - ## HTTP retries examples Example of retries in the presence of a trace started by an inbound request: diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 36d8f2aedf..831165d985 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -151,7 +151,7 @@ The following operations related to messages are defined for these semantic conv **[3]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. -**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. +**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. **[5]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set. diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 8a8ead9be1..d800f0c5b5 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -120,10 +120,10 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service |---|---|---|---|---| | [`net.host.name`](span-general.md) | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | | [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [1] | -| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | +| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended | | [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [2] | -**[1]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. +**[1]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. **[2]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 84d561b8c1..c0051a2f1a 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -51,7 +51,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.peer.port` | int | Logical remote port number | `80`; `8080`; `443` | Recommended | | `net.host.name` | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | | `net.host.port` | int | Logical local port number, preferably the one that the peer used to connect | `8080` | Recommended | -| `net.sock.host.addr` | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | +| `net.sock.host.addr` | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended | | `net.sock.host.port` | int | Local socket port number. | `35555` | Recommended: [6] | | `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended | | `net.host.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` | Recommended | @@ -62,11 +62,11 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[1]:** `net.app.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. -**[2]:** If available and different than `net.peer.name` and if `net.sock.peer.addr` is set. +**[2]:** If available and different from `net.peer.name` and if `net.sock.peer.addr` is set. **[3]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. -**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. +**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. **[5]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup.