176 lines
8.7 KiB
YAML
176 lines
8.7 KiB
YAML
groups:
|
|
- id: registry.http
|
|
prefix: http
|
|
type: attribute_group
|
|
display_name: HTTP Attributes
|
|
brief: 'This document defines semantic convention attributes in the HTTP namespace.'
|
|
attributes:
|
|
- 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
|
|
stability: experimental # this should not be marked stable with other HTTP attributes
|
|
- id: request.header
|
|
stability: stable
|
|
type: template[string[]]
|
|
brief: >
|
|
HTTP request headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values.
|
|
note: >
|
|
Instrumentations SHOULD require an explicit configuration of which headers are to be captured.
|
|
Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
|
|
|
|
The `User-Agent` header is already captured in the `user_agent.original` attribute.
|
|
Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
|
|
|
|
The attribute value MUST consist of either multiple header values as an array of strings
|
|
or a single-item array containing a possibly comma-concatenated string, depending on the way
|
|
the HTTP library provides access to headers.
|
|
examples: ['http.request.header.content-type=["application/json"]', 'http.request.header.x-forwarded-for=["1.2.3.4", "1.2.3.5"]']
|
|
- id: request.method
|
|
stability: stable
|
|
type:
|
|
allow_custom_values: true
|
|
members:
|
|
- id: connect
|
|
value: "CONNECT"
|
|
brief: 'CONNECT method.'
|
|
stability: stable
|
|
- id: delete
|
|
value: "DELETE"
|
|
brief: 'DELETE method.'
|
|
stability: stable
|
|
- id: get
|
|
value: "GET"
|
|
brief: 'GET method.'
|
|
stability: stable
|
|
- id: head
|
|
value: "HEAD"
|
|
brief: 'HEAD method.'
|
|
stability: stable
|
|
- id: options
|
|
value: "OPTIONS"
|
|
brief: 'OPTIONS method.'
|
|
stability: stable
|
|
- id: patch
|
|
value: "PATCH"
|
|
brief: 'PATCH method.'
|
|
stability: stable
|
|
- id: post
|
|
value: "POST"
|
|
brief: 'POST method.'
|
|
stability: stable
|
|
- id: put
|
|
value: "PUT"
|
|
brief: 'PUT method.'
|
|
stability: stable
|
|
- id: trace
|
|
value: "TRACE"
|
|
brief: 'TRACE method.'
|
|
stability: stable
|
|
- id: other
|
|
value: "_OTHER"
|
|
brief: 'Any HTTP method that the instrumentation has no prior knowledge of.'
|
|
stability: stable
|
|
brief: 'HTTP request method.'
|
|
examples: ["GET", "POST", "HEAD"]
|
|
note: |
|
|
HTTP request method value SHOULD be "known" to the instrumentation.
|
|
By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
|
|
and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
|
|
|
|
If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER`.
|
|
|
|
If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override
|
|
the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named
|
|
OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods
|
|
(this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults).
|
|
|
|
HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
|
|
Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
|
|
Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
|
|
- id: request.method_original
|
|
stability: stable
|
|
type: string
|
|
brief: Original HTTP method sent by the client in the request line.
|
|
examples: ["GeT", "ACL", "foo"]
|
|
- id: request.resend_count
|
|
stability: stable
|
|
type: int
|
|
brief: >
|
|
The ordinal number of request resending attempt (for any reason, including redirects).
|
|
note: >
|
|
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).
|
|
examples: 3
|
|
- id: request.size
|
|
type: int
|
|
brief: >
|
|
The total size of the request in bytes. This should be the total number of bytes sent over the wire, including the request line (HTTP/1.1),
|
|
framing (HTTP/2 and HTTP/3), headers, and request body if any.
|
|
examples: 1437
|
|
stability: experimental
|
|
- 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
|
|
stability: experimental # this should not be marked stable with other HTTP attributes
|
|
- id: response.header
|
|
stability: stable
|
|
type: template[string[]]
|
|
brief: >
|
|
HTTP response headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values.
|
|
note: >
|
|
Instrumentations SHOULD require an explicit configuration of which headers are to be captured.
|
|
Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
|
|
|
|
Users MAY explicitly configure instrumentations to capture them even though it is not recommended.
|
|
|
|
The attribute value MUST consist of either multiple header values as an array of strings
|
|
or a single-item array containing a possibly comma-concatenated string, depending on the way
|
|
the HTTP library provides access to headers.
|
|
examples: ['http.response.header.content-type=["application/json"]', 'http.response.header.my-custom-header=["abc", "def"]']
|
|
- id: response.size
|
|
type: int
|
|
brief: >
|
|
The total size of the response in bytes. This should be the total number of bytes sent over the wire, including the status line (HTTP/1.1),
|
|
framing (HTTP/2 and HTTP/3), headers, and response body and trailers if any.
|
|
examples: 1437
|
|
stability: experimental
|
|
- id: response.status_code
|
|
stability: stable
|
|
type: int
|
|
brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).'
|
|
examples: [200]
|
|
- id: route
|
|
stability: stable
|
|
type: string
|
|
brief: >
|
|
The matched route, that is, the path template in the format used by the respective server framework.
|
|
examples: ['/users/:userID?', '{controller}/{action}/{id?}']
|
|
note: >
|
|
MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
|
|
|
|
SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one.
|
|
- id: connection.state
|
|
type:
|
|
allow_custom_values: true
|
|
members:
|
|
- id: active
|
|
value: "active"
|
|
brief: 'active state.'
|
|
stability: experimental
|
|
- id: idle
|
|
value: "idle"
|
|
brief: 'idle state.'
|
|
stability: experimental
|
|
brief: State of the HTTP connection in the HTTP connection pool.
|
|
stability: experimental
|
|
examples: ["active", "idle"]
|