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 type: string
brief: Remote socket peer name. brief: Remote socket peer name.
requirement_level: 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 examples: proxy.example.com
- id: sock.peer.addr - id: sock.peer.addr
type: string type: string
@ -74,8 +74,8 @@ groups:
requirement_level: requirement_level:
conditionally_required: > conditionally_required: >
If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. 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` Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr`
without `net.sock.family` coming from instrumentations that follow previous versions if `net.sock.family` is not set. This is to support instrumentations that follow previous versions
of this document. of this document.
brief: > brief: >
Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. 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 examples: 8080
- id: sock.host.addr - id: sock.host.addr
type: string 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' examples: '192.168.0.1'
- id: sock.host.port - id: sock.host.port
type: int type: int

173
semantic_conventions/trace/http.yaml
View File

@ -13,39 +13,6 @@ groups:
brief: 'HTTP request method.' brief: 'HTTP request method.'
sampling_relevant: true sampling_relevant: true
examples: ["GET", "POST", "HEAD"] 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 - id: status_code
type: int type: int
requirement_level: requirement_level:
@ -82,44 +49,27 @@ groups:
is `QUIC`, in which case `IP.UDP` is assumed. is `QUIC`, in which case `IP.UDP` is assumed.
- id: user_agent - id: user_agent
type: string 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'] examples: ['CERN-LineMode/2.15 libwww/2.17b3']
- id: request_content_length - id: request_content_length
type: int type: int
brief: > brief: >
The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and 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. header. For requests using transport encoding, this should be the compressed size.
examples: 3495 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 - id: response_content_length
type: int type: int
brief: > brief: >
The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and 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. header. For requests using transport encoding, this should be the compressed size.
examples: 3495 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.addr
- ref: net.sock.peer.port - ref: net.sock.peer.port
- ref: net.sock.peer.name - ref: net.sock.peer.name
- ref: net.sock.family - ref: net.sock.family
examples: ['inet', 'inet6']
constraints: constraints:
- include: network - include: network
@ -130,31 +80,47 @@ groups:
span_kind: client span_kind: client
brief: 'Semantic Convention for HTTP Client' brief: 'Semantic Convention for HTTP Client'
attributes: 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 - ref: net.peer.name
requirement_level: required
sampling_relevant: true sampling_relevant: true
brief: > brief: >
Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to.
note: > note: |
When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set Determined by using the first of the following that applies
`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 - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
URI host component, otherwise `Host` header host component SHOULD be used. 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 - ref: net.peer.port
sampling_relevant: true sampling_relevant: true
requirement_level: requirement_level:
conditionally_required: if not default for request scheme. conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
brief: > 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: > note: >
When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match 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 - id: http.server
prefix: http prefix: http
type: span type: span
@ -162,21 +128,27 @@ groups:
span_kind: server span_kind: server
brief: 'Semantic Convention for HTTP Server' brief: 'Semantic Convention for HTTP Server'
attributes: attributes:
- id: server_name - id: scheme
type: string type: string
brief: > brief: 'The URI scheme identifying the used protocol.'
The primary server name of the matched virtual host. This should be obtained via configuration. requirement_level: required
If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). sampling_relevant: true
note: > examples: ["http", "https"]
`http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and - id: target
sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). type: string
It is thus preferred to supply the raw data that is available. brief: 'The full request target as passed in a HTTP request line or equivalent.'
examples: ['example.com'] requirement_level: required
sampling_relevant: true
examples: ['/path/12314/?q=ddds']
- id: route - id: route
type: string type: string
requirement_level:
conditionally_required: If and only if it's available
brief: > brief: >
The matched route (path template). The matched route (path template in the format used by the respective server framework). See note below
examples: '/users/:userID?' 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 - id: client_ip
type: string type: string
brief: > brief: >
@ -196,26 +168,35 @@ groups:
the closest proxy. the closest proxy.
examples: '83.164.160.102' examples: '83.164.160.102'
- ref: net.host.name - ref: net.host.name
requirement_level: required
sampling_relevant: true sampling_relevant: true
brief: > brief: >
Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. Name of the local HTTP server that received the request.
note: > note: |
When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set Determined by using the first of the following that applies
`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 - The [primary server name](#http-server-definitions) of the matched virtual host. MUST only
URI host component, otherwise `Host` header host component SHOULD be used. 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 - ref: net.host.port
sampling_relevant: true sampling_relevant: true
requirement_level:
conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
brief: > brief: >
Port component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. Port of the local HTTP server that received the request.
note: > note: |
When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.port` SHOULD match Determined by using the first of the following that applies
URI port component, otherwise `Host` header port component SHOULD be used.
- 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 - ref: net.sock.host.addr
requirement_level: optional
- ref: net.sock.host.port - 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]

57
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: and whether they should be on server, client, or both types of HTTP metric events:
| Name | Type | Requirement Level | Notes and examples | | Name | Type | Requirement Level | Notes and examples |
|--------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |----------------------|---------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `http.method` | `client` & `server` | Required | The HTTP request method. E.g. `"GET"` | | `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` | `server` | Required | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` |
| `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: if and only if one was received/sent. | [HTTP response status code][]. E.g. `200` (String) |
| `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"`. | | `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.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` | 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` | 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` | 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` | Recommended | 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` | Required | Host of the local HTTP server that received the request. |
| `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` | Conditionally Required: If not default (`80` for `http`, `443` for `https`). | Port of the local HTTP server that received the request. |
| `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) |
The following attributes SHOULD be included in the `http.server.active_requests` observation: The following attributes SHOULD be included in the `http.server.active_requests` observation:
| Name | Requirement Level | Notes and examples | | Name | Requirement Level | Notes and examples |
|--------------------|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |--------------------|-------------------|----------------------------------------------------------------------------------|
| `http.method` | Required | The HTTP request method. E.g. `"GET"` | | `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` | Required | The URI scheme identifying the used protocol in lowercase: `"http"` or `"https"` |
| `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.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). | | `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 host header]: https://www.rfc-editor.org/rfc/rfc9110.html#name-host-and-authority
[HTTP response status code]: https://tools.ietf.org/html/rfc7231#section-6 [HTTP response status code]: https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes
[HTTP reason phrase]: https://tools.ietf.org/html/rfc7230#section-3.1.2 [HTTP reason phrase]: https://www.rfc-editor.org/rfc/rfc9110.html#section-15.1
### Parameterized attributes ### Parameterized attributes
To avoid high cardinality the following attributes SHOULD substitute any parameters when added as attributes to http metric events as described below: 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 | | Attribute name | Type | Requirement Level | Notes and examples |
|----------------|---------------------|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------| |----------------|---------|-------------------|--------------------------------------------------------------------------------------------------------|
| `http.url` | `client` & `server` | see [attribute alternatives](#attribute-alternatives) | The originally requested URL | | `http.url` | `client` | Required | 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={}"`. | | `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` 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. 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, cardinality names formed from the available parameters of an HTTP request,
such as `"HTTP {METHOD_NAME}"`. These attributes MUST NOT default to using URI such as `"HTTP {METHOD_NAME}"`. These attributes MUST NOT default to using URI
path. 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. **[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. **[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) - [Status](#status)
- [Common Attributes](#common-attributes) - [Common Attributes](#common-attributes)
* [HTTP request and response headers](#http-request-and-response-headers) * [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 client](#http-client)
* [HTTP request retries and redirects](#http-request-retries-and-redirects)
- [HTTP server](#http-server) - [HTTP server](#http-server)
* [HTTP server definitions](#http-server-definitions) * [HTTP server definitions](#http-server-definitions)
* [HTTP Server semantic conventions](#http-server-semantic-conventions) * [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 | | Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---| |---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `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.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.flavor` | string | Kind of HTTP protocol used. [1] | `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.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://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` | 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.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://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://tools.ietf.org/html/rfc7230#section-3.3.2) 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] |
| `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] |
| [`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.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.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: [6] | | [`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. **[4]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set.
**[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.
`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. `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: Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
* `http.method` * `http.method`
* `http.url`
* `http.target`
* `http.host`
* `http.scheme`
<!-- endsemconv --> <!-- 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). 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 ### HTTP request and response headers
| Attribute | Type | Description | Examples | Requirement Level | | 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. **[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. 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. 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. **[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 ## HTTP client
This span type represents an outbound HTTP request. 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 --> <!-- semconv http.client -->
| Attribute | Type | Description | Examples | Requirement Level | | 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 | | `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 |
| [`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.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` SHOULD NOT be set if capturing it would require an extra DNS lookup.
* `http.scheme`, `http.host`, `http.target`
* `http.scheme`, [`net.peer.name`](span-general.md), [`net.peer.port`](span-general.md), `http.target` **[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.
* `http.scheme`, [`net.sock.peer.addr`](span-general.md), [`net.sock.peer.port`](span-general.md), `http.target`
**[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: 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.name`](span-general.md)
* [`net.peer.port`](span-general.md) * [`net.peer.port`](span-general.md)
<!-- endsemconv --> <!-- 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 ### HTTP request retries and redirects
from the `net.peer.name`
used to look up the `net.sock.peer.addr` that is actually connected to. Retries and redirects cause more than one physical HTTP request to be sent.
In that case it is strongly recommended to set the `net.peer.name` attribute in addition to `http.host`. 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 ## HTTP server
@ -243,15 +229,16 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
<!-- semconv http.server --> <!-- semconv http.server -->
| Attribute | Type | Description | Examples | Requirement Level | | 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.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required |
| `http.route` | string | The matched route (path template). | `/users/:userID?` | Recommended | | `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 | | `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.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 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.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` | Recommended | | [`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: [5] | | [`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 **[2]:** This is not necessarily the same as `net.sock.peer.addr`, which would
identify the network-level peer, which may be a proxy. 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 one is at least somewhat confident that the address is not that of
the closest proxy. 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` - Port identifier of the [primary server host](#http-server-definitions) of the matched virtual host.
* `http.scheme`, `http.server_name`, [`net.host.port`](span-general.md), `http.target` - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
* `http.scheme`, [`net.host.name`](span-general.md), [`net.host.port`](span-general.md), `http.target` if it's sent in absolute-form.
* `http.url` - 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: 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.name`](span-general.md)
* [`net.host.port`](span-general.md) * [`net.host.port`](span-general.md)
<!-- endsemconv --> <!-- 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. `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.
For example, `http.server_name` has shown great value in practice, as bogus HTTP Host headers occur often in the wild.
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 ## HTTP client-server example
@ -300,6 +296,8 @@ Span name: `HTTP GET`
| `http.method` | `"GET"` | | `http.method` | `"GET"` |
| `http.flavor` | `"1.1"` | | `http.flavor` | `"1.1"` |
| `http.url` | `"https://example.com:8080/webshop/articles/4?s=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"` | | `net.sock.peer.addr` | `"192.0.2.5"` |
| `http.status_code` | `200` | | `http.status_code` | `200` |
@ -312,8 +310,7 @@ Span name: `/webshop/articles/:article_id`.
| `http.method` | `"GET"` | | `http.method` | `"GET"` |
| `http.flavor` | `"1.1"` | | `http.flavor` | `"1.1"` |
| `http.target` | `"/webshop/articles/4?s=1"` | | `http.target` | `"/webshop/articles/4?s=1"` |
| `http.host` | `"example.com:8080"` | | `net.host.name` | `"example.com"` |
| `http.server_name` | `"example.com"` |
| `net.host.port` | `8080` | | `net.host.port` | `8080` |
| `http.scheme` | `"https"` | | `http.scheme` | `"https"` |
| `http.route` | `"/webshop/articles/:article_id"` | | `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) | | `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"` | | `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 ## HTTP retries examples
Example of retries in the presence of a trace started by an inbound request: 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. **[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. **[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.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.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] | | [`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. **[2]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set.
<!-- endsemconv --> <!-- 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.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.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.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.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.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 | | `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`. **[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. **[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. **[5]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup.