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

BREAKING: Introduce common `url.*` attributes, and improve use of namespacing under `http.*` (#3355)

This commit is contained in:
Liudmila Molkova 2023-05-08 19:55:53 -07:00 committed by GitHub
parent 9e3e528ccc
commit 614dbefc77
9 changed files with 192 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
schemas/1.21.0
View File

@ -36,6 +36,15 @@ versions:
net.host.carrier.mcc: network.carrier.mcc
net.host.carrier.mnc: network.carrier.mnc
net.host.carrier.icc: network.carrier.icc
# https://github.com/open-telemetry/opentelemetry-specification/pull/3355
- rename_attributes:
attribute_map:
http.method: http.request.method
http.status_code: http.response.status_code
http.scheme: url.scheme
http.url: url.full
http.request_content_length: http.request.body.size
http.response_content_length: http.response.body.size
1.20.0:
spans:
changes:

41
semantic_conventions/deprecated/http.yaml Normal file
View File

@ -0,0 +1,41 @@
groups:
- id: attributes.http.deprecated
type: attribute_group
brief: "Describes deprecated HTTP attributes."
prefix: http
attributes:
- id: method
type: string
brief: 'Deprecated, use `http.request.method` instead.'
stability: deprecated
examples: ["GET", "POST", "HEAD"]
- id: status_code
type: int
brief: 'Deprecated, use `http.response.status_code` instead.'
stability: deprecated
examples: [200]
- id: scheme
type: string
brief: 'Deprecated, use `url.scheme` instead.'
stability: deprecated
examples: ['http', 'https']
- id: url
type: string
brief: 'Deprecated, use `url.full` instead.'
stability: deprecated
examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv']
- id: target
type: string
brief: 'Deprecated, use `url.path` and `url.query` instead.'
stability: deprecated
examples: ['/search?q=OpenTelemetry#SemConv']
- id: request_content_length
type: int
brief: 'Deprecated, use `http.request.body.size` instead.'
stability: deprecated
examples: 3495
- id: response_content_length
type: int
brief: 'Deprecated, use `http.response.body.size` instead.'
stability: deprecated
examples: 3495

12
semantic_conventions/http-common.yaml
View File

@ -4,12 +4,12 @@ groups:
brief: "Describes HTTP attributes."
prefix: http
attributes:
- id: method
- id: request.method
type: string
requirement_level: required
brief: 'HTTP request method.'
examples: ["GET", "POST", "HEAD"]
- id: status_code
- id: response.status_code
type: int
requirement_level:
conditionally_required: If and only if one was received/sent.
@ -53,11 +53,6 @@ groups:
type: attribute_group
brief: 'HTTP Server spans attributes'
attributes:
- id: scheme
type: string
brief: 'The URI scheme identifying the used protocol.'
requirement_level: required
examples: ["http", "https"]
- id: route
type: string
requirement_level:
@ -96,3 +91,6 @@ groups:
- 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: url.scheme
requirement_level: required
examples: ["http", "https"]

31
semantic_conventions/metrics/http.yaml
View File

@ -8,8 +8,8 @@ groups:
extends: attributes.http.server
attributes:
# todo (lmolkova) build tools don't populate grandparent attributes
- ref: http.method
- ref: http.status_code
- ref: http.request.method
- ref: http.response.status_code
- ref: network.protocol.name
- ref: network.protocol.version
@ -20,8 +20,10 @@ groups:
instrument: updowncounter
unit: "{request}"
attributes:
- ref: http.method
- ref: http.scheme
- ref: http.request.method
- ref: url.scheme
requirement_level: required
examples: ["http", "https"]
- ref: server.address
requirement_level: required
brief: >
@ -60,8 +62,8 @@ groups:
# TODO (trask) below attributes are identical to above in metric.http.server.duration
attributes:
# todo (lmolkova) build tools don't populate grandparent attributes
- ref: http.method
- ref: http.status_code
- ref: http.request.method
- ref: http.response.status_code
- ref: network.protocol.name
- ref: network.protocol.version
@ -74,8 +76,8 @@ groups:
extends: attributes.http.server
# TODO (trask) below attributes are identical to above in metric.http.server.duration
attributes:
- ref: http.method
- ref: http.status_code
- ref: http.request.method
- ref: http.response.status_code
- ref: network.protocol.name
- ref: network.protocol.version
@ -87,12 +89,11 @@ groups:
unit: "s"
extends: attributes.http.client
attributes:
- ref: http.method
- ref: http.status_code
- ref: http.request.method
- ref: http.response.status_code
- ref: network.protocol.name
- ref: network.protocol.version
- ref: server.socket.address
- id: metric.http.client.request.size
type: metric
metric_name: http.client.request.size
@ -102,8 +103,8 @@ groups:
extends: attributes.http.client
# TODO (trask) below attributes are identical to above in metric.http.client.duration
attributes:
- ref: http.method
- ref: http.status_code
- ref: http.request.method
- ref: http.response.status_code
- ref: network.protocol.name
- ref: network.protocol.version
- ref: server.socket.address
@ -117,8 +118,8 @@ groups:
extends: attributes.http.client
# TODO (trask) below attributes are identical to above in metric.http.client.duration
attributes:
- ref: http.method
- ref: http.status_code
- ref: http.request.method
- ref: http.response.status_code
- ref: network.protocol.name
- ref: network.protocol.version
- ref: server.socket.address

38
semantic_conventions/trace/http.yaml
View File

@ -8,21 +8,21 @@ groups:
These conventions can be used for http and https schemes
and various HTTP versions like 1.1, 2 and SPDY.
attributes:
- id: request_content_length
- id: request.body.size
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://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
- id: response.body.size
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://www.rfc-editor.org/rfc/rfc9110.html#field.content-length)
header. For requests using transport encoding, this should be the compressed size.
examples: 3495
- ref: http.method
- ref: http.request.method
sampling_relevant: true
- ref: network.transport
requirement_level:
@ -37,17 +37,6 @@ 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']
- id: resend_count
type: int
brief: >
@ -85,6 +74,10 @@ groups:
- ref: server.socket.domain
- ref: server.socket.address
- ref: server.socket.port
- ref: url.full
sampling_relevant: true
requirement_level: required
- id: trace.http.server
prefix: http
@ -93,14 +86,6 @@ groups:
span_kind: server
brief: 'Semantic Convention for HTTP Server'
attributes:
- 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: ['/users/12314/?q=ddds']
- ref: http.scheme
sampling_relevant: true
- ref: server.address
requirement_level: required
sampling_relevant: true
@ -149,3 +134,12 @@ groups:
Otherwise, the immediate client peer port.
- ref: client.socket.address
- ref: client.socket.port
- ref: url.path
requirement_level: required
sampling_relevant: true
- ref: url.query
sampling_relevant: true
- ref: url.scheme
sampling_relevant: true
requirement_level: required
examples: ["http", "https"]

39
semantic_conventions/url.yaml Normal file
View File

@ -0,0 +1,39 @@
groups:
- id: url
brief: Attributes describing URL.
type: attribute_group
prefix: url
attributes:
- id: scheme
type: string
brief: 'The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol.'
examples: ["https", "ftp", "telnet"]
- id: full
type: string
brief: Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986)
note: >
For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
is not transmitted over HTTP, but if it is known, it should be included nevertheless.
`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`.
In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`.
`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed)
and SHOULD NOT be validated or modified except for sanitizing purposes.
examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost']
tag: sensitive-information
- id: path
type: string
brief: 'The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component'
examples: ['/search']
note: When missing, the value is assumed to be `/`
- id: query
type: string
brief: 'The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component'
examples: ["q=OpenTelemetry"]
note: Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it.
tag: sensitive-information
- id: fragment
type: string
brief: 'The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component'
examples: ["SemConv"]

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

@ -69,14 +69,14 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
<!-- semconv metric.http.server.duration(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | 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.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.response.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. |
| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
@ -116,10 +116,10 @@ This metric is optional.
<!-- semconv metric.http.server.active_requests(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required |
| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Conditionally Required: [3] |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** Determined by using the first of the following that applies
@ -154,14 +154,14 @@ This metric is optional.
<!-- semconv metric.http.server.request.size(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | 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.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.response.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. |
| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
@ -201,14 +201,14 @@ This metric is optional.
<!-- semconv metric.http.server.response.size(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | 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.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.response.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. |
| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required |
| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
@ -254,8 +254,8 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
<!-- semconv metric.http.client.duration(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.response.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. |
| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/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 |
@ -290,8 +290,8 @@ This metric is optional.
<!-- semconv metric.http.client.request.size(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.response.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. |
| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/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 |
@ -326,8 +326,8 @@ This metric is optional.
<!-- semconv metric.http.client.response.size(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `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.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.response.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. |
| [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |
| [`server.address`](../../trace/semantic_conventions/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 |

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

@ -54,7 +54,7 @@ and various HTTP versions like 1.1, 2 and SPDY.
## Name
HTTP spans MUST follow the overall [guidelines for span names](../api.md#span).
HTTP server span names SHOULD be `{http.method} {http.route}` if there is a
HTTP server span names SHOULD be `{http.request.method} {http.route}` if there is a
(low-cardinality) `http.route` available.
HTTP server span names SHOULD be `{http.method}` if there is no (low-cardinality)
`http.route` available.
@ -78,7 +78,7 @@ and MUST be set to `Error` in case of `SpanKind.CLIENT`.
For HTTP status codes in the 5xx range, as well as any other code the client
failed to interpret, span status MUST be set to `Error`.
Don't set the span status description if the reason can be inferred from `http.status_code`.
Don't set the span status description if the reason can be inferred from `http.response.status_code`.
## Common Attributes
@ -89,10 +89,10 @@ sections below.
<!-- semconv trace.http.common(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `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.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 |
| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| `http.response.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.request.body.size` | 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.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended |
| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required |
| [`network.protocol.name`](span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). |
| [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [1] | `1.0`; `1.1`; `2.0` | Recommended |
| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [2] |
@ -105,7 +105,7 @@ sections below.
Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
* `http.method`
* `http.request.method`
`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
@ -134,7 +134,7 @@ Following attributes MUST be provided **at span creation time** (when provided a
**[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.
The `User-Agent` header is already captured in the `http.user_agent` attribute.
The `User-Agent` header is already captured in the `user_agent.original` attribute.
Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
**[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.
@ -149,26 +149,24 @@ This span type represents an outbound HTTP request. There are two ways this can
2. If for some reason it is not possible to emit a span for each send attempt (because e.g. the instrumented library does not expose hooks that would allow this),
instrumentations MAY create an HTTP span for the top-most operation of the HTTP client.
In this case, the `http.url` MUST be the originally requested URL, before any HTTP-redirects that may happen when executing the request.
In this case, the `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request.
For an HTTP client span, `SpanKind` MUST be `Client`.
<!-- semconv trace.http.client(full) -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `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.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [2] | `3` | Recommended: if and only if request was retried. |
| [`server.address`](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. [3] | `example.com` | Required |
| [`server.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. |
| [`server.address`](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 |
| [`server.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] |
| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. | `10.5.3.2` | Recommended: If different than `server.address`. |
| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [6] | `proxy.example.com` | Recommended |
| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended |
| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. |
| [`url.full`](../../common/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required |
**[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]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
**[2]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other).
**[3]:** Determined by using the first of the following that applies
**[2]:** 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
@ -177,17 +175,21 @@ For an HTTP client span, `SpanKind` MUST be `Client`.
If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x.x.x:8080`, then
`server.address` SHOULD be the IP address `x.x.x.x`. A DNS lookup SHOULD NOT be used.
**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier.
**[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier.
**[5]:** If not default (`80` for `http` scheme, `443` for `https`).
**[4]:** If not default (`80` for `http` scheme, `443` for `https`).
**[6]:** Typically observed from the client side, and represents a proxy or other intermediary domain name.
**[5]:** Typically observed from the client side, and represents a proxy or other intermediary domain name.
**[6]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless.
`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`.
`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes.
Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
* `http.url`
* [`server.address`](span-general.md)
* [`server.port`](span-general.md)
* [`url.full`](../../common/url.md)
<!-- endsemconv -->
Note that in some cases host and port identifiers in the `Host` header might be different from the `server.address` and `server.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user.
@ -269,16 +271,17 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `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.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/users/12314/?q=ddds` | Required |
| [`client.address`](span-general.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended |
| [`client.port`](span-general.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended |
| [`client.socket.address`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. |
| [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. |
| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required |
| [`server.address`](span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Required |
| [`server.port`](span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Conditionally Required: [6] |
| [`server.socket.address`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In |
| [`server.socket.port`](span-general.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In |
| [`url.path`](../../common/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required |
| [`url.query`](../../common/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Recommended |
| [`url.scheme`](../../common/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required |
**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
@ -306,12 +309,17 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
**[6]:** If not default (`80` for `http` scheme, `443` for `https`).
**[7]:** When missing, the value is assumed to be `/`
**[8]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it.
Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions:
* `http.target`
* `http.scheme`
* [`server.address`](span-general.md)
* [`server.port`](span-general.md)
* [`url.path`](../../common/url.md)
* [`url.query`](../../common/url.md)
* [`url.scheme`](../../common/url.md)
<!-- endsemconv -->
`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.
@ -328,13 +336,13 @@ Span name: `GET`
| Attribute name | Value |
| :------------------- | :-------------------------------------------------------|
| `http.method` | `"GET"` |
| `http.flavor` | `"1.1"` |
| `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` |
| `http.request.method`| `"GET"` |
| `network.protocol.version` | `"1.1"` |
| `url.full` | `"https://example.com:8080/webshop/articles/4?s=1"` |
| `server.address` | `example.com` |
| `server.port` | 8080 |
| `server.socket.address` | `"192.0.2.5"` |
| `http.status_code` | `200` |
| `http.response.status_code` | `200` |
The corresponding server Span may look like this:
@ -342,17 +350,18 @@ Span name: `GET /webshop/articles/:article_id`.
| Attribute name | Value |
| :------------------- | :---------------------------------------------- |
| `http.method` | `"GET"` |
| `http.flavor` | `"1.1"` |
| `http.target` | `"/webshop/articles/4?s=1"` |
| `http.request.method`| `"GET"` |
| `network.protocol.version` | `"1.1"` |
| `url.path` | `"/webshop/articles/4"` |
| `url.query` | `"?s=1"` |
| `server.address` | `"example.com"` |
| `server.port` | `8080` |
| `http.scheme` | `"https"` |
| `url.scheme` | `"https"` |
| `http.route` | `"/webshop/articles/:article_id"` |
| `http.status_code` | `200` |
| `http.response.status_code` | `200` |
| `client.address` | `"192.0.2.4"` |
| `client.socket.address` | `"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"` |
| `user_agent.original` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` |
### HTTP client retries examples

10
specification/trace/semantic_conventions/instrumentation/aws-lambda.md
View File

@ -167,13 +167,11 @@ Function F: | Span Function |
| `server.address` | `foo.execute-api.us-east-1.amazonaws.com` | |
| `server.port` | `413` | |
| `http.method` | `GET` | `GET` |
| `http.user_agent` | `okhttp 3.0` | `okhttp 3.0` |
| `http.url` | `https://foo.execute-api.us-east-1.amazonaws.com/pets/10` | |
| `http.scheme` | | `https` |
| `http.host` | | `foo.execute-api.us-east-1.amazonaws.com` |
| `http.target` | | `/pets/10` |
| `user_agent.original` | `okhttp 3.0` | `okhttp 3.0` |
| `url.scheme` | | `https` |
| `url.path` | | `/pets/10` |
| `http.route` | | `/pets/{petId}` |
| `http.status_code` | `200` | `200` |
| `http.response.status_code` | `200` | `200` |
### API Gateway Request Proxy (Lambda tracing active)