From 84f4b2b1b2688f1f09e9f5465bf23c8bbde57ffc Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Fri, 26 Jun 2026 00:22:26 +0530 Subject: [PATCH 01/11] Migrate HTTP conventions to Schema v2 (definition/2) --- model/http/common.yaml | 17 +- .../http/deprecated/registry-deprecated.yaml | 308 +++++++------ model/http/events.yaml | 17 +- model/http/metrics.yaml | 162 +++---- model/http/registry.yaml | 420 +++++++++--------- model/http/spans.yaml | 147 ++++-- 6 files changed, 580 insertions(+), 491 deletions(-) diff --git a/model/http/common.yaml b/model/http/common.yaml index 7fd3f9568f..89bcc07ae4 100644 --- a/model/http/common.yaml +++ b/model/http/common.yaml @@ -1,6 +1,9 @@ -groups: +file_format: definition/2 + +attribute_groups: - id: attributes.http.common - type: attribute_group + visibility: public + stability: development brief: "Describes HTTP attributes." attributes: - ref: http.request.method @@ -37,10 +40,11 @@ groups: examples: ['1.0', '1.1', '2', '3'] - id: attributes.http.client - type: attribute_group + visibility: public + stability: development brief: 'HTTP Client attributes' - extends: attributes.http.common attributes: + - ref_group: attributes.http.common - ref: server.address requirement_level: required note: | @@ -68,10 +72,11 @@ 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 + visibility: public + stability: development brief: 'HTTP Server attributes' - extends: attributes.http.common 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..af1ea38127 100644 --- a/model/http/deprecated/registry-deprecated.yaml +++ b/model/http/deprecated/registry-deprecated.yaml @@ -1,144 +1,164 @@ -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 + stability: development + deprecated: + reason: renamed + renamed_to: http.request.method + note: 'Replaced by `http.request.method`.' + brief: 'Deprecated, use `http.request.method` instead.' + examples: ["GET", "POST", "HEAD"] + + - key: http.status_code + type: int + stability: development + deprecated: + reason: renamed + renamed_to: http.response.status_code + note: 'Replaced by `http.response.status_code`.' + brief: 'Deprecated, use `http.response.status_code` instead.' + examples: [200] + + - key: http.scheme + type: string + stability: development + deprecated: + reason: renamed + renamed_to: url.scheme + note: 'Replaced by `url.scheme`.' + brief: 'Deprecated, use `url.scheme` instead.' + examples: ['http', 'https'] + + - key: http.url + type: string + stability: development + deprecated: + reason: renamed + renamed_to: url.full + note: 'Replaced by `url.full`.' + brief: 'Deprecated, use `url.full` instead.' + examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] + + - key: http.target + type: string + stability: development + deprecated: + reason: obsoleted + note: Split to `url.path` and `url.query`. + brief: 'Deprecated, use `url.path` and `url.query` instead.' + examples: ['/search?q=OpenTelemetry#SemConv'] + + - key: http.request_content_length + type: int + stability: development + deprecated: + reason: uncategorized + note: Replaced by `http.request.header.content-length`. + brief: 'Deprecated, use `http.request.header.content-length` instead.' + examples: 3495 + + - key: http.response_content_length + type: int + stability: development + deprecated: + reason: uncategorized + note: Replaced by `http.response.header.content-length`. + brief: 'Deprecated, use `http.response.header.content-length` instead.' + 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 + type: int + stability: development + deprecated: + reason: renamed + renamed_to: http.request.body.size + note: 'Replaced by `http.request.body.size`.' + brief: "Deprecated, use `http.request.body.size` instead." + examples: 5493 + + - key: http.response_content_length_uncompressed + type: int + stability: development + deprecated: + reason: renamed + renamed_to: http.response.body.size + note: 'Replaced by `http.response.body.size`.' + 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 + stability: development + deprecated: + reason: uncategorized + note: "Split into `network.protocol.name` and `network.protocol.version`" + 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.' + + - key: http.user_agent + type: string + stability: development + deprecated: + reason: renamed + renamed_to: user_agent.original + note: 'Replaced by `user_agent.original`.' + 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' diff --git a/model/http/events.yaml b/model/http/events.yaml index de4368c641..c793c95a63 100644 --- a/model/http/events.yaml +++ b/model/http/events.yaml @@ -1,21 +1,17 @@ -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 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 from completing successfully. note: > This event SHOULD be recorded when an exception occurs during HTTP client operations. - Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. - Some HTTP client frameworks generate artificial exceptions for non-successful HTTP status codes (e.g., 404 Not Found). When possible, instrumentations SHOULD NOT record these artificial exceptions, or SHOULD set the severity to DEBUG (severity number 5). - Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding HTTP client span. attributes: @@ -26,20 +22,15 @@ groups: requirement_level: 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 brief: > This event represents an exception that occurred during HTTP server request processing, such as application errors, internal failures, or other exceptions that prevent the server from successfully handling the request. note: > This event SHOULD be recorded when an exception occurs during HTTP server request processing. - Instrumentations SHOULD set the severity to ERROR (severity number 17) when recording this event. - Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding HTTP server span. attributes: diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index 3659cef3cb..61889f7f17 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -1,65 +1,54 @@ -groups: +file_format: definition/2 + +attribute_groups: - id: metric_attributes.http.server - type: attribute_group - brief: 'HTTP server attributes' - extends: attributes.http.server + visibility: public + stability: development + brief: 'HTTP server metric attributes' attributes: - - 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). - - > [!WARNING] - > 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. - - 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). - - > [!WARNING] - > 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. + - ref_group: attributes.http.server - 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: public + stability: development + brief: 'HTTP client metric attributes' + attributes: + - ref_group: attributes.http.client - id: metric_attributes.http.client.experimental - type: attribute_group - brief: 'HTTP client experimental attributes' - extends: metric_attributes.http.client + visibility: public + stability: development + brief: 'HTTP client experimental metric attributes (extends metric_attributes.http.client)' attributes: + - ref_group: 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 - annotations: - code_generation: - metric_value_type: double +metrics: + - name: http.server.request.duration + stability: stable brief: "Duration of HTTP server requests." instrument: histogram unit: "s" - stability: stable - extends: metric_attributes.http.server - - - id: metric.http.server.active_requests - type: metric - metric_name: http.server.active_requests annotations: code_generation: - metric_value_type: int + metric_value_type: double + attributes: + - ref_group: metric_attributes.http.server + + - name: http.server.active_requests stability: development brief: "Number of active HTTP server requests." instrument: updowncounter unit: "{request}" + annotations: + code_generation: + metric_value_type: int attributes: - ref: http.request.method requirement_level: required @@ -87,92 +76,85 @@ 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 - annotations: - code_generation: - metric_value_type: int + - name: http.server.request.body.size stability: development brief: "Size of HTTP server request bodies." instrument: histogram unit: "By" + annotations: + code_generation: + metric_value_type: int note: > 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 - annotations: - code_generation: - metric_value_type: int + - name: http.server.response.body.size stability: development brief: "Size of HTTP server response bodies." instrument: histogram unit: "By" + annotations: + code_generation: + metric_value_type: int note: > 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 - annotations: - code_generation: - metric_value_type: double + - name: http.client.request.duration + stability: stable brief: "Duration of HTTP client requests." instrument: histogram unit: "s" - stability: stable - extends: metric_attributes.http.client - - - id: metric.http.client.request.body.size - type: metric - metric_name: http.client.request.body.size annotations: code_generation: - metric_value_type: int + metric_value_type: double + attributes: + - ref_group: metric_attributes.http.client + + - name: http.client.request.body.size stability: development brief: "Size of HTTP client request bodies." instrument: histogram unit: "By" + annotations: + code_generation: + metric_value_type: int note: > 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 - annotations: - code_generation: - metric_value_type: int + - name: http.client.response.body.size stability: development brief: "Size of HTTP client response bodies." instrument: histogram unit: "By" + annotations: + code_generation: + metric_value_type: int note: > 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 - annotations: - code_generation: - metric_value_type: int + - name: http.client.open_connections stability: development brief: "Number of outbound HTTP connections that are currently active or idle on the client." instrument: updowncounter unit: "{connection}" + annotations: + code_generation: + metric_value_type: int attributes: - ref: http.connection.state requirement_level: required @@ -188,16 +170,14 @@ groups: requirement_level: opt_in examples: ["http", "https"] - - id: metric.http.client.connection.duration - type: metric - metric_name: http.client.connection.duration - annotations: - code_generation: - metric_value_type: double + - name: http.client.connection.duration stability: development brief: "The duration of the successfully established outbound HTTP connections." instrument: histogram unit: "s" + annotations: + code_generation: + metric_value_type: double attributes: - ref: network.peer.address requirement_level: opt_in @@ -211,16 +191,14 @@ groups: requirement_level: opt_in examples: ["http", "https"] - - id: metric.http.client.active_requests - type: metric - metric_name: http.client.active_requests - annotations: - code_generation: - metric_value_type: int + - name: http.client.active_requests stability: development brief: "Number of active HTTP requests." instrument: updowncounter unit: "{request}" + annotations: + code_generation: + metric_value_type: int attributes: - ref: http.request.method requirement_level: recommended diff --git a/model/http/registry.yaml b/model/http/registry.yaml index d91c2d8762..64988c684e 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -1,206 +1,214 @@ -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 + stability: development + 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 + + - 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 + stability: development + 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 + + - key: http.response.body.size + type: int + stability: development + 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 + + - 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 + stability: development + 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 + + - 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 + stability: development + 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. + examples: ["active", "idle"] diff --git a/model/http/spans.yaml b/model/http/spans.yaml index dd49374df9..509eaf7684 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -1,30 +1,78 @@ -groups: - - id: span.http.client - type: span - extends: attributes.http.client - span_kind: client +file_format: definition/2 +spans: + - type: span.http.client + kind: client + name: + note: HTTP span name stability: stable brief: > This span represents an outbound HTTP request. note: | There are two ways HTTP client spans can be implemented in an instrumentation: - 1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). In this case, instrumentations SHOULD NOT (also) emit a logical encompassing HTTP client span. - 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 `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. - **Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section. - **Span kind** MUST be `CLIENT`. - **Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section. attributes: - ref: http.request.method sampling_relevant: true + requirement_level: required + - ref: http.response.status_code + requirement_level: + conditionally_required: If and only if one was received/sent. + - ref: error.type + requirement_level: + conditionally_required: If request has ended with an error. + examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] + note: | + If the request fails with an error before response status code was sent or received, + `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) + or a component-specific low cardinality error identifier. + If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), + `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. + The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + The cardinality of `error.type` within one instrumentation library SHOULD be low, but + telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.type` to have high cardinality at query time, when no + additional filters are applied. + If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + - ref: network.protocol.name + examples: ['http', 'spdy'] + requirement_level: + conditionally_required: If not `http` and `network.protocol.version` is set. + - ref: network.protocol.version + examples: ['1.0', '1.1', '2', '3'] + - ref: server.address + sampling_relevant: true + requirement_level: required + note: | + In HTTP/1.1, when the [request target](https://www.rfc-editor.org/rfc/rfc9112.html#name-request-target) + is passed in its [absolute-form](https://www.rfc-editor.org/rfc/rfc9112.html#section-3.2.2), + the `server.address` SHOULD match the host component of the request target. + In all other cases, `server.address` SHOULD match the host component of the + `Host` header in HTTP/1.1 or the `:authority` pseudo-header in HTTP/2 and HTTP/3. + - ref: server.port + sampling_relevant: true + requirement_level: required + note: | + In the case of HTTP/1.1, when the [request target](https://www.rfc-editor.org/rfc/rfc9112.html#name-request-target) + is passed in its [absolute-form](https://www.rfc-editor.org/rfc/rfc9112.html#section-3.2.2), + the `server.port` SHOULD match the port component of the request target. + In all other cases, `server.port` SHOULD match the port component of the + `Host` header in HTTP/1.1 or the `:authority` pseudo-header in HTTP/2 and HTTP/3. + - ref: url.scheme + requirement_level: opt_in + examples: ["http", "https"] + - ref: url.template + requirement_level: opt_in + 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. - ref: http.request.method_original requirement_level: conditionally_required: If and only if it's different than `http.request.method`. @@ -35,16 +83,11 @@ groups: requirement_level: opt_in - ref: http.response.header requirement_level: opt_in - - ref: server.address - sampling_relevant: true - - ref: server.port - sampling_relevant: true - ref: url.full sampling_relevant: true requirement_level: required - ref: user_agent.original requirement_level: opt_in - - ref: url.scheme - ref: network.peer.address - ref: network.peer.port requirement_level: @@ -64,36 +107,82 @@ groups: requirement_level: opt_in - ref: user_agent.synthetic.type requirement_level: opt_in - - - id: span.http.server - type: span - extends: attributes.http.server - span_kind: server + - type: span.http.server + kind: server + name: + note: HTTP span name + stability: stable brief: > This span represents an inbound HTTP request. note: | **Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section. - **Span kind** MUST be `SERVER`. - **Span status:** refer to the [Span Status](/docs/http/http-spans.md#status) section. - stability: stable attributes: - ref: http.request.method sampling_relevant: true + requirement_level: required + - ref: http.response.status_code + requirement_level: + conditionally_required: If and only if one was received/sent. + - ref: error.type + requirement_level: + conditionally_required: If request has ended with an error. + examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] + note: | + If the request fails with an error before response status code was sent or received, + `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) + or a component-specific low cardinality error identifier. + If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), + `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. + The `error.type` value SHOULD be predictable and SHOULD have low cardinality. + Instrumentations SHOULD document the list of errors they report. + The cardinality of `error.type` within one instrumentation library SHOULD be low, but + telemetry consumers that aggregate data from multiple instrumentation libraries and applications + should be prepared for `error.type` to have high cardinality at query time, when no + additional filters are applied. + If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. + - ref: network.protocol.name + examples: ['http', 'spdy'] + requirement_level: + conditionally_required: If not `http` and `network.protocol.version` is set. + - ref: network.protocol.version + examples: ['1.0', '1.1', '2', '3'] + - ref: http.route + requirement_level: + conditionally_required: If and only if it's available + - ref: server.address + sampling_relevant: true + brief: > + Name of the local HTTP server that received the request. + note: > + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + - ref: server.port + sampling_relevant: true + brief: > + Port of the local HTTP server that received the request. + note: > + See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). + requirement_level: + conditionally_required: If available and `server.address` is set. + - ref: url.scheme + sampling_relevant: true + requirement_level: required + examples: ["http", "https"] + note: > + The scheme of the original client request, if known + (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), + [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), + or a similar header). + Otherwise, the scheme of the immediate peer request. - ref: http.request.method_original requirement_level: conditionally_required: If and only if it's different than `http.request.method`. - - ref: http.route - ref: http.request.header sampling_relevant: true requirement_level: opt_in - ref: http.response.header requirement_level: opt_in - - ref: server.address - sampling_relevant: true - - ref: server.port - sampling_relevant: true - ref: network.local.address requirement_level: opt_in brief: Local socket address. Useful in case of a multi-IP host. @@ -118,8 +207,6 @@ groups: requirement_level: conditionally_required: If and only if one was received/sent. sampling_relevant: true - - ref: url.scheme - sampling_relevant: true - ref: user_agent.original sampling_relevant: true - ref: network.peer.address From d9fb64c204ee54af97e5cd645309e751ca781db8 Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Mon, 29 Jun 2026 02:22:04 +0530 Subject: [PATCH 02/11] fix(http): fully migrate to v2 schema and address reviewer feedback --- .chloggen/migrate-http-v2.yaml | 4 + model/http/common.yaml | 12 +- .../http/deprecated/registry-deprecated.yaml | 66 +++---- model/http/events.yaml | 7 + model/http/metrics.yaml | 181 +++++++++++------- model/http/registry.yaml | 38 +--- model/http/spans.yaml | 139 +++----------- 7 files changed, 187 insertions(+), 260 deletions(-) create mode 100644 .chloggen/migrate-http-v2.yaml 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/model/http/common.yaml b/model/http/common.yaml index 89bcc07ae4..f4794714ee 100644 --- a/model/http/common.yaml +++ b/model/http/common.yaml @@ -2,9 +2,7 @@ file_format: definition/2 attribute_groups: - id: attributes.http.common - visibility: public - stability: development - brief: "Describes HTTP attributes." + visibility: internal attributes: - ref: http.request.method requirement_level: required @@ -40,9 +38,7 @@ attribute_groups: examples: ['1.0', '1.1', '2', '3'] - id: attributes.http.client - visibility: public - stability: development - brief: 'HTTP Client attributes' + visibility: internal attributes: - ref_group: attributes.http.common - ref: server.address @@ -72,9 +68,7 @@ attribute_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 - visibility: public - stability: development - brief: 'HTTP Server attributes' + visibility: internal attributes: - ref_group: attributes.http.common - ref: http.route diff --git a/model/http/deprecated/registry-deprecated.yaml b/model/http/deprecated/registry-deprecated.yaml index af1ea38127..7edc69c8d8 100644 --- a/model/http/deprecated/registry-deprecated.yaml +++ b/model/http/deprecated/registry-deprecated.yaml @@ -3,81 +3,73 @@ 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`.' - brief: 'Deprecated, use `http.request.method` instead.' + 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`.' - brief: 'Deprecated, use `http.response.status_code` instead.' + 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`.' - brief: 'Deprecated, use `url.scheme` instead.' + 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`.' - brief: 'Deprecated, use `url.full` instead.' + 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`. - brief: 'Deprecated, use `url.path` and `url.query` instead.' 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`. - brief: 'Deprecated, use `http.request.header.content-length` instead.' 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`. - brief: 'Deprecated, use `http.response.header.content-length` instead.' examples: 3495 - - key: http.client_ip type: string stability: development deprecated: reason: renamed renamed_to: client.address - note: 'Replaced by `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 @@ -87,42 +79,34 @@ attributes: 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 - type: int stability: development deprecated: reason: renamed renamed_to: http.request.body.size - note: 'Replaced by `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 - type: int stability: development deprecated: reason: renamed renamed_to: http.response.body.size - note: 'Replaced by `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`.' + note: "Replaced by server.address." brief: "Deprecated, use `server.address` instead." examples: ['example.com'] - - key: http.flavor - stability: development - deprecated: - reason: uncategorized - note: "Split into `network.protocol.name` and `network.protocol.version`" type: members: - id: http_1_0 @@ -150,15 +134,17 @@ attributes: 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 - stability: development + 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`.' - 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' + note: "Replaced by user_agent.original." + stability: development diff --git a/model/http/events.yaml b/model/http/events.yaml index c793c95a63..9df8ce215a 100644 --- a/model/http/events.yaml +++ b/model/http/events.yaml @@ -1,4 +1,5 @@ file_format: definition/2 + events: - name: http.client.request.exception stability: development @@ -8,10 +9,13 @@ events: from completing successfully. note: > This event SHOULD be recorded when an exception occurs during HTTP client operations. + Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event. + Some HTTP client frameworks generate artificial exceptions for non-successful HTTP status codes (e.g., 404 Not Found). When possible, instrumentations SHOULD NOT record these artificial exceptions, or SHOULD set the severity to DEBUG (severity number 5). + Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding HTTP client span. attributes: @@ -22,6 +26,7 @@ events: requirement_level: conditionally_required: Required if `exception.type` is not set, recommended otherwise. - ref: exception.stacktrace + - name: http.server.request.exception stability: development brief: > @@ -30,7 +35,9 @@ events: the server from successfully handling the request. note: > This event SHOULD be recorded when an exception occurs during HTTP server request processing. + Instrumentations SHOULD set the severity to ERROR (severity number 17) when recording this event. + Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding HTTP server span. attributes: diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index 61889f7f17..60bac6edf5 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -1,54 +1,39 @@ file_format: definition/2 -attribute_groups: - - id: metric_attributes.http.server - visibility: public - stability: development - brief: 'HTTP server metric attributes' - attributes: - - ref_group: attributes.http.server - - ref: user_agent.synthetic.type - requirement_level: opt_in - - - id: metric_attributes.http.client - visibility: public - stability: development - brief: 'HTTP client metric attributes' - attributes: - - ref_group: attributes.http.client - - - id: metric_attributes.http.client.experimental - visibility: public - stability: development - brief: 'HTTP client experimental metric attributes (extends metric_attributes.http.client)' - attributes: - - ref_group: 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. - metrics: - name: http.server.request.duration - stability: stable - brief: "Duration of HTTP server requests." - instrument: histogram - unit: "s" annotations: code_generation: metric_value_type: double + brief: "Duration of HTTP server requests." + instrument: histogram + unit: "s" + stability: stable attributes: - - ref_group: metric_attributes.http.server + - ref_group: attributes.http.server + - ref: server.address + requirement_level: opt_in + note: | + > [!WARNING] + > 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. + - ref: server.port + requirement_level: opt_in + note: | + > [!WARNING] + > 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. + - ref: user_agent.synthetic.type + requirement_level: opt_in - name: http.server.active_requests + annotations: + code_generation: + metric_value_type: int stability: development brief: "Number of active HTTP server requests." instrument: updowncounter unit: "{request}" - annotations: - code_generation: - metric_value_type: int attributes: - ref: http.request.method requirement_level: required @@ -77,84 +62,146 @@ metrics: > to trigger cardinality limits, degrading the usefulness of the metric. - name: http.server.request.body.size + annotations: + code_generation: + metric_value_type: int stability: development brief: "Size of HTTP server request bodies." instrument: histogram unit: "By" - annotations: - code_generation: - metric_value_type: int note: > 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. attributes: - - ref_group: metric_attributes.http.server + - ref_group: attributes.http.server + - ref: server.address + requirement_level: opt_in + note: | + > [!WARNING] + > 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. + - ref: server.port + requirement_level: opt_in + note: | + > [!WARNING] + > 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. + - ref: user_agent.synthetic.type + requirement_level: opt_in - name: http.server.response.body.size + annotations: + code_generation: + metric_value_type: int stability: development brief: "Size of HTTP server response bodies." instrument: histogram unit: "By" - annotations: - code_generation: - metric_value_type: int note: > 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. attributes: - - ref_group: metric_attributes.http.server + - ref_group: attributes.http.server + - ref: server.address + requirement_level: opt_in + note: | + > [!WARNING] + > 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. + - ref: server.port + requirement_level: opt_in + note: | + > [!WARNING] + > 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. + - ref: user_agent.synthetic.type + requirement_level: opt_in - name: http.client.request.duration - stability: stable - brief: "Duration of HTTP client requests." - instrument: histogram - unit: "s" annotations: code_generation: metric_value_type: double + brief: "Duration of HTTP client requests." + instrument: histogram + unit: "s" + stability: stable attributes: - - ref_group: metric_attributes.http.client + - 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). - name: http.client.request.body.size + annotations: + code_generation: + metric_value_type: int stability: development brief: "Size of HTTP client request bodies." instrument: histogram unit: "By" - annotations: - code_generation: - metric_value_type: int note: > 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. attributes: - - ref_group: metric_attributes.http.client.experimental + - 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). + - 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. - name: http.client.response.body.size + annotations: + code_generation: + metric_value_type: int stability: development brief: "Size of HTTP client response bodies." instrument: histogram unit: "By" - annotations: - code_generation: - metric_value_type: int note: > 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. attributes: - - ref_group: metric_attributes.http.client.experimental + - 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). + - 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. - name: http.client.open_connections + annotations: + code_generation: + metric_value_type: int stability: development brief: "Number of outbound HTTP connections that are currently active or idle on the client." instrument: updowncounter unit: "{connection}" - annotations: - code_generation: - metric_value_type: int attributes: - ref: http.connection.state requirement_level: required @@ -171,13 +218,13 @@ metrics: examples: ["http", "https"] - name: http.client.connection.duration + annotations: + code_generation: + metric_value_type: double stability: development brief: "The duration of the successfully established outbound HTTP connections." instrument: histogram unit: "s" - annotations: - code_generation: - metric_value_type: double attributes: - ref: network.peer.address requirement_level: opt_in @@ -192,13 +239,13 @@ metrics: examples: ["http", "https"] - name: http.client.active_requests + annotations: + code_generation: + metric_value_type: int stability: development brief: "Number of active HTTP requests." instrument: updowncounter unit: "{request}" - annotations: - code_generation: - metric_value_type: int attributes: - ref: http.request.method requirement_level: recommended diff --git a/model/http/registry.yaml b/model/http/registry.yaml index 64988c684e..ed25308f40 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -3,13 +3,12 @@ file_format: definition/2 attributes: - key: http.request.body.size type: int - stability: development 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[]] @@ -18,23 +17,17 @@ attributes: 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: @@ -90,31 +83,24 @@ attributes: 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 @@ -125,24 +111,21 @@ attributes: 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 - stability: development 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 - stability: development 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[]] @@ -151,35 +134,28 @@ attributes: 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 - stability: development 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 @@ -189,17 +165,12 @@ attributes: 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 - stability: development type: members: - id: active @@ -211,4 +182,5 @@ attributes: 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 509eaf7684..48ecf98e71 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -1,78 +1,33 @@ file_format: definition/2 + spans: - - type: span.http.client + - type: http.client kind: client name: - note: HTTP span name + note: "{http.request.method}" stability: stable brief: > This span represents an outbound HTTP request. note: | There are two ways HTTP client spans can be implemented in an instrumentation: + 1. Instrumentations SHOULD create an HTTP span for each attempt to send an HTTP request over the wire. In case the request is resent, the resend attempts MUST follow the [HTTP resend spec](#http-request-retries-and-redirects). In this case, instrumentations SHOULD NOT (also) emit a logical encompassing HTTP client span. + 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 `url.full` MUST be the absolute URL that was originally requested, before any HTTP-redirects that may happen when executing the request. + **Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section. + **Span kind** MUST be `CLIENT`. + **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 - requirement_level: required - - ref: http.response.status_code - requirement_level: - conditionally_required: If and only if one was received/sent. - - ref: error.type - requirement_level: - conditionally_required: If request has ended with an error. - examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] - note: | - If the request fails with an error before response status code was sent or received, - `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) - or a component-specific low cardinality error identifier. - If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), - `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. - The `error.type` value SHOULD be predictable and SHOULD have low cardinality. - Instrumentations SHOULD document the list of errors they report. - The cardinality of `error.type` within one instrumentation library SHOULD be low, but - telemetry consumers that aggregate data from multiple instrumentation libraries and applications - should be prepared for `error.type` to have high cardinality at query time, when no - additional filters are applied. - If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. - - ref: network.protocol.name - examples: ['http', 'spdy'] - requirement_level: - conditionally_required: If not `http` and `network.protocol.version` is set. - - ref: network.protocol.version - examples: ['1.0', '1.1', '2', '3'] - - ref: server.address - sampling_relevant: true - requirement_level: required - note: | - In HTTP/1.1, when the [request target](https://www.rfc-editor.org/rfc/rfc9112.html#name-request-target) - is passed in its [absolute-form](https://www.rfc-editor.org/rfc/rfc9112.html#section-3.2.2), - the `server.address` SHOULD match the host component of the request target. - In all other cases, `server.address` SHOULD match the host component of the - `Host` header in HTTP/1.1 or the `:authority` pseudo-header in HTTP/2 and HTTP/3. - - ref: server.port - sampling_relevant: true - requirement_level: required - note: | - In the case of HTTP/1.1, when the [request target](https://www.rfc-editor.org/rfc/rfc9112.html#name-request-target) - is passed in its [absolute-form](https://www.rfc-editor.org/rfc/rfc9112.html#section-3.2.2), - the `server.port` SHOULD match the port component of the request target. - In all other cases, `server.port` SHOULD match the port component of the - `Host` header in HTTP/1.1 or the `:authority` pseudo-header in HTTP/2 and HTTP/3. - - ref: url.scheme - requirement_level: opt_in - examples: ["http", "https"] - - ref: url.template - requirement_level: opt_in - 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. - ref: http.request.method_original requirement_level: conditionally_required: If and only if it's different than `http.request.method`. @@ -83,11 +38,16 @@ spans: requirement_level: opt_in - ref: http.response.header requirement_level: opt_in + - ref: server.address + sampling_relevant: true + - ref: server.port + sampling_relevant: true - ref: url.full sampling_relevant: true requirement_level: required - ref: user_agent.original requirement_level: opt_in + - ref: url.scheme - ref: network.peer.address - ref: network.peer.port requirement_level: @@ -107,82 +67,37 @@ spans: requirement_level: opt_in - ref: user_agent.synthetic.type requirement_level: opt_in - - type: span.http.server + + - type: http.server kind: server name: - note: HTTP span name - stability: stable + note: "{http.request.method} {http.route}" brief: > This span represents an inbound HTTP request. note: | **Span name:** refer to the [Span Name](/docs/http/http-spans.md#name) section. + **Span kind** MUST be `SERVER`. + **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 - requirement_level: required - - ref: http.response.status_code - requirement_level: - conditionally_required: If and only if one was received/sent. - - ref: error.type - requirement_level: - conditionally_required: If request has ended with an error. - examples: ['timeout', 'java.net.UnknownHostException', 'server_certificate_invalid', '500'] - note: | - If the request fails with an error before response status code was sent or received, - `error.type` SHOULD be set to exception type (its fully-qualified class name, if applicable) - or a component-specific low cardinality error identifier. - If response status code was sent or received and status indicates an error according to [HTTP span status definition](/docs/http/http-spans.md), - `error.type` SHOULD be set to the status code number (represented as a string), an exception type (if thrown) or a component-specific error identifier. - The `error.type` value SHOULD be predictable and SHOULD have low cardinality. - Instrumentations SHOULD document the list of errors they report. - The cardinality of `error.type` within one instrumentation library SHOULD be low, but - telemetry consumers that aggregate data from multiple instrumentation libraries and applications - should be prepared for `error.type` to have high cardinality at query time, when no - additional filters are applied. - If the request has completed successfully, instrumentations SHOULD NOT set `error.type`. - - ref: network.protocol.name - examples: ['http', 'spdy'] - requirement_level: - conditionally_required: If not `http` and `network.protocol.version` is set. - - ref: network.protocol.version - examples: ['1.0', '1.1', '2', '3'] - - ref: http.route - requirement_level: - conditionally_required: If and only if it's available - - ref: server.address - sampling_relevant: true - brief: > - Name of the local HTTP server that received the request. - note: > - See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). - - ref: server.port - sampling_relevant: true - brief: > - Port of the local HTTP server that received the request. - note: > - See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). - requirement_level: - conditionally_required: If available and `server.address` is set. - - ref: url.scheme - sampling_relevant: true - requirement_level: required - examples: ["http", "https"] - note: > - The scheme of the original client request, if known - (e.g. from [Forwarded#proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded#proto), - [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), - or a similar header). - Otherwise, the scheme of the immediate peer request. - ref: http.request.method_original requirement_level: conditionally_required: If and only if it's different than `http.request.method`. + - ref: http.route - ref: http.request.header sampling_relevant: true requirement_level: opt_in - ref: http.response.header requirement_level: opt_in + - ref: server.address + sampling_relevant: true + - ref: server.port + sampling_relevant: true - ref: network.local.address requirement_level: opt_in brief: Local socket address. Useful in case of a multi-IP host. @@ -207,6 +122,8 @@ spans: requirement_level: conditionally_required: If and only if one was received/sent. sampling_relevant: true + - ref: url.scheme + sampling_relevant: true - ref: user_agent.original sampling_relevant: true - ref: network.peer.address From b6e0ec3aa1c6a37c90dc6d400eb3744d4320b335 Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Tue, 30 Jun 2026 01:47:00 +0530 Subject: [PATCH 03/11] chore(docs): regenerate registry markdown and add missing requirement_level to spans and events --- docs/README.md | 56 +---------- docs/registry/attributes/README.md | 2 +- docs/registry/attributes/model.md | 144 +++++++++++++++++++++++++++++ model/http/events.yaml | 2 + model/http/spans.yaml | 2 + 5 files changed, 154 insertions(+), 52 deletions(-) create mode 100644 docs/registry/attributes/model.md diff --git a/docs/README.md b/docs/README.md index 10d7eb2e80..31b1e729ed 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,56 +1,10 @@ -# OpenTelemetry semantic conventions +# Registry -The Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it. -The Semantic Conventions specify among other things span names and kind, metric instruments and units as well as attribute names, types, meaning and valid values. For a detailed definition of the Semantic Conventions' scope see [Semantic Conventions Stability](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability). -The benefit to using Semantic Conventions is in following a common naming scheme that can be standardized across a codebase, libraries, and platforms. This allows easier correlation and consumption of data. +This is an automatically generated registry of available semantic conventions. -Semantic Conventions are defined for the following areas: - -* **[General](general/README.md): General Semantic Conventions**. -* [CI/CD](cicd/README.md): Semantic Conventions for CI/CD systems. -* [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries. -* [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification. -* [Database](db/README.md): Semantic Conventions for database operations. -* [Exceptions](exceptions/README.md): Semantic Conventions for exceptions. -* [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations. -* [Feature Flags](feature-flags/README.md): Semantic Conventions for feature flag evaluations. -* [Generative AI](gen-ai/README.md): Moved to the [OpenTelemetry GenAI semantic conventions repository](https://github.com/open-telemetry/semantic-conventions-genai). -* [GraphQL](graphql/README.md): Semantic Conventions for GraphQL implementations. -* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. -* [Messaging](messaging/README.md): Semantic Conventions for messaging operations and systems. -* [Object Stores](object-stores/README.md): Semantic Conventions for object stores operations. -* [RPC](rpc/README.md): Semantic Conventions for RPC client and server operations. -* [System](system/README.md): System Semantic Conventions. - -Semantic Conventions by signals: - -* [Events](general/events.md): Semantic Conventions for event data. -* [Logs](general/logs.md): Semantic Conventions for logs data. -* [Metrics](general/metrics.md): Semantic Conventions for metrics. -* [Profiles](general/profiles.md): Semantic Conventions for profiles. -* [Resource](resource/README.md): Semantic Conventions for resources. -* [Trace](general/trace.md): Semantic Conventions for traces and spans. - -Configuration: - -* [Configuration](configuration/README.md): Semantic convention related configuration options. - -Also see: - -* [How to write semantic conventions](how-to-write-conventions/README.md) -* [Non-normative supplementary information](non-normative/README.md) +- [Attributes](attributes/README.md) +- [Entities](entities/README.md) diff --git a/docs/registry/attributes/README.md b/docs/registry/attributes/README.md index 64c71e2869..8878354ce9 100644 --- a/docs/registry/attributes/README.md +++ b/docs/registry/attributes/README.md @@ -71,7 +71,6 @@ Currently, the following namespaces exist: - [Hardware](hardware.md) - [Heroku](heroku.md) - [Host](host.md) -- [HTTP](http.md) - [iOS](ios.md) - [JSONRPC](jsonrpc.md) - [JVM](jvm.md) @@ -81,6 +80,7 @@ Currently, the following namespaces exist: - [Mainframe](mainframe.md) - [MCP](mcp.md) - [Messaging](messaging.md) +- [Model](model.md) - [Network](network.md) - [NFS](nfs.md) - [NodeJS](nodejs.md) diff --git a/docs/registry/attributes/model.md b/docs/registry/attributes/model.md new file mode 100644 index 0000000000..6f1199a06a --- /dev/null +++ b/docs/registry/attributes/model.md @@ -0,0 +1,144 @@ + + + +# Model + +- [Model HTTP Attributes](#model-http-attributes) +- [Model HTTP Deprecated Registry Deprecated Attributes](#model-http-deprecated-registry-deprecated-attributes) + +## Model HTTP Attributes + + + +**Attributes:** + +| Key | Stability | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | +| `http.connection.state` | ![Development](https://img.shields.io/badge/-development-blue) | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | +| `http.request.body.size` | ![Development](https://img.shields.io/badge/-development-blue) | 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` | +| `http.request.header.` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [1] | `["application/json"]`; `["1.2.3.4", "1.2.3.5"]` | +| `http.request.method` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | +| `http.request.method_original` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | +| `http.request.resend_count` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | int | The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | +| `http.request.size` | ![Development](https://img.shields.io/badge/-development-blue) | int | 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. | `1437` | +| `http.response.body.size` | ![Development](https://img.shields.io/badge/-development-blue) | 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` | +| `http.response.header.` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `["application/json"]`; `["abc", "def"]` | +| `http.response.size` | ![Development](https://img.shields.io/badge/-development-blue) | int | 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. | `1437` | +| `http.response.status_code` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | +| `http.route` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | 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. [5] | `/users/:userID?`; `my-controller/my-action/{id?}` | + +**[1] `http.request.header.`:** 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. + +**[2] `http.request.method`:** 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. + +**[3] `http.request.resend_count`:** 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). + +**[4] `http.response.header.`:** 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. + +**[5] `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. +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. + +--- + +`http.connection.state` 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. + +| Value | Description | Stability | +| --- | --- | --- | +| `active` | active state. | ![Development](https://img.shields.io/badge/-development-blue) | +| `idle` | idle state. | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + +`http.request.method` 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. + +| Value | Description | Stability | +| --- | --- | --- | +| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| `QUERY` | QUERY method. | ![Development](https://img.shields.io/badge/-development-blue) | +| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +## Model HTTP Deprecated Registry Deprecated Attributes + + + +**Attributes:** + +| Key | Stability | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | +| `http.client_ip` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by client.address. | string | Deprecated, use `client.address` instead. | `83.164.160.102` | +| `http.flavor` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split into `network.protocol.name` and `network.protocol.version` | string | Deprecated, use `network.protocol.name` and `network.protocol.version` instead. | `1.0`; `1.1`; `2.0` | +| `http.host` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by one of `server.address`, `client.address` or `http.request.header.host`, depending on the usage. | string | Deprecated, use one of `server.address`, `client.address` or `http.request.header.host` instead, depending on the usage. | `www.example.org` | +| `http.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.request.method. | string | Deprecated, use `http.request.method` instead. | `GET`; `POST`; `HEAD` | +| `http.request_content_length` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.header.content-length`. | int | Deprecated, use `http.request.header.content-length` instead. | `3495` | +| `http.request_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.request.body.size. | int | Deprecated, use `http.request.body.size` instead. | `5493` | +| `http.response_content_length` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.header.content-length`. | int | Deprecated, use `http.response.header.content-length` instead. | `3495` | +| `http.response_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.response.body.size. | int | Deprecated, use `http.response.body.size` instead. | `5493` | +| `http.scheme` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by url.scheme. | string | Deprecated, use `url.scheme` instead. | `http`; `https` | +| `http.server_name` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by server.address. | string | Deprecated, use `server.address` instead. | `example.com` | +| `http.status_code` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.response.status_code. | int | Deprecated, use `http.response.status_code` instead. | `200` | +| `http.target` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split to `url.path` and `url.query`. | string | Deprecated, use `url.path` and `url.query` instead. | `/search?q=OpenTelemetry#SemConv` | +| `http.url` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by url.full. | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | +| `http.user_agent` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by user_agent.original. | string | Deprecated, use `user_agent.original` instead. | `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` | + +--- + +`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. + +| Value | Description | Stability | +| --- | --- | --- | +| `1.0` | HTTP/1.0 | ![Development](https://img.shields.io/badge/-development-blue) | +| `1.1` | HTTP/1.1 | ![Development](https://img.shields.io/badge/-development-blue) | +| `2.0` | HTTP/2 | ![Development](https://img.shields.io/badge/-development-blue) | +| `3.0` | HTTP/3 | ![Development](https://img.shields.io/badge/-development-blue) | +| `QUIC` | QUIC protocol. | ![Development](https://img.shields.io/badge/-development-blue) | +| `SPDY` | SPDY protocol. | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/http/events.yaml b/model/http/events.yaml index 9df8ce215a..d0799e713a 100644 --- a/model/http/events.yaml +++ b/model/http/events.yaml @@ -3,6 +3,7 @@ file_format: definition/2 events: - name: http.client.request.exception stability: development + 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 @@ -29,6 +30,7 @@ events: - name: http.server.request.exception stability: development + 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/spans.yaml b/model/http/spans.yaml index 48ecf98e71..1006b6ac04 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -3,6 +3,7 @@ file_format: definition/2 spans: - type: http.client kind: client + requirement_level: recommended name: note: "{http.request.method}" stability: stable @@ -70,6 +71,7 @@ spans: - type: http.server kind: server + requirement_level: recommended name: note: "{http.request.method} {http.route}" brief: > From c4021e75a68223f7f62e84fd7ba04731d29d962d Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Tue, 30 Jun 2026 02:13:47 +0530 Subject: [PATCH 04/11] fix(http): add missing requirement_levels and fix markdown generation --- docs/registry/attributes/README.md | 1 + docs/registry/attributes/http.md | 38 ++--- docs/registry/attributes/model.md | 144 ------------------ .../http/deprecated/registry-deprecated.yaml | 21 +++ model/http/metrics.yaml | 10 ++ model/http/registry.yaml | 19 +++ 6 files changed, 62 insertions(+), 171 deletions(-) delete mode 100644 docs/registry/attributes/model.md diff --git a/docs/registry/attributes/README.md b/docs/registry/attributes/README.md index 8878354ce9..41151a7e59 100644 --- a/docs/registry/attributes/README.md +++ b/docs/registry/attributes/README.md @@ -71,6 +71,7 @@ Currently, the following namespaces exist: - [Hardware](hardware.md) - [Heroku](heroku.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/http.md index 5f48f1d314..8030f2c781 100644 --- a/docs/registry/attributes/http.md +++ b/docs/registry/attributes/http.md @@ -4,7 +4,7 @@ # HTTP - [HTTP Attributes](#http-attributes) -- [Deprecated HTTP Attributes](#deprecated-http-attributes) +- [HTTP Deprecated Attributes](#http-deprecated-attributes) ## HTTP Attributes @@ -29,16 +29,12 @@ This document defines semantic convention attributes in the HTTP namespace. **[1] `http.request.header.`:** 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` @@ -48,21 +44,16 @@ Examples: 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. @@ -71,15 +62,11 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[4] `http.response.header.`:** 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` @@ -87,12 +74,9 @@ Examples: **[5] `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. 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. @@ -123,7 +107,7 @@ 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 +## HTTP Deprecated Attributes Describes deprecated HTTP attributes. @@ -131,20 +115,20 @@ Describes deprecated HTTP attributes. | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `http.client_ip` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `client.address`. | string | Deprecated, use `client.address` instead. | `83.164.160.102` | +| `http.client_ip` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by client.address. | string | Deprecated, use `client.address` instead. | `83.164.160.102` | | `http.flavor` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split into `network.protocol.name` and `network.protocol.version` | string | Deprecated, use `network.protocol.name` and `network.protocol.version` instead. | `1.0`; `1.1`; `2.0` | | `http.host` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by one of `server.address`, `client.address` or `http.request.header.host`, depending on the usage. | string | Deprecated, use one of `server.address`, `client.address` or `http.request.header.host` instead, depending on the usage. | `www.example.org` | -| `http.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.method`. | string | Deprecated, use `http.request.method` instead. | `GET`; `POST`; `HEAD` | +| `http.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.request.method. | string | Deprecated, use `http.request.method` instead. | `GET`; `POST`; `HEAD` | | `http.request_content_length` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.header.content-length`. | int | Deprecated, use `http.request.header.content-length` instead. | `3495` | -| `http.request_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.body.size`. | int | Deprecated, use `http.request.body.size` instead. | `5493` | +| `http.request_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.request.body.size. | int | Deprecated, use `http.request.body.size` instead. | `5493` | | `http.response_content_length` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.header.content-length`. | int | Deprecated, use `http.response.header.content-length` instead. | `3495` | -| `http.response_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.body.size`. | int | Deprecated, use `http.response.body.size` instead. | `5493` | -| `http.scheme` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `url.scheme`. | string | Deprecated, use `url.scheme` instead. | `http`; `https` | -| `http.server_name` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `server.address`. | string | Deprecated, use `server.address` instead. | `example.com` | -| `http.status_code` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.status_code`. | int | Deprecated, use `http.response.status_code` instead. | `200` | +| `http.response_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.response.body.size. | int | Deprecated, use `http.response.body.size` instead. | `5493` | +| `http.scheme` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by url.scheme. | string | Deprecated, use `url.scheme` instead. | `http`; `https` | +| `http.server_name` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by server.address. | string | Deprecated, use `server.address` instead. | `example.com` | +| `http.status_code` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.response.status_code. | int | Deprecated, use `http.response.status_code` instead. | `200` | | `http.target` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split to `url.path` and `url.query`. | string | Deprecated, use `url.path` and `url.query` instead. | `/search?q=OpenTelemetry#SemConv` | -| `http.url` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `url.full`. | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | -| `http.user_agent` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `user_agent.original`. | string | Deprecated, use `user_agent.original` instead. | `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` | +| `http.url` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by url.full. | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | +| `http.user_agent` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by user_agent.original. | string | Deprecated, use `user_agent.original` instead. | `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` | --- diff --git a/docs/registry/attributes/model.md b/docs/registry/attributes/model.md deleted file mode 100644 index 6f1199a06a..0000000000 --- a/docs/registry/attributes/model.md +++ /dev/null @@ -1,144 +0,0 @@ - - - -# Model - -- [Model HTTP Attributes](#model-http-attributes) -- [Model HTTP Deprecated Registry Deprecated Attributes](#model-http-deprecated-registry-deprecated-attributes) - -## Model HTTP Attributes - - - -**Attributes:** - -| Key | Stability | Value Type | Description | Example Values | -| --- | --- | --- | --- | --- | -| `http.connection.state` | ![Development](https://img.shields.io/badge/-development-blue) | string | State of the HTTP connection in the HTTP connection pool. | `active`; `idle` | -| `http.request.body.size` | ![Development](https://img.shields.io/badge/-development-blue) | 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` | -| `http.request.header.` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [1] | `["application/json"]`; `["1.2.3.4", "1.2.3.5"]` | -| `http.request.method` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | -| `http.request.method_original` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Original HTTP method sent by the client in the request line. | `GeT`; `ACL`; `foo` | -| `http.request.resend_count` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | int | The ordinal number of request resending attempt (for any reason, including redirects). [3] | `3` | -| `http.request.size` | ![Development](https://img.shields.io/badge/-development-blue) | int | 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. | `1437` | -| `http.response.body.size` | ![Development](https://img.shields.io/badge/-development-blue) | 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` | -| `http.response.header.` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `["application/json"]`; `["abc", "def"]` | -| `http.response.size` | ![Development](https://img.shields.io/badge/-development-blue) | int | 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. | `1437` | -| `http.response.status_code` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | -| `http.route` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | 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. [5] | `/users/:userID?`; `my-controller/my-action/{id?}` | - -**[1] `http.request.header.`:** 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. - -**[2] `http.request.method`:** 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. - -**[3] `http.request.resend_count`:** 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). - -**[4] `http.response.header.`:** 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. - -**[5] `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. -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. - ---- - -`http.connection.state` 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. - -| Value | Description | Stability | -| --- | --- | --- | -| `active` | active state. | ![Development](https://img.shields.io/badge/-development-blue) | -| `idle` | idle state. | ![Development](https://img.shields.io/badge/-development-blue) | - ---- - -`http.request.method` 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. - -| Value | Description | Stability | -| --- | --- | --- | -| `_OTHER` | Any HTTP method that the instrumentation has no prior knowledge of. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `CONNECT` | CONNECT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `DELETE` | DELETE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `GET` | GET method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `HEAD` | HEAD method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `OPTIONS` | OPTIONS method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `PATCH` | PATCH method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `POST` | POST method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `PUT` | PUT method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | -| `QUERY` | QUERY method. | ![Development](https://img.shields.io/badge/-development-blue) | -| `TRACE` | TRACE method. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | - -## Model HTTP Deprecated Registry Deprecated Attributes - - - -**Attributes:** - -| Key | Stability | Value Type | Description | Example Values | -| --- | --- | --- | --- | --- | -| `http.client_ip` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by client.address. | string | Deprecated, use `client.address` instead. | `83.164.160.102` | -| `http.flavor` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split into `network.protocol.name` and `network.protocol.version` | string | Deprecated, use `network.protocol.name` and `network.protocol.version` instead. | `1.0`; `1.1`; `2.0` | -| `http.host` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by one of `server.address`, `client.address` or `http.request.header.host`, depending on the usage. | string | Deprecated, use one of `server.address`, `client.address` or `http.request.header.host` instead, depending on the usage. | `www.example.org` | -| `http.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.request.method. | string | Deprecated, use `http.request.method` instead. | `GET`; `POST`; `HEAD` | -| `http.request_content_length` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.header.content-length`. | int | Deprecated, use `http.request.header.content-length` instead. | `3495` | -| `http.request_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.request.body.size. | int | Deprecated, use `http.request.body.size` instead. | `5493` | -| `http.response_content_length` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.header.content-length`. | int | Deprecated, use `http.response.header.content-length` instead. | `3495` | -| `http.response_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.response.body.size. | int | Deprecated, use `http.response.body.size` instead. | `5493` | -| `http.scheme` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by url.scheme. | string | Deprecated, use `url.scheme` instead. | `http`; `https` | -| `http.server_name` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by server.address. | string | Deprecated, use `server.address` instead. | `example.com` | -| `http.status_code` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.response.status_code. | int | Deprecated, use `http.response.status_code` instead. | `200` | -| `http.target` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split to `url.path` and `url.query`. | string | Deprecated, use `url.path` and `url.query` instead. | `/search?q=OpenTelemetry#SemConv` | -| `http.url` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by url.full. | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | -| `http.user_agent` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by user_agent.original. | string | Deprecated, use `user_agent.original` instead. | `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` | - ---- - -`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. - -| Value | Description | Stability | -| --- | --- | --- | -| `1.0` | HTTP/1.0 | ![Development](https://img.shields.io/badge/-development-blue) | -| `1.1` | HTTP/1.1 | ![Development](https://img.shields.io/badge/-development-blue) | -| `2.0` | HTTP/2 | ![Development](https://img.shields.io/badge/-development-blue) | -| `3.0` | HTTP/3 | ![Development](https://img.shields.io/badge/-development-blue) | -| `QUIC` | QUIC protocol. | ![Development](https://img.shields.io/badge/-development-blue) | -| `SPDY` | SPDY protocol. | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/http/deprecated/registry-deprecated.yaml b/model/http/deprecated/registry-deprecated.yaml index 7edc69c8d8..878fbd688c 100644 --- a/model/http/deprecated/registry-deprecated.yaml +++ b/model/http/deprecated/registry-deprecated.yaml @@ -1,5 +1,26 @@ file_format: definition/2 +attribute_groups: + - id: registry.http.deprecated + visibility: public + stability: development + brief: "Describes deprecated HTTP attributes." + attributes: + - ref: http.method + - ref: http.status_code + - ref: http.scheme + - ref: http.url + - ref: http.target + - ref: http.request_content_length + - ref: http.response_content_length + - ref: http.client_ip + - ref: http.host + - ref: http.request_content_length_uncompressed + - ref: http.response_content_length_uncompressed + - ref: http.server_name + - ref: http.flavor + - ref: http.user_agent + attributes: - key: http.method type: string diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index 60bac6edf5..049314bbca 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -2,6 +2,7 @@ file_format: definition/2 metrics: - name: http.server.request.duration + requirement_level: recommended annotations: code_generation: metric_value_type: double @@ -27,6 +28,7 @@ metrics: requirement_level: opt_in - name: http.server.active_requests + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -62,6 +64,7 @@ metrics: > to trigger cardinality limits, degrading the usefulness of the metric. - name: http.server.request.body.size + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -91,6 +94,7 @@ metrics: requirement_level: opt_in - name: http.server.response.body.size + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -120,6 +124,7 @@ metrics: requirement_level: opt_in - name: http.client.request.duration + requirement_level: recommended annotations: code_generation: metric_value_type: double @@ -139,6 +144,7 @@ metrics: See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes). - name: http.client.request.body.size + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -167,6 +173,7 @@ metrics: 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. - name: http.client.response.body.size + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -195,6 +202,7 @@ metrics: 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. - name: http.client.open_connections + requirement_level: recommended annotations: code_generation: metric_value_type: int @@ -218,6 +226,7 @@ metrics: examples: ["http", "https"] - name: http.client.connection.duration + requirement_level: recommended annotations: code_generation: metric_value_type: double @@ -239,6 +248,7 @@ metrics: examples: ["http", "https"] - 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 ed25308f40..0e711c4afe 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -1,5 +1,24 @@ file_format: definition/2 +attribute_groups: + - id: registry.http + visibility: public + stability: stable + brief: "This document defines semantic convention attributes in the HTTP namespace." + attributes: + - ref: http.request.body.size + - ref: http.request.header + - ref: http.request.method + - ref: http.request.method_original + - ref: http.request.resend_count + - ref: http.request.size + - ref: http.response.body.size + - ref: http.response.header + - ref: http.response.size + - ref: http.response.status_code + - ref: http.route + - ref: http.connection.state + attributes: - key: http.request.body.size type: int From 9b17df4c13d59f5890f863e62ce04e72cbd8555e Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Wed, 1 Jul 2026 08:33:44 +0530 Subject: [PATCH 05/11] fix(http): address reviewer feedback, revert attribute_group hack, restore missing note --- docs/README.md | 4 +-- .../http/deprecated/registry-deprecated.yaml | 26 ------------------- model/http/metrics.yaml | 12 +++++++++ model/http/registry.yaml | 17 ++---------- 4 files changed, 16 insertions(+), 43 deletions(-) diff --git a/docs/README.md b/docs/README.md index 31b1e729ed..d6717bb919 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,5 +6,5 @@ weight: -2 This is an automatically generated registry of available semantic conventions. -- [Attributes](attributes/README.md) -- [Entities](entities/README.md) +- [Attributes](registry/attributes/README.md) +- [Entities](registry/entities/README.md) diff --git a/model/http/deprecated/registry-deprecated.yaml b/model/http/deprecated/registry-deprecated.yaml index 878fbd688c..55b40aefd2 100644 --- a/model/http/deprecated/registry-deprecated.yaml +++ b/model/http/deprecated/registry-deprecated.yaml @@ -2,24 +2,7 @@ file_format: definition/2 attribute_groups: - id: registry.http.deprecated - visibility: public - stability: development brief: "Describes deprecated HTTP attributes." - attributes: - - ref: http.method - - ref: http.status_code - - ref: http.scheme - - ref: http.url - - ref: http.target - - ref: http.request_content_length - - ref: http.response_content_length - - ref: http.client_ip - - ref: http.host - - ref: http.request_content_length_uncompressed - - ref: http.response_content_length_uncompressed - - ref: http.server_name - - ref: http.flavor - - ref: http.user_agent attributes: - key: http.method @@ -29,7 +12,6 @@ attributes: deprecated: reason: renamed renamed_to: http.request.method - note: "Replaced by http.request.method." examples: ["GET", "POST", "HEAD"] - key: http.status_code type: int @@ -38,7 +20,6 @@ attributes: deprecated: reason: renamed renamed_to: http.response.status_code - note: "Replaced by http.response.status_code." examples: [200] - key: http.scheme type: string @@ -47,7 +28,6 @@ attributes: deprecated: reason: renamed renamed_to: url.scheme - note: "Replaced by url.scheme." examples: ['http', 'https'] - key: http.url type: string @@ -56,7 +36,6 @@ attributes: 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 @@ -88,7 +67,6 @@ attributes: 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 @@ -105,7 +83,6 @@ attributes: 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 @@ -114,7 +91,6 @@ attributes: 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 @@ -124,7 +100,6 @@ attributes: deprecated: reason: renamed renamed_to: server.address - note: "Replaced by server.address." brief: "Deprecated, use `server.address` instead." examples: ['example.com'] - key: http.flavor @@ -167,5 +142,4 @@ attributes: deprecated: reason: renamed renamed_to: user_agent.original - note: "Replaced by user_agent.original." stability: development diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index 049314bbca..581b78f206 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -15,12 +15,16 @@ metrics: - 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). + > [!WARNING] > 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. - 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). + > [!WARNING] > 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. @@ -81,12 +85,16 @@ metrics: - 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). + > [!WARNING] > 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. - 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). + > [!WARNING] > 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. @@ -111,12 +119,16 @@ metrics: - 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). + > [!WARNING] > 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. - 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). + > [!WARNING] > 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. diff --git a/model/http/registry.yaml b/model/http/registry.yaml index 0e711c4afe..a4c04deaae 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -2,22 +2,7 @@ file_format: definition/2 attribute_groups: - id: registry.http - visibility: public - stability: stable brief: "This document defines semantic convention attributes in the HTTP namespace." - attributes: - - ref: http.request.body.size - - ref: http.request.header - - ref: http.request.method - - ref: http.request.method_original - - ref: http.request.resend_count - - ref: http.request.size - - ref: http.response.body.size - - ref: http.response.header - - ref: http.response.size - - ref: http.response.status_code - - ref: http.route - - ref: http.connection.state attributes: - key: http.request.body.size @@ -41,6 +26,7 @@ attributes: 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"]`. @@ -157,6 +143,7 @@ attributes: 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"]`. From 166e85aa610d03cc98e60029cb39dc82d7422e9f Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Wed, 1 Jul 2026 08:41:20 +0530 Subject: [PATCH 06/11] chore(docs): fix markdownlint errors in generated http.md --- docs/registry/attributes/http.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/registry/attributes/http.md b/docs/registry/attributes/http.md index 8030f2c781..6039346f03 100644 --- a/docs/registry/attributes/http.md +++ b/docs/registry/attributes/http.md @@ -35,6 +35,8 @@ The attribute value MUST consist of either multiple header values as an array of 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` @@ -66,7 +68,9 @@ Users MAY explicitly configure instrumentations to capture them even though it i 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` From d9a7cda41290bbf468bf9cbef595878a8726a57b Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Wed, 1 Jul 2026 08:52:06 +0530 Subject: [PATCH 07/11] fix(http): restore note fields for deprecated attributes and fix MD012 --- docs/registry/attributes/http.md | 1 - model/http/deprecated/registry-deprecated.yaml | 11 +++++++++++ model/http/registry.yaml | 2 ++ 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/registry/attributes/http.md b/docs/registry/attributes/http.md index 6039346f03..21e640010c 100644 --- a/docs/registry/attributes/http.md +++ b/docs/registry/attributes/http.md @@ -36,7 +36,6 @@ or a single-item array containing a possibly comma-concatenated string, dependin 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` diff --git a/model/http/deprecated/registry-deprecated.yaml b/model/http/deprecated/registry-deprecated.yaml index 55b40aefd2..c4f5c78af4 100644 --- a/model/http/deprecated/registry-deprecated.yaml +++ b/model/http/deprecated/registry-deprecated.yaml @@ -2,6 +2,8 @@ file_format: definition/2 attribute_groups: - id: registry.http.deprecated + visibility: internal + stability: development brief: "Describes deprecated HTTP attributes." attributes: @@ -12,6 +14,7 @@ attributes: deprecated: reason: renamed renamed_to: http.request.method + note: "Replaced by http.request.method." examples: ["GET", "POST", "HEAD"] - key: http.status_code type: int @@ -20,6 +23,7 @@ attributes: deprecated: reason: renamed renamed_to: http.response.status_code + note: "Replaced by http.response.status_code." examples: [200] - key: http.scheme type: string @@ -28,6 +32,7 @@ attributes: deprecated: reason: renamed renamed_to: url.scheme + note: "Replaced by url.scheme." examples: ['http', 'https'] - key: http.url type: string @@ -36,6 +41,7 @@ attributes: 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 @@ -67,6 +73,7 @@ attributes: 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 @@ -83,6 +90,7 @@ attributes: 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 @@ -91,6 +99,7 @@ attributes: 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 @@ -100,6 +109,7 @@ attributes: deprecated: reason: renamed renamed_to: server.address + note: "Replaced by server.address." brief: "Deprecated, use `server.address` instead." examples: ['example.com'] - key: http.flavor @@ -142,4 +152,5 @@ attributes: deprecated: reason: renamed renamed_to: user_agent.original + note: "Replaced by user_agent.original." stability: development diff --git a/model/http/registry.yaml b/model/http/registry.yaml index a4c04deaae..001d040581 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -2,6 +2,8 @@ file_format: definition/2 attribute_groups: - id: registry.http + visibility: internal + stability: development brief: "This document defines semantic convention attributes in the HTTP namespace." attributes: From 590d1c8772b7636526e0a8494f596c80b2e28ec8 Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Wed, 1 Jul 2026 20:18:46 +0530 Subject: [PATCH 08/11] fix(http): address maintainer review feedback on duplication, backticks, and redundant groups --- .../http/deprecated/registry-deprecated.yaml | 23 ++- model/http/metrics.yaml | 132 +++++++----------- model/http/registry.yaml | 5 - 3 files changed, 56 insertions(+), 104 deletions(-) diff --git a/model/http/deprecated/registry-deprecated.yaml b/model/http/deprecated/registry-deprecated.yaml index c4f5c78af4..e5663afad3 100644 --- a/model/http/deprecated/registry-deprecated.yaml +++ b/model/http/deprecated/registry-deprecated.yaml @@ -1,10 +1,5 @@ file_format: definition/2 -attribute_groups: - - id: registry.http.deprecated - visibility: internal - stability: development - brief: "Describes deprecated HTTP attributes." attributes: - key: http.method @@ -14,7 +9,7 @@ attributes: deprecated: reason: renamed renamed_to: http.request.method - note: "Replaced by http.request.method." + note: "Replaced by `http.request.method`." examples: ["GET", "POST", "HEAD"] - key: http.status_code type: int @@ -23,7 +18,7 @@ attributes: deprecated: reason: renamed renamed_to: http.response.status_code - note: "Replaced by http.response.status_code." + note: "Replaced by `http.response.status_code`." examples: [200] - key: http.scheme type: string @@ -32,7 +27,7 @@ attributes: deprecated: reason: renamed renamed_to: url.scheme - note: "Replaced by url.scheme." + note: "Replaced by `url.scheme`." examples: ['http', 'https'] - key: http.url type: string @@ -41,7 +36,7 @@ attributes: deprecated: reason: renamed renamed_to: url.full - note: "Replaced by url.full." + note: "Replaced by `url.full`." examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] - key: http.target type: string @@ -73,7 +68,7 @@ attributes: deprecated: reason: renamed renamed_to: client.address - note: "Replaced by client.address." + note: "Replaced by `client.address`." brief: "Deprecated, use `client.address` instead." examples: '83.164.160.102' - key: http.host @@ -90,7 +85,7 @@ attributes: deprecated: reason: renamed renamed_to: http.request.body.size - note: "Replaced by http.request.body.size." + note: "Replaced by `http.request.body.size`." type: int brief: "Deprecated, use `http.request.body.size` instead." examples: 5493 @@ -99,7 +94,7 @@ attributes: deprecated: reason: renamed renamed_to: http.response.body.size - note: "Replaced by http.response.body.size." + note: "Replaced by `http.response.body.size`." type: int brief: "Deprecated, use `http.response.body.size` instead." examples: 5493 @@ -109,7 +104,7 @@ attributes: deprecated: reason: renamed renamed_to: server.address - note: "Replaced by server.address." + note: "Replaced by `server.address`." brief: "Deprecated, use `server.address` instead." examples: ['example.com'] - key: http.flavor @@ -152,5 +147,5 @@ attributes: deprecated: reason: renamed renamed_to: user_agent.original - note: "Replaced by user_agent.original." + note: "Replaced by `user_agent.original`." stability: development diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index 581b78f206..f864505657 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -1,15 +1,9 @@ file_format: definition/2 -metrics: - - name: http.server.request.duration - requirement_level: recommended - annotations: - code_generation: - metric_value_type: double - brief: "Duration of HTTP server requests." - instrument: histogram - unit: "s" - stability: stable +attribute_groups: + - id: metric_attributes.http.server + visibility: internal + brief: 'HTTP server attributes' attributes: - ref_group: attributes.http.server - ref: server.address @@ -31,6 +25,44 @@ metrics: - ref: user_agent.synthetic.type requirement_level: opt_in + - id: metric_attributes.http.client + visibility: internal + brief: 'HTTP client attributes' + 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 + visibility: internal + brief: 'HTTP client experimental attributes' + 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. + +metrics: + - name: http.server.request.duration + requirement_level: recommended + annotations: + code_generation: + metric_value_type: double + brief: "Duration of HTTP server requests." + instrument: histogram + unit: "s" + stability: stable + attributes: + - ref_group: metric_attributes.http.server + - name: http.server.active_requests requirement_level: recommended annotations: @@ -81,25 +113,7 @@ metrics: 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. attributes: - - ref_group: attributes.http.server - - 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). - - > [!WARNING] - > 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. - - 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). - - > [!WARNING] - > 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. - - ref: user_agent.synthetic.type - requirement_level: opt_in + - ref_group: metric_attributes.http.server - name: http.server.response.body.size requirement_level: recommended @@ -115,25 +129,7 @@ metrics: 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. attributes: - - ref_group: attributes.http.server - - 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). - - > [!WARNING] - > 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. - - 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). - - > [!WARNING] - > 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. - - ref: user_agent.synthetic.type - requirement_level: opt_in + - ref_group: metric_attributes.http.server - name: http.client.request.duration requirement_level: recommended @@ -145,15 +141,7 @@ metrics: unit: "s" stability: stable 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). + - ref_group: metric_attributes.http.client - name: http.client.request.body.size requirement_level: recommended @@ -169,20 +157,7 @@ metrics: 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. 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). - - 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. + - ref_group: metric_attributes.http.client.experimental - name: http.client.response.body.size requirement_level: recommended @@ -198,20 +173,7 @@ metrics: 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. 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). - - 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. + - ref_group: metric_attributes.http.client.experimental - name: http.client.open_connections requirement_level: recommended diff --git a/model/http/registry.yaml b/model/http/registry.yaml index 001d040581..a8852f0e8a 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -1,10 +1,5 @@ file_format: definition/2 -attribute_groups: - - id: registry.http - visibility: internal - stability: development - brief: "This document defines semantic convention attributes in the HTTP namespace." attributes: - key: http.request.body.size From f973efb31d14bece11d50cd223bae1f191825d33 Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Wed, 1 Jul 2026 23:08:55 +0530 Subject: [PATCH 09/11] fix(http): remove brief property from internal attribute groups --- model/http/metrics.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/model/http/metrics.yaml b/model/http/metrics.yaml index f864505657..9d88e73b19 100644 --- a/model/http/metrics.yaml +++ b/model/http/metrics.yaml @@ -3,7 +3,6 @@ file_format: definition/2 attribute_groups: - id: metric_attributes.http.server visibility: internal - brief: 'HTTP server attributes' attributes: - ref_group: attributes.http.server - ref: server.address @@ -27,7 +26,6 @@ attribute_groups: - id: metric_attributes.http.client visibility: internal - brief: 'HTTP client attributes' attributes: - ref_group: attributes.http.client - ref: server.address @@ -41,7 +39,6 @@ attribute_groups: - id: metric_attributes.http.client.experimental visibility: internal - brief: 'HTTP client experimental attributes' attributes: - ref_group: metric_attributes.http.client - ref: url.template From 26b6fd9f216b22cdb5ae7d64f05f6a3b5fb9ec99 Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Thu, 2 Jul 2026 14:55:27 +0530 Subject: [PATCH 10/11] fix(http): apply maintainer changes for docs CI block --- docs/README.md | 56 +++++++++++++++++-- docs/registry/attributes/README.md | 3 +- docs/registry/attributes/{http.md => home.md} | 45 +++++++++------ model/http/registry.yaml | 15 +++++ 4 files changed, 96 insertions(+), 23 deletions(-) rename docs/registry/attributes/{http.md => home.md} (90%) diff --git a/docs/README.md b/docs/README.md index d6717bb919..10d7eb2e80 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,10 +1,56 @@ -# Registry +# OpenTelemetry semantic conventions -This is an automatically generated registry of available semantic conventions. +The Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it. +The Semantic Conventions specify among other things span names and kind, metric instruments and units as well as attribute names, types, meaning and valid values. For a detailed definition of the Semantic Conventions' scope see [Semantic Conventions Stability](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability). +The benefit to using Semantic Conventions is in following a common naming scheme that can be standardized across a codebase, libraries, and platforms. This allows easier correlation and consumption of data. -- [Attributes](registry/attributes/README.md) -- [Entities](registry/entities/README.md) +Semantic Conventions are defined for the following areas: + +* **[General](general/README.md): General Semantic Conventions**. +* [CI/CD](cicd/README.md): Semantic Conventions for CI/CD systems. +* [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries. +* [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification. +* [Database](db/README.md): Semantic Conventions for database operations. +* [Exceptions](exceptions/README.md): Semantic Conventions for exceptions. +* [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations. +* [Feature Flags](feature-flags/README.md): Semantic Conventions for feature flag evaluations. +* [Generative AI](gen-ai/README.md): Moved to the [OpenTelemetry GenAI semantic conventions repository](https://github.com/open-telemetry/semantic-conventions-genai). +* [GraphQL](graphql/README.md): Semantic Conventions for GraphQL implementations. +* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. +* [Messaging](messaging/README.md): Semantic Conventions for messaging operations and systems. +* [Object Stores](object-stores/README.md): Semantic Conventions for object stores operations. +* [RPC](rpc/README.md): Semantic Conventions for RPC client and server operations. +* [System](system/README.md): System Semantic Conventions. + +Semantic Conventions by signals: + +* [Events](general/events.md): Semantic Conventions for event data. +* [Logs](general/logs.md): Semantic Conventions for logs data. +* [Metrics](general/metrics.md): Semantic Conventions for metrics. +* [Profiles](general/profiles.md): Semantic Conventions for profiles. +* [Resource](resource/README.md): Semantic Conventions for resources. +* [Trace](general/trace.md): Semantic Conventions for traces and spans. + +Configuration: + +* [Configuration](configuration/README.md): Semantic convention related configuration options. + +Also see: + +* [How to write semantic conventions](how-to-write-conventions/README.md) +* [Non-normative supplementary information](non-normative/README.md) diff --git a/docs/registry/attributes/README.md b/docs/registry/attributes/README.md index 41151a7e59..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) @@ -81,7 +81,6 @@ Currently, the following namespaces exist: - [Mainframe](mainframe.md) - [MCP](mcp.md) - [Messaging](messaging.md) -- [Model](model.md) - [Network](network.md) - [NFS](nfs.md) - [NodeJS](nodejs.md) diff --git a/docs/registry/attributes/http.md b/docs/registry/attributes/home.md similarity index 90% rename from docs/registry/attributes/http.md rename to docs/registry/attributes/home.md index 21e640010c..6e53014093 100644 --- a/docs/registry/attributes/http.md +++ b/docs/registry/attributes/home.md @@ -1,14 +1,14 @@ -# HTTP +# Home -- [HTTP Attributes](#http-attributes) -- [HTTP Deprecated Attributes](#http-deprecated-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:** @@ -29,11 +29,14 @@ This document defines semantic convention attributes in the HTTP namespace. **[1] `http.request.header.`:** 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` @@ -45,16 +48,21 @@ Examples: 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. @@ -63,7 +71,9 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[4] `http.response.header.`:** 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. @@ -77,9 +87,12 @@ Examples: **[5] `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. 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. @@ -110,28 +123,28 @@ 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) | -## HTTP Deprecated Attributes +## Home Weaver Source HTTP Deprecated Registry Deprecated Attributes -Describes deprecated HTTP attributes. + **Attributes:** | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `http.client_ip` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by client.address. | string | Deprecated, use `client.address` instead. | `83.164.160.102` | +| `http.client_ip` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `client.address`. | string | Deprecated, use `client.address` instead. | `83.164.160.102` | | `http.flavor` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split into `network.protocol.name` and `network.protocol.version` | string | Deprecated, use `network.protocol.name` and `network.protocol.version` instead. | `1.0`; `1.1`; `2.0` | | `http.host` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by one of `server.address`, `client.address` or `http.request.header.host`, depending on the usage. | string | Deprecated, use one of `server.address`, `client.address` or `http.request.header.host` instead, depending on the usage. | `www.example.org` | -| `http.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.request.method. | string | Deprecated, use `http.request.method` instead. | `GET`; `POST`; `HEAD` | +| `http.method` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.method`. | string | Deprecated, use `http.request.method` instead. | `GET`; `POST`; `HEAD` | | `http.request_content_length` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.header.content-length`. | int | Deprecated, use `http.request.header.content-length` instead. | `3495` | -| `http.request_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.request.body.size. | int | Deprecated, use `http.request.body.size` instead. | `5493` | +| `http.request_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.request.body.size`. | int | Deprecated, use `http.request.body.size` instead. | `5493` | | `http.response_content_length` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.header.content-length`. | int | Deprecated, use `http.response.header.content-length` instead. | `3495` | -| `http.response_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.response.body.size. | int | Deprecated, use `http.response.body.size` instead. | `5493` | -| `http.scheme` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by url.scheme. | string | Deprecated, use `url.scheme` instead. | `http`; `https` | -| `http.server_name` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by server.address. | string | Deprecated, use `server.address` instead. | `example.com` | -| `http.status_code` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by http.response.status_code. | int | Deprecated, use `http.response.status_code` instead. | `200` | +| `http.response_content_length_uncompressed` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.body.size`. | int | Deprecated, use `http.response.body.size` instead. | `5493` | +| `http.scheme` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `url.scheme`. | string | Deprecated, use `url.scheme` instead. | `http`; `https` | +| `http.server_name` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `server.address`. | string | Deprecated, use `server.address` instead. | `example.com` | +| `http.status_code` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `http.response.status_code`. | int | Deprecated, use `http.response.status_code` instead. | `200` | | `http.target` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Split to `url.path` and `url.query`. | string | Deprecated, use `url.path` and `url.query` instead. | `/search?q=OpenTelemetry#SemConv` | -| `http.url` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by url.full. | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | -| `http.user_agent` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by user_agent.original. | string | Deprecated, use `user_agent.original` instead. | `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` | +| `http.url` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `url.full`. | string | Deprecated, use `url.full` instead. | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | +| `http.user_agent` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `user_agent.original`. | string | Deprecated, use `user_agent.original` instead. | `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` | --- diff --git a/model/http/registry.yaml b/model/http/registry.yaml index a8852f0e8a..c4c8ed4d4e 100644 --- a/model/http/registry.yaml +++ b/model/http/registry.yaml @@ -18,17 +18,21 @@ attributes: 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 @@ -85,16 +89,21 @@ attributes: 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. @@ -136,12 +145,15 @@ attributes: 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` @@ -168,9 +180,12 @@ attributes: 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 From 440e3089d60a9c6273f3608893b016cf1b567ec9 Mon Sep 17 00:00:00 2001 From: Dipanshu Singh Date: Sat, 4 Jul 2026 07:52:44 +0530 Subject: [PATCH 11/11] fix(http): use link to docs for span name note --- model/http/spans.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/model/http/spans.yaml b/model/http/spans.yaml index 1006b6ac04..3787aed5e1 100644 --- a/model/http/spans.yaml +++ b/model/http/spans.yaml @@ -5,7 +5,7 @@ spans: kind: client requirement_level: recommended name: - note: "{http.request.method}" + note: "refer to the [Span Name](/docs/http/http-spans.md#name) section." stability: stable brief: > This span represents an outbound HTTP request. @@ -73,7 +73,7 @@ spans: kind: server requirement_level: recommended name: - note: "{http.request.method} {http.route}" + note: "refer to the [Span Name](/docs/http/http-spans.md#name) section." brief: > This span represents an inbound HTTP request. note: |