open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove alternative attribute sets from HTTP semantic conventions (#2469)

This commit is contained in:
Liudmila Molkova 2022-07-27 11:31:21 -07:00 committed by GitHub
parent 6a3df0d52d
commit 298c566cf9
8 changed files with 184 additions and 234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
semantic_conventions/trace/general.yaml
View File

@ -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

173
semantic_conventions/trace/http.yaml
View File

@ -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]

69
specification/metrics/semantic_conventions/http-metrics.md
View File

@ -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. <https://github.com/open-telemetry/opentelemetry-python/pull/148>).
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`

2
specification/trace/semantic_conventions/database.md
View File

@ -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.

154
specification/trace/semantic_conventions/http.md
View File

@ -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] |
| [`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] |
**[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/`.
**[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.
**[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.
**[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.
**[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.
**[3]:** If available and different from `net.peer.name` 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.
**[5]:** If available and different than `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`
<!-- endsemconv -->
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.
<!-- semconv http.client -->
| 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)
<!-- endsemconv -->
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.
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`.
### 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 server
@ -243,15 +229,16 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
<!-- semconv http.server -->
| 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)
<!-- endsemconv -->
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:

2
specification/trace/semantic_conventions/messaging.md
View File

@ -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.

4
specification/trace/semantic_conventions/rpc.md
View File

@ -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.
<!-- endsemconv -->

6
specification/trace/semantic_conventions/span-general.md
View File

@ -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.