diff --git a/.chloggen/migrate-http-v2.yaml b/.chloggen/migrate-http-v2.yaml new file mode 100644 index 0000000000..5c1caabf26 --- /dev/null +++ b/.chloggen/migrate-http-v2.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: http +note: Migrate HTTP semantic conventions to Weaver v2 schema +issues: [3809] diff --git a/docs/registry/attributes/README.md b/docs/registry/attributes/README.md index 64c71e2869..c66b6c25de 100644 --- a/docs/registry/attributes/README.md +++ b/docs/registry/attributes/README.md @@ -70,8 +70,8 @@ Currently, the following namespaces exist: - [GraphQL](graphql.md) - [Hardware](hardware.md) - [Heroku](heroku.md) +- [Home](home.md) - [Host](host.md) -- [HTTP](http.md) - [iOS](ios.md) - [JSONRPC](jsonrpc.md) - [JVM](jvm.md) diff --git a/docs/registry/attributes/http.md b/docs/registry/attributes/home.md similarity index 97% rename from docs/registry/attributes/http.md rename to docs/registry/attributes/home.md index 5f48f1d314..6e53014093 100644 --- a/docs/registry/attributes/http.md +++ b/docs/registry/attributes/home.md @@ -1,14 +1,14 @@ -# HTTP +# Home -- [HTTP Attributes](#http-attributes) -- [Deprecated HTTP Attributes](#deprecated-http-attributes) +- [Home Weaver Source HTTP Attributes](#home-weaver-source-http-attributes) +- [Home Weaver Source HTTP Deprecated Registry Deprecated Attributes](#home-weaver-source-http-deprecated-registry-deprecated-attributes) -## HTTP Attributes +## Home Weaver Source HTTP Attributes -This document defines semantic convention attributes in the HTTP namespace. + **Attributes:** @@ -123,9 +123,9 @@ support custom route formatting. Instrumentations SHOULD document the format and | `QUERY` | QUERY method. | ![Development](https://img.shields.io/badge/-development-blue) | | `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -## Deprecated HTTP Attributes +## Home Weaver Source HTTP Deprecated Registry Deprecated Attributes -Describes deprecated HTTP attributes. + **Attributes:** diff --git a/model/http/common.yaml b/model/http/common.yaml index 7fd3f9568f..f4794714ee 100644 --- a/model/http/common.yaml +++ b/model/http/common.yaml @@ -1,7 +1,8 @@ -groups: +file_format: definition/2 + +attribute_groups: - id: attributes.http.common - type: attribute_group - brief: "Describes HTTP attributes." + visibility: internal attributes: - ref: http.request.method requirement_level: required @@ -37,10 +38,9 @@ groups: examples: ['1.0', '1.1', '2', '3'] - id: attributes.http.client - type: attribute_group - brief: 'HTTP Client attributes' - extends: attributes.http.common + visibility: internal attributes: + - ref_group: attributes.http.common - ref: server.address requirement_level: required note: | @@ -68,10 +68,9 @@ groups: The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation. - id: attributes.http.server - type: attribute_group - brief: 'HTTP Server attributes' - extends: attributes.http.common + visibility: internal attributes: + - ref_group: attributes.http.common - ref: http.route requirement_level: conditionally_required: If and only if it's available diff --git a/model/http/deprecated/registry-deprecated.yaml b/model/http/deprecated/registry-deprecated.yaml index 7fa7a04b08..e5663afad3 100644 --- a/model/http/deprecated/registry-deprecated.yaml +++ b/model/http/deprecated/registry-deprecated.yaml @@ -1,144 +1,151 @@ -groups: - - id: registry.http.deprecated - type: attribute_group - display_name: Deprecated HTTP Attributes - brief: "Describes deprecated HTTP attributes." - attributes: - - id: http.method - type: string - brief: 'Deprecated, use `http.request.method` instead.' - stability: development - deprecated: - reason: renamed - renamed_to: http.request.method - examples: ["GET", "POST", "HEAD"] - - id: http.status_code - type: int - brief: 'Deprecated, use `http.response.status_code` instead.' - stability: development - deprecated: - reason: renamed - renamed_to: http.response.status_code - examples: [200] - - id: http.scheme - type: string - brief: 'Deprecated, use `url.scheme` instead.' - stability: development - deprecated: - reason: renamed - renamed_to: url.scheme - examples: ['http', 'https'] - - id: http.url - type: string - brief: 'Deprecated, use `url.full` instead.' - stability: development - deprecated: - reason: renamed - renamed_to: url.full - examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] - - id: http.target - type: string - brief: 'Deprecated, use `url.path` and `url.query` instead.' - stability: development - deprecated: - reason: obsoleted - note: Split to `url.path` and `url.query`. - examples: ['/search?q=OpenTelemetry#SemConv'] - - id: http.request_content_length - type: int - brief: 'Deprecated, use `http.request.header.content-length` instead.' - stability: development - deprecated: - reason: uncategorized - note: Replaced by `http.request.header.content-length`. - examples: 3495 - - id: http.response_content_length - type: int - brief: 'Deprecated, use `http.response.header.content-length` instead.' - stability: development - deprecated: - reason: uncategorized - note: Replaced by `http.response.header.content-length`. - examples: 3495 - - id: http.client_ip - type: string - stability: development - deprecated: - reason: renamed - renamed_to: client.address - brief: "Deprecated, use `client.address` instead." - examples: '83.164.160.102' - - id: http.host - type: string - stability: development - deprecated: - reason: uncategorized - note: > - Replaced by one of `server.address`, `client.address` or `http.request.header.host`, depending on the usage. - brief: "Deprecated, use one of `server.address`, `client.address` or `http.request.header.host` instead, depending on the usage." - examples: ['www.example.org'] - - id: http.request_content_length_uncompressed - stability: development - deprecated: - reason: renamed - renamed_to: http.request.body.size - type: int - brief: "Deprecated, use `http.request.body.size` instead." - examples: 5493 - - id: http.response_content_length_uncompressed - stability: development - deprecated: - reason: renamed - renamed_to: http.response.body.size - type: int - brief: "Deprecated, use `http.response.body.size` instead." - examples: 5493 - - id: http.server_name - type: string - stability: development - deprecated: - reason: renamed - renamed_to: server.address - brief: "Deprecated, use `server.address` instead." - examples: ['example.com'] - - id: http.flavor - type: - members: - - id: http_1_0 - value: '1.0' - brief: 'HTTP/1.0' - stability: development - - id: http_1_1 - value: '1.1' - brief: 'HTTP/1.1' - stability: development - - id: http_2_0 - value: '2.0' - brief: 'HTTP/2' - stability: development - - id: http_3_0 - value: '3.0' - brief: 'HTTP/3' - stability: development - - id: spdy - value: 'SPDY' - brief: 'SPDY protocol.' - stability: development - - id: quic - value: 'QUIC' - brief: 'QUIC protocol.' - stability: development - brief: 'Deprecated, use `network.protocol.name` and `network.protocol.version` instead.' - deprecated: - reason: uncategorized - note: "Split into `network.protocol.name` and `network.protocol.version`" - stability: development - - id: http.user_agent - type: string - brief: 'Deprecated, use `user_agent.original` instead.' - examples: ['CERN-LineMode/2.15 libwww/2.17b3', - 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'] - deprecated: - reason: renamed - renamed_to: user_agent.original - stability: development +file_format: definition/2 + + +attributes: + - key: http.method + type: string + brief: 'Deprecated, use `http.request.method` instead.' + stability: development + deprecated: + reason: renamed + renamed_to: http.request.method + note: "Replaced by `http.request.method`." + examples: ["GET", "POST", "HEAD"] + - key: http.status_code + type: int + brief: 'Deprecated, use `http.response.status_code` instead.' + stability: development + deprecated: + reason: renamed + renamed_to: http.response.status_code + note: "Replaced by `http.response.status_code`." + examples: [200] + - key: http.scheme + type: string + brief: 'Deprecated, use `url.scheme` instead.' + stability: development + deprecated: + reason: renamed + renamed_to: url.scheme + note: "Replaced by `url.scheme`." + examples: ['http', 'https'] + - key: http.url + type: string + brief: 'Deprecated, use `url.full` instead.' + stability: development + deprecated: + reason: renamed + renamed_to: url.full + note: "Replaced by `url.full`." + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] + - key: http.target + type: string + brief: 'Deprecated, use `url.path` and `url.query` instead.' + stability: development + deprecated: + reason: obsoleted + note: Split to `url.path` and `url.query`. + examples: ['/search?q=OpenTelemetry#SemConv'] + - key: http.request_content_length + type: int + brief: 'Deprecated, use `http.request.header.content-length` instead.' + stability: development + deprecated: + reason: uncategorized + note: Replaced by `http.request.header.content-length`. + examples: 3495 + - key: http.response_content_length + type: int + brief: 'Deprecated, use `http.response.header.content-length` instead.' + stability: development + deprecated: + reason: uncategorized + note: Replaced by `http.response.header.content-length`. + examples: 3495 + - key: http.client_ip + type: string + stability: development + deprecated: + reason: renamed + renamed_to: client.address + note: "Replaced by `client.address`." + brief: "Deprecated, use `client.address` instead." + examples: '83.164.160.102' + - key: http.host + type: string + stability: development + deprecated: + reason: uncategorized + note: > + Replaced by one of `server.address`, `client.address` or `http.request.header.host`, depending on the usage. + brief: "Deprecated, use one of `server.address`, `client.address` or `http.request.header.host` instead, depending on the usage." + examples: ['www.example.org'] + - key: http.request_content_length_uncompressed + stability: development + deprecated: + reason: renamed + renamed_to: http.request.body.size + note: "Replaced by `http.request.body.size`." + type: int + brief: "Deprecated, use `http.request.body.size` instead." + examples: 5493 + - key: http.response_content_length_uncompressed + stability: development + deprecated: + reason: renamed + renamed_to: http.response.body.size + note: "Replaced by `http.response.body.size`." + type: int + brief: "Deprecated, use `http.response.body.size` instead." + examples: 5493 + - key: http.server_name + type: string + stability: development + deprecated: + reason: renamed + renamed_to: server.address + note: "Replaced by `server.address`." + brief: "Deprecated, use `server.address` instead." + examples: ['example.com'] + - key: http.flavor + type: + members: + - id: http_1_0 + value: '1.0' + brief: 'HTTP/1.0' + stability: development + - id: http_1_1 + value: '1.1' + brief: 'HTTP/1.1' + stability: development + - id: http_2_0 + value: '2.0' + brief: 'HTTP/2' + stability: development + - id: http_3_0 + value: '3.0' + brief: 'HTTP/3' + stability: development + - id: spdy + value: 'SPDY' + brief: 'SPDY protocol.' + stability: development + - id: quic + value: 'QUIC' + brief: 'QUIC protocol.' + stability: development + brief: 'Deprecated, use `network.protocol.name` and `network.protocol.version` instead.' + deprecated: + reason: uncategorized + note: "Split into `network.protocol.name` and `network.protocol.version`" + stability: development + - key: http.user_agent + type: string + brief: 'Deprecated, use `user_agent.original` instead.' + examples: ['CERN-LineMode/2.15 libwww/2.17b3', + 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1'] + deprecated: + reason: renamed + renamed_to: user_agent.original + note: "Replaced by `user_agent.original`." + stability: development diff --git a/model/http/events.yaml b/model/http/events.yaml index de4368c641..d0799e713a 100644 --- a/model/http/events.yaml +++ b/model/http/events.yaml @@ -1,8 +1,9 @@ -groups: - - id: event.http.client.request.exception - name: http.client.request.exception +file_format: definition/2 + +events: + - name: http.client.request.exception stability: development - type: event + requirement_level: recommended brief: > This event represents an exception that occurred during an HTTP client request, such as network failures, timeouts, or other errors that prevent the request @@ -27,10 +28,9 @@ groups: conditionally_required: Required if `exception.type` is not set, recommended otherwise. - ref: exception.stacktrace - - id: event.http.server.request.exception - name: http.server.request.exception + - name: http.server.request.exception stability: development - type: event + requirement_level: recommended brief: > This event represents an exception that occurred during HTTP server request processing, such as application errors, internal failures, or other exceptions that prevent diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index 3659cef3cb..9d88e73b19 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -1,9 +1,10 @@ -groups: +file_format: definition/2 + +attribute_groups: - id: metric_attributes.http.server - type: attribute_group - brief: 'HTTP server attributes' - extends: attributes.http.server + visibility: internal attributes: + - ref_group: attributes.http.server - ref: server.address requirement_level: opt_in note: | @@ -22,25 +23,33 @@ groups: > to trigger cardinality limits, degrading the usefulness of the metric. - ref: user_agent.synthetic.type requirement_level: opt_in + - id: metric_attributes.http.client - type: attribute_group - brief: 'HTTP client attributes' - extends: attributes.http.client + visibility: internal + attributes: + - ref_group: attributes.http.client + - ref: server.address + requirement_level: opt_in + note: | + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + - ref: server.port + requirement_level: opt_in + note: | + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). - id: metric_attributes.http.client.experimental - type: attribute_group - brief: 'HTTP client experimental attributes' - extends: metric_attributes.http.client + visibility: internal attributes: + - ref_group: metric_attributes.http.client - ref: url.template requirement_level: conditionally_required: If available. note: > The `url.template` MUST have low cardinality. It is not usually available on HTTP clients, but may be known by the application or specialized HTTP instrumentation. - - id: metric.http.server.request.duration - type: metric - metric_name: http.server.request.duration +metrics: + - name: http.server.request.duration + requirement_level: recommended annotations: code_generation: metric_value_type: double @@ -48,11 +57,11 @@ groups: instrument: histogram unit: "s" stability: stable - extends: metric_attributes.http.server + attributes: + - ref_group: metric_attributes.http.server - - id: metric.http.server.active_requests - type: metric - metric_name: http.server.active_requests + - name: http.server.active_requests + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -87,9 +96,8 @@ groups: > Since this attribute is based on HTTP headers, opting in to it may allow an attacker > to trigger cardinality limits, degrading the usefulness of the metric. - - id: metric.http.server.request.body.size - type: metric - metric_name: http.server.request.body.size + - name: http.server.request.body.size + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -101,11 +109,11 @@ groups: 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. - extends: metric_attributes.http.server + attributes: + - ref_group: metric_attributes.http.server - - id: metric.http.server.response.body.size - type: metric - metric_name: http.server.response.body.size + - name: http.server.response.body.size + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -117,11 +125,11 @@ groups: 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. - extends: metric_attributes.http.server + attributes: + - ref_group: metric_attributes.http.server - - id: metric.http.client.request.duration - type: metric - metric_name: http.client.request.duration + - name: http.client.request.duration + requirement_level: recommended annotations: code_generation: metric_value_type: double @@ -129,11 +137,11 @@ groups: instrument: histogram unit: "s" stability: stable - extends: metric_attributes.http.client + attributes: + - ref_group: metric_attributes.http.client - - id: metric.http.client.request.body.size - type: metric - metric_name: http.client.request.body.size + - name: http.client.request.body.size + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -145,11 +153,11 @@ groups: 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. - extends: metric_attributes.http.client.experimental + attributes: + - ref_group: metric_attributes.http.client.experimental - - id: metric.http.client.response.body.size - type: metric - metric_name: http.client.response.body.size + - name: http.client.response.body.size + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -161,11 +169,11 @@ groups: 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. - extends: metric_attributes.http.client.experimental + attributes: + - ref_group: metric_attributes.http.client.experimental - - id: metric.http.client.open_connections - type: metric - metric_name: http.client.open_connections + - name: http.client.open_connections + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -188,9 +196,8 @@ groups: requirement_level: opt_in examples: ["http", "https"] - - id: metric.http.client.connection.duration - type: metric - metric_name: http.client.connection.duration + - name: http.client.connection.duration + requirement_level: recommended annotations: code_generation: metric_value_type: double @@ -211,9 +218,8 @@ groups: requirement_level: opt_in examples: ["http", "https"] - - id: metric.http.client.active_requests - type: metric - metric_name: http.client.active_requests + - name: http.client.active_requests + requirement_level: recommended annotations: code_generation: metric_value_type: int diff --git a/model/http/registry.yaml b/model/http/registry.yaml index d91c2d8762..c4c8ed4d4e 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -1,206 +1,204 @@ -groups: - - id: registry.http - type: attribute_group - display_name: HTTP Attributes - brief: 'This document defines semantic convention attributes in the HTTP namespace.' - attributes: - - id: http.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: development # this should not be marked stable with other HTTP attributes - - id: http.request.header - stability: stable - type: template[string[]] - brief: > - HTTP request headers, `` 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: - - - A header `Content-Type: application/json` SHOULD be recorded as the `http.request.header.content-type` - attribute with value `["application/json"]`. - - A header `X-Forwarded-For: 1.2.3.4, 1.2.3.5` SHOULD be recorded as the `http.request.header.x-forwarded-for` - attribute with value `["1.2.3.4", "1.2.3.5"]` or `["1.2.3.4, 1.2.3.5"]` depending on the HTTP library. - - examples: [["application/json"], ["1.2.3.4", "1.2.3.5"]] - - id: http.request.method - stability: stable - type: - 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: query - value: "QUERY" - brief: 'QUERY method.' - stability: development - - 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), - the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html) - and the QUERY method defined in [httpbis-safe-method-w-body](https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/?include_text=1). - - 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. - - ![Development](https://img.shields.io/badge/-development-blue) - If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property - (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or - `.instrumentation/development.general.http.server`. - - In either case, this list MUST be a full override of the default known methods, - 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: http.request.method_original - stability: stable - type: string - brief: Original HTTP method sent by the client in the request line. - examples: ["GeT", "ACL", "foo"] - - id: http.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: http.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: development - - id: http.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: development # this should not be marked stable with other HTTP attributes - - id: http.response.header - stability: stable - type: template[string[]] - brief: > - HTTP response headers, `` 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: - - - A header `Content-Type: application/json` header SHOULD be recorded as the `http.request.response.content-type` - attribute with value `["application/json"]`. - - A header `My-custom-header: abc, def` header SHOULD be recorded as the `http.response.header.my-custom-header` - attribute with value `["abc", "def"]` or `["abc, def"]` depending on the HTTP library. - examples: [["application/json"], ["abc", "def"]] - - id: http.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: development - - id: http.response.status_code - stability: stable - type: int - brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' - examples: [200] - - id: http.route - stability: stable - type: string - brief: > - The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders. - examples: ['/users/:userID?', 'my-controller/my-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. - - A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that - are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`. - - A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments. - - Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY - support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string. - - id: http.connection.state - type: - members: - - id: active - value: "active" - brief: 'active state.' - stability: development - - id: idle - value: "idle" - brief: 'idle state.' - stability: development - brief: State of the HTTP connection in the HTTP connection pool. - stability: development - examples: ["active", "idle"] +file_format: definition/2 + + +attributes: + - key: http.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: development # this should not be marked stable with other HTTP attributes + - key: http.request.header + stability: stable + type: template[string[]] + brief: > + HTTP request headers, `` 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: + + - A header `Content-Type: application/json` SHOULD be recorded as the `http.request.header.content-type` + attribute with value `["application/json"]`. + - A header `X-Forwarded-For: 1.2.3.4, 1.2.3.5` SHOULD be recorded as the `http.request.header.x-forwarded-for` + attribute with value `["1.2.3.4", "1.2.3.5"]` or `["1.2.3.4, 1.2.3.5"]` depending on the HTTP library. + + examples: [["application/json"], ["1.2.3.4", "1.2.3.5"]] + - key: http.request.method + stability: stable + type: + 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: query + value: "QUERY" + brief: 'QUERY method.' + stability: development + - 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), + the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html) + and the QUERY method defined in [httpbis-safe-method-w-body](https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/?include_text=1). + + 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. + + ![Development](https://img.shields.io/badge/-development-blue) + If this override is done via declarative configuration, then the list MUST be configurable via the `known_methods` property + (an array of case-sensitive strings with minimum items 0) under `.instrumentation/development.general.http.client` and/or + `.instrumentation/development.general.http.server`. + + In either case, this list MUST be a full override of the default known methods, + 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. + - key: http.request.method_original + stability: stable + type: string + brief: Original HTTP method sent by the client in the request line. + examples: ["GeT", "ACL", "foo"] + - key: http.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 + - key: http.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: development + - key: http.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: development # this should not be marked stable with other HTTP attributes + - key: http.response.header + stability: stable + type: template[string[]] + brief: > + HTTP response headers, `` 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: + + - A header `Content-Type: application/json` header SHOULD be recorded as the `http.request.response.content-type` + attribute with value `["application/json"]`. + - A header `My-custom-header: abc, def` header SHOULD be recorded as the `http.response.header.my-custom-header` + attribute with value `["abc", "def"]` or `["abc, def"]` depending on the HTTP library. + examples: [["application/json"], ["abc", "def"]] + - key: http.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: development + - key: http.response.status_code + stability: stable + type: int + brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' + examples: [200] + - key: http.route + stability: stable + type: string + brief: > + The matched route template for the request. This MUST be low-cardinality and include all static path segments, with dynamic path segments represented with placeholders. + examples: ['/users/:userID?', 'my-controller/my-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. + + A static path segment is a part of the route template with a fixed, low-cardinality value. This includes literal strings like `/users/` and placeholders that + are constrained to a finite, predefined set of values, e.g. `{controller}` or `{action}`. + + A dynamic path segment is a placeholder for a value that can have high cardinality and is not constrained to a predefined list like static path segments. + + Instrumentations SHOULD use routing information provided by the corresponding web framework. They SHOULD pick the most precise source of routing information and MAY + support custom route formatting. Instrumentations SHOULD document the format and the API used to obtain the route string. + - key: http.connection.state + type: + members: + - id: active + value: "active" + brief: 'active state.' + stability: development + - id: idle + value: "idle" + brief: 'idle state.' + stability: development + brief: State of the HTTP connection in the HTTP connection pool. + stability: development + examples: ["active", "idle"] diff --git a/model/http/spans.yaml b/model/http/spans.yaml index dd49374df9..3787aed5e1 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -1,8 +1,11 @@ -groups: - - id: span.http.client - type: span - extends: attributes.http.client - span_kind: client +file_format: definition/2 + +spans: + - type: http.client + kind: client + requirement_level: recommended + name: + note: "refer to the [Span Name](/docs/http/http-spans.md#name) section." stability: stable brief: > This span represents an outbound HTTP request. @@ -23,6 +26,7 @@ groups: **Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section. attributes: + - ref_group: attributes.http.client - ref: http.request.method sampling_relevant: true - ref: http.request.method_original @@ -65,10 +69,11 @@ groups: - ref: user_agent.synthetic.type requirement_level: opt_in - - id: span.http.server - type: span - extends: attributes.http.server - span_kind: server + - type: http.server + kind: server + requirement_level: recommended + name: + note: "refer to the [Span Name](/docs/http/http-spans.md#name) section." brief: > This span represents an inbound HTTP request. note: | @@ -79,6 +84,7 @@ groups: **Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section. stability: stable attributes: + - ref_group: attributes.http.server - ref: http.request.method sampling_relevant: true - ref: http.request.method_original