From 3a0a197f4cbbccd7653500127410918baa89d98d Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 13 Feb 2023 16:00:14 -0800 Subject: [PATCH] Use attribute_group for cross-signal HTTP attributes (#3183) --- .markdown_link_check_config.json | 6 + semantic_conventions/http-common.yaml | 120 ++++++++++ semantic_conventions/logs/events.yaml | 2 +- semantic_conventions/logs/log-exception.yaml | 2 +- semantic_conventions/metrics/http.yaml | 209 +----------------- semantic_conventions/trace/faas.yaml | 2 +- semantic_conventions/trace/general.yaml | 2 +- semantic_conventions/trace/http.yaml | 105 +++------ semantic_conventions/trace/messaging.yaml | 15 +- .../semantic_conventions/http-metrics.md | 180 ++++++++++----- .../trace/semantic_conventions/http.md | 28 ++- 11 files changed, 313 insertions(+), 358 deletions(-) create mode 100644 semantic_conventions/http-common.yaml diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json index 96d7455c2..dac3ae97b 100644 --- a/.markdown_link_check_config.json +++ b/.markdown_link_check_config.json @@ -4,6 +4,12 @@ "pattern": "^https://github\\.com/open-telemetry/opentelemetry-specification/(issues|pull)" } ], + "replacementPatterns": [ + { + "pattern": "^/", + "replacement": "{{BASEURL}}/" + } + ], "retryOn429": true, "aliveStatusCodes": [ 200, diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml new file mode 100644 index 000000000..8d1bf1944 --- /dev/null +++ b/semantic_conventions/http-common.yaml @@ -0,0 +1,120 @@ +groups: + - id: attributes.http.common + type: attribute_group + brief: "Describes HTTP attributes." + prefix: http + attributes: + - id: method + type: string + requirement_level: required + brief: 'HTTP request method.' + examples: ["GET", "POST", "HEAD"] + - id: status_code + type: int + requirement_level: + conditionally_required: If and only if one was received/sent. + brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' + examples: [200] + - id: flavor + type: + # Default value: `true`. If false, it helps the code gen tool to + # encode checks that only accept the listed values. + allow_custom_values: true + members: + - id: http_1_0 + value: '1.0' + brief: 'HTTP/1.0' + - id: http_1_1 + value: '1.1' + brief: 'HTTP/1.1' + - id: http_2_0 + value: '2.0' + brief: 'HTTP/2' + - id: http_3_0 + value: '3.0' + brief: 'HTTP/3' + - id: spdy + value: 'SPDY' + brief: 'SPDY protocol.' + - id: quic + value: 'QUIC' + brief: 'QUIC protocol.' + brief: 'Kind of HTTP protocol used.' + note: > + If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` + is `QUIC`, in which case `IP.UDP` is assumed. + + - id: attributes.http.client + prefix: http + type: attribute_group + brief: 'HTTP Client spans attributes' + attributes: + - ref: net.peer.name + requirement_level: required + brief: > + Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: | + Determined by using the first of the following that applies + + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form + - Host identifier of the `Host` header + + SHOULD NOT be set if capturing it would require an extra DNS lookup. + - ref: net.peer.port + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + brief: > + Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. + note: > + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match + URI port identifier, otherwise it MUST match `Host` header port identifier. + + - id: attributes.http.server + prefix: http + type: attribute_group + brief: 'HTTP Server spans attributes' + attributes: + - id: scheme + type: string + brief: 'The URI scheme identifying the used protocol.' + requirement_level: required + examples: ["http", "https"] + - id: route + type: string + requirement_level: + conditionally_required: If and only if it's available + brief: > + The matched route (path template in the format used by the respective server framework). See note below + examples: ['/users/:userID?', '{controller}/{action}/{id?}'] + note: > + MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. + + SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. + - ref: net.host.name + requirement_level: required + brief: > + Name of the local HTTP server that received the request. + note: | + Determined by using the first of the following that applies + + - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only + include host identifier. + - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. + - Host identifier of the `Host` header + + SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. + + - ref: net.host.port + requirement_level: + conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + brief: > + Port of the local HTTP server that received the request. + note: | + Determined by using the first of the following that applies + + - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. + - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) + if it's sent in absolute-form. + - Port identifier of the `Host` header diff --git a/semantic_conventions/logs/events.yaml b/semantic_conventions/logs/events.yaml index 7d7d80f88..f3398c9ac 100644 --- a/semantic_conventions/logs/events.yaml +++ b/semantic_conventions/logs/events.yaml @@ -1,6 +1,6 @@ groups: - id: event - type: span + type: attribute_group prefix: event brief: > This document defines attributes for Events represented using Log Records. diff --git a/semantic_conventions/logs/log-exception.yaml b/semantic_conventions/logs/log-exception.yaml index 94c52ba80..d0b251552 100644 --- a/semantic_conventions/logs/log-exception.yaml +++ b/semantic_conventions/logs/log-exception.yaml @@ -1,6 +1,6 @@ groups: - id: log-exception - type: span + type: attribute_group prefix: exception brief: > This document defines attributes for exceptions represented using Log diff --git a/semantic_conventions/metrics/http.yaml b/semantic_conventions/metrics/http.yaml index 6d88aea06..cb23f27e9 100644 --- a/semantic_conventions/metrics/http.yaml +++ b/semantic_conventions/metrics/http.yaml @@ -5,51 +5,12 @@ groups: brief: "Measures the duration of inbound HTTP requests." instrument: histogram unit: "ms" + extends: attributes.http.server attributes: + # todo (lmolkova) build tools don't populate grandparent attributes - ref: http.method - requirement_level: required - - ref: http.scheme - requirement_level: required - - ref: http.route - requirement_level: - conditionally_required: If and only if it's available - brief: > - The matched route (path template in the format used by the respective server framework). See note below - examples: ['/users/:userID?', '{controller}/{action}/{id?}'] - note: > - MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. - - SHOULD include the [application root](../../trace/semantic_conventions/http.md#http-server-definitions) if there is one. - ref: http.status_code - requirement_level: - conditionally_required: If and only if one was received/sent. - ref: http.flavor - - ref: net.host.name - requirement_level: required - brief: > - Name of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - The [primary server name](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Host identifier of the `Host` header - - SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - - ref: net.host.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - Port identifier of the [primary server host](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Port identifier of the `Host` header - id: metric.http.server.active_requests type: metric @@ -59,10 +20,8 @@ groups: unit: "{requests}" attributes: - ref: http.method - requirement_level: required + - ref: http.status_code - ref: http.scheme - requirement_level: required - - ref: http.flavor - ref: net.host.name requirement_level: required brief: > @@ -70,13 +29,14 @@ groups: note: | Determined by using the first of the following that applies - - The [primary server name](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only + - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Host identifier of the `Host` header SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. + - ref: net.host.port requirement_level: conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). @@ -85,7 +45,7 @@ groups: note: | Determined by using the first of the following that applies - - Port identifier of the [primary server host](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. + - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header @@ -96,52 +56,13 @@ groups: brief: "Measures the size of HTTP request messages (compressed)." instrument: histogram unit: "By" + extends: attributes.http.server # TODO (trask) below attributes are identical to above in metric.http.server.duration attributes: + # todo (lmolkova) build tools don't populate grandparent attributes - ref: http.method - requirement_level: required - - ref: http.scheme - requirement_level: required - - ref: http.route - requirement_level: - conditionally_required: If and only if it's available - brief: > - The matched route (path template in the format used by the respective server framework). See note below - examples: ['/users/:userID?', '{controller}/{action}/{id?}'] - note: > - MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. - - SHOULD include the [application root](../../trace/semantic_conventions/http.md#http-server-definitions) if there is one. - ref: http.status_code - requirement_level: - conditionally_required: If and only if one was received/sent. - ref: http.flavor - - ref: net.host.name - requirement_level: required - brief: > - Name of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - The [primary server name](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Host identifier of the `Host` header - - SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - - ref: net.host.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - Port identifier of the [primary server host](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Port identifier of the `Host` header - id: metric.http.server.response.size type: metric @@ -149,52 +70,12 @@ groups: brief: "Measures the size of HTTP response messages (compressed)." instrument: histogram unit: "By" + extends: attributes.http.server # TODO (trask) below attributes are identical to above in metric.http.server.duration attributes: - ref: http.method - requirement_level: required - - ref: http.scheme - requirement_level: required - - ref: http.route - requirement_level: - conditionally_required: If and only if it's available - brief: > - The matched route (path template in the format used by the respective server framework). See note below - examples: ['/users/:userID?', '{controller}/{action}/{id?}'] - note: > - MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. - - SHOULD include the [application root](../../trace/semantic_conventions/http.md#http-server-definitions) if there is one. - ref: http.status_code - requirement_level: - conditionally_required: If and only if one was received/sent. - ref: http.flavor - - ref: net.host.name - requirement_level: required - brief: > - Name of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - The [primary server name](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only - include host identifier. - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Host identifier of the `Host` header - - SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - - ref: net.host.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port of the local HTTP server that received the request. - note: | - Determined by using the first of the following that applies - - - Port identifier of the [primary server host](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form. - - Port identifier of the `Host` header - id: metric.http.client.duration type: metric @@ -202,33 +83,11 @@ groups: brief: "Measures the duration of outbound HTTP requests." instrument: histogram unit: "ms" + extends: attributes.http.client attributes: - ref: http.method - requirement_level: required - ref: http.status_code - requirement_level: - conditionally_required: If and only if one was received/sent. - ref: http.flavor - - ref: net.peer.name - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - SHOULD NOT be set if capturing it would require an extra DNS lookup. - - ref: net.peer.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. - ref: net.sock.peer.addr - id: metric.http.client.request.size @@ -237,34 +96,12 @@ groups: brief: "Measures the size of HTTP request messages (compressed)." instrument: histogram unit: "By" + extends: attributes.http.client # TODO (trask) below attributes are identical to above in metric.http.client.duration attributes: - ref: http.method - requirement_level: required - ref: http.status_code - requirement_level: - conditionally_required: If and only if one was received/sent. - ref: http.flavor - - ref: net.peer.name - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - SHOULD NOT be set if capturing it would require an extra DNS lookup. - - ref: net.peer.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. - ref: net.sock.peer.addr - id: metric.http.client.response.size @@ -273,32 +110,10 @@ groups: brief: "Measures the size of HTTP response messages (compressed)." instrument: histogram unit: "By" + extends: attributes.http.client # TODO (trask) below attributes are identical to above in metric.http.client.duration attributes: - ref: http.method - requirement_level: required - ref: http.status_code - requirement_level: - conditionally_required: If and only if one was received/sent. - ref: http.flavor - - ref: net.peer.name - requirement_level: required - brief: > - Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: | - Determined by using the first of the following that applies - - - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) - if it's sent in absolute-form - - Host identifier of the `Host` header - - SHOULD NOT be set if capturing it would require an extra DNS lookup. - - ref: net.peer.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). - brief: > - Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. - note: > - When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match - URI port identifier, otherwise it MUST match `Host` header port identifier. - ref: net.sock.peer.addr diff --git a/semantic_conventions/trace/faas.yaml b/semantic_conventions/trace/faas.yaml index fac000a7c..ff4963b16 100644 --- a/semantic_conventions/trace/faas.yaml +++ b/semantic_conventions/trace/faas.yaml @@ -95,7 +95,7 @@ groups: Semantic Convention for FaaS triggered as a response to some data source operation such as a database or filesystem read/write. constraints: - - include: http.server + - include: trace.http.server - id: faas_span.pubsub type: span diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index 4491cc102..544034429 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -1,7 +1,7 @@ groups: - id: network prefix: net - type: span + type: attribute_group brief: > These attributes may be used for any network related operation. attributes: diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index 6b8736e88..6b2eefbea 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -1,52 +1,13 @@ groups: - - id: http + - id: trace.http.common prefix: http - type: span + extends: attributes.http.common + type: attribute_group brief: 'This document defines semantic conventions for HTTP client and server Spans.' note: > These conventions can be used for http and https schemes and various HTTP versions like 1.1, 2 and SPDY. attributes: - - id: method - type: string - requirement_level: required - brief: 'HTTP request method.' - sampling_relevant: true - examples: ["GET", "POST", "HEAD"] - - id: status_code - type: int - requirement_level: - conditionally_required: If and only if one was received/sent. - brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' - examples: [200] - - id: flavor - type: - # Default value: `true`. If false, it helps the code gen tool to - # encode checks that only accept the listed values. - allow_custom_values: true - members: - - id: http_1_0 - value: '1.0' - brief: 'HTTP/1.0' - - id: http_1_1 - value: '1.1' - brief: 'HTTP/1.1' - - id: http_2_0 - value: '2.0' - brief: 'HTTP/2' - - id: http_3_0 - value: '3.0' - brief: 'HTTP/3' - - id: spdy - value: 'SPDY' - brief: 'SPDY protocol.' - - id: quic - value: 'QUIC' - brief: 'QUIC protocol.' - brief: 'Kind of HTTP protocol used.' - note: > - If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` - is `QUIC`, in which case `IP.UDP` is assumed. - id: user_agent type: string brief: 'Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client.' @@ -65,18 +26,18 @@ groups: is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. examples: 3495 + - ref: http.method + sampling_relevant: true - ref: net.sock.peer.addr - ref: net.sock.peer.port - ref: net.sock.peer.name - ref: net.sock.family examples: ['inet', 'inet6'] - constraints: - - include: network - - id: http.client + - id: trace.http.client prefix: http type: span - extends: http + extends: attributes.http.client span_kind: client brief: 'Semantic Convention for HTTP Client' attributes: @@ -91,9 +52,20 @@ groups: In such case the attribute's value should be `https://www.example.com/`. sampling_relevant: true examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] + - id: resend_count + type: int + brief: > + 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). + requirement_level: + recommended: if and only if request was retried. + examples: 3 - ref: net.peer.name - requirement_level: required sampling_relevant: true + requirement_level: required brief: > Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. note: | @@ -113,48 +85,20 @@ groups: note: > When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - - id: resend_count - 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). - requirement_level: - recommended: if and only if request was retried. - examples: 3 - - id: http.server + - id: trace.http.server prefix: http type: span - extends: http + extends: attributes.http.server span_kind: server brief: 'Semantic Convention for HTTP Server' attributes: - - id: scheme - type: string - brief: 'The URI scheme identifying the used protocol.' - requirement_level: required - sampling_relevant: true - examples: ["http", "https"] - id: target type: string brief: 'The full request target as passed in a HTTP request line or equivalent.' requirement_level: required sampling_relevant: true examples: ['/path/12314/?q=ddds'] - - id: route - type: string - requirement_level: - conditionally_required: If and only if it's available - brief: > - The matched route (path template in the format used by the respective server framework). See note below - examples: ['/users/:userID?', '{controller}/{action}/{id?}'] - note: > - MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. - - SHOULD include the [application root](#http-server-definitions) if there is one. - id: client_ip type: string brief: > @@ -173,6 +117,8 @@ groups: one is at least somewhat confident that the address is not that of the closest proxy. examples: '83.164.160.102' + - ref: http.scheme + sampling_relevant: true - ref: net.host.name requirement_level: required sampling_relevant: true @@ -181,7 +127,7 @@ groups: note: | Determined by using the first of the following that applies - - The [primary server name](#http-server-definitions) of the matched virtual host. MUST only + - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -198,11 +144,10 @@ groups: note: | Determined by using the first of the following that applies - - Port identifier of the [primary server host](#http-server-definitions) of the matched virtual host. + - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header - - ref: net.sock.host.addr requirement_level: optional - ref: net.sock.host.port diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml index 83b049f45..e89f6b6f9 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -1,8 +1,7 @@ groups: - id: messaging.message prefix: messaging - # todo (https://github.com/open-telemetry/build-tools/issues/123) - type: span + type: attribute_group brief: 'Semantic convention describing per-message attributes populated on messaging spans or links.' attributes: - ref: messaging.destination.name @@ -30,8 +29,7 @@ groups: - id: messaging.destination prefix: messaging.destination - # todo (https://github.com/open-telemetry/build-tools/issues/123) - type: span + type: attribute_group brief: 'Semantic convention for attributes that describe messaging destination on broker' attributes: - id: name @@ -71,8 +69,7 @@ groups: - id: messaging.source prefix: messaging.source - # todo (https://github.com/open-telemetry/build-tools/issues/123) - type: span + type: attribute_group brief: 'Semantic convention for attributes that describe messaging source on broker' attributes: - id: name @@ -270,7 +267,7 @@ groups: - id: messaging.rabbitmq prefix: messaging.rabbitmq - type: span + type: attribute_group extends: messaging brief: > Attributes for RabbitMQ @@ -285,7 +282,7 @@ groups: - id: messaging.kafka prefix: messaging.kafka - type: span + type: attribute_group extends: messaging brief: > Attributes for Apache Kafka @@ -334,7 +331,7 @@ groups: - id: messaging.rocketmq prefix: messaging.rocketmq - type: span + type: attribute_group extends: messaging brief: > Attributes for Apache RocketMQ diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 627aa466e..be603a309 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -24,25 +24,25 @@ This metric is required. | `http.server.duration` | Histogram | `ms` | Measures the duration of inbound HTTP requests. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.flavor`](../../trace/semantic_conventions/http.md) | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | -| [`http.method`](../../trace/semantic_conventions/http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`http.route`](../../trace/semantic_conventions/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [2] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`http.scheme`](../../trace/semantic_conventions/http.md) | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | -| [`http.status_code`](../../trace/semantic_conventions/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| `http.flavor` | string | Kind of HTTP protocol used. [2] | `1.0` | Recommended | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | | [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | -**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. +**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. -**[2]:** 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](../../trace/semantic_conventions/http.md#http-server-definitions) if there is one. +**[2]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. **[3]:** Determined by using the first of the following that applies -- The [primary server name](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -52,12 +52,23 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[4]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header **[5]:** If not default (`80` for `http` scheme, `443` for `https`). + +`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 | +|---|---| +| `1.0` | HTTP/1.0 | +| `1.1` | HTTP/1.1 | +| `2.0` | HTTP/2 | +| `3.0` | HTTP/3 | +| `SPDY` | SPDY protocol. | +| `QUIC` | QUIC protocol. | ### Metric: `http.server.active_requests` @@ -70,20 +81,18 @@ This metric is optional. | `http.server.active_requests` | UpDownCounter | `{requests}` | Measures the number of concurrent HTTP requests that are currently in-flight. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.flavor`](../../trace/semantic_conventions/http.md) | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | -| [`http.method`](../../trace/semantic_conventions/http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`http.scheme`](../../trace/semantic_conventions/http.md) | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | -| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `localhost` | Required | -| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `8080` | Conditionally Required: [4] | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `localhost` | Required | +| [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `8080` | Conditionally Required: [3] | -**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. +**[1]:** Determined by using the first of the following that applies -**[2]:** Determined by using the first of the following that applies - -- The [primary server name](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -91,14 +100,14 @@ This metric is optional. SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[3]:** Determined by using the first of the following that applies +**[2]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header -**[4]:** If not default (`80` for `http` scheme, `443` for `https`). +**[3]:** If not default (`80` for `http` scheme, `443` for `https`). ### Metric: `http.server.request.size` @@ -111,25 +120,25 @@ This metric is optional. | `http.server.request.size` | Histogram | `By` | Measures the size of HTTP request messages (compressed). | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.flavor`](../../trace/semantic_conventions/http.md) | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | -| [`http.method`](../../trace/semantic_conventions/http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`http.route`](../../trace/semantic_conventions/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [2] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`http.scheme`](../../trace/semantic_conventions/http.md) | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | -| [`http.status_code`](../../trace/semantic_conventions/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| `http.flavor` | string | Kind of HTTP protocol used. [2] | `1.0` | Recommended | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | | [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | -**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. +**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. -**[2]:** 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](../../trace/semantic_conventions/http.md#http-server-definitions) if there is one. +**[2]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. **[3]:** Determined by using the first of the following that applies -- The [primary server name](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -139,12 +148,23 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[4]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header **[5]:** If not default (`80` for `http` scheme, `443` for `https`). + +`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 | +|---|---| +| `1.0` | HTTP/1.0 | +| `1.1` | HTTP/1.1 | +| `2.0` | HTTP/2 | +| `3.0` | HTTP/3 | +| `SPDY` | SPDY protocol. | +| `QUIC` | QUIC protocol. | ### Metric: `http.server.response.size` @@ -157,25 +177,25 @@ This metric is optional. | `http.server.response.size` | Histogram | `By` | Measures the size of HTTP response messages (compressed). | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.flavor`](../../trace/semantic_conventions/http.md) | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | -| [`http.method`](../../trace/semantic_conventions/http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`http.route`](../../trace/semantic_conventions/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [2] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`http.scheme`](../../trace/semantic_conventions/http.md) | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | -| [`http.status_code`](../../trace/semantic_conventions/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | +| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| `http.flavor` | string | Kind of HTTP protocol used. [2] | `1.0` | Recommended | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`net.host.name`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | | [`net.host.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | -**[1]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. +**[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. -**[2]:** 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](../../trace/semantic_conventions/http.md#http-server-definitions) if there is one. +**[2]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. **[3]:** Determined by using the first of the following that applies -- The [primary server name](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -185,12 +205,23 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[4]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](../../trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header **[5]:** If not default (`80` for `http` scheme, `443` for `https`). + +`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 | +|---|---| +| `1.0` | HTTP/1.0 | +| `1.1` | HTTP/1.1 | +| `2.0` | HTTP/2 | +| `3.0` | HTTP/3 | +| `SPDY` | SPDY protocol. | +| `QUIC` | QUIC protocol. | ## HTTP Client @@ -205,12 +236,12 @@ This metric is required. | `http.client.duration` | Histogram | `ms` | Measures the duration of outbound HTTP requests. | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.flavor`](../../trace/semantic_conventions/http.md) | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | -| [`http.method`](../../trace/semantic_conventions/http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`http.status_code`](../../trace/semantic_conventions/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | | [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | @@ -228,6 +259,17 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. **[4]:** If not default (`80` for `http` scheme, `443` for `https`). + +`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 | +|---|---| +| `1.0` | HTTP/1.0 | +| `1.1` | HTTP/1.1 | +| `2.0` | HTTP/2 | +| `3.0` | HTTP/3 | +| `SPDY` | SPDY protocol. | +| `QUIC` | QUIC protocol. | ### Metric: `http.client.request.size` @@ -240,12 +282,12 @@ This metric is optional. | `http.client.request.size` | Histogram | `By` | Measures the size of HTTP request messages (compressed). | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.flavor`](../../trace/semantic_conventions/http.md) | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | -| [`http.method`](../../trace/semantic_conventions/http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`http.status_code`](../../trace/semantic_conventions/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | | [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | @@ -263,6 +305,17 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. **[4]:** If not default (`80` for `http` scheme, `443` for `https`). + +`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 | +|---|---| +| `1.0` | HTTP/1.0 | +| `1.1` | HTTP/1.1 | +| `2.0` | HTTP/2 | +| `3.0` | HTTP/3 | +| `SPDY` | SPDY protocol. | +| `QUIC` | QUIC protocol. | ### Metric: `http.client.response.size` @@ -275,12 +328,12 @@ This metric is optional. | `http.client.response.size` | Histogram | `By` | Measures the size of HTTP response messages (compressed). | - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`http.flavor`](../../trace/semantic_conventions/http.md) | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | -| [`http.method`](../../trace/semantic_conventions/http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`http.status_code`](../../trace/semantic_conventions/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | +| `http.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | | [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | | [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | @@ -298,4 +351,15 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[3]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. **[4]:** If not default (`80` for `http` scheme, `443` for `https`). + +`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 | +|---|---| +| `1.0` | HTTP/1.0 | +| `1.1` | HTTP/1.1 | +| `2.0` | HTTP/2 | +| `3.0` | HTTP/3 | +| `SPDY` | SPDY protocol. | +| `QUIC` | QUIC protocol. | diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 10b808fa3..8bfc9bbfb 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -62,15 +62,15 @@ The common attributes listed in this section apply to both HTTP clients and serv the specific attributes listed in the [HTTP client](#http-client) and [HTTP server](#http-server) sections below. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | `http.flavor` | string | Kind of HTTP protocol used. [1] | `1.0` | Recommended | | `http.user_agent` | string | Value of the [HTTP User-Agent](https://www.rfc-editor.org/rfc/rfc9110.html#field.user-agent) header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Recommended | | `http.request_content_length` | int | The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | | `http.response_content_length` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` | Recommended | +| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | | [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet`; `inet6` | Conditionally Required: [2] | | [`net.sock.peer.addr`](span-general.md) | string | Remote socket peer address: IPv4 or IPv6 for internet protocols, path for local communication, [etc](https://man7.org/linux/man-pages/man7/address_families.7.html). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [3] | @@ -98,6 +98,14 @@ Following attributes MUST be provided **at span creation time** (when provided a | `3.0` | HTTP/3 | | `SPDY` | SPDY protocol. | | `QUIC` | QUIC protocol. | + +`net.sock.family` 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 | +|---|---| +| `inet` | IPv4 address | +| `inet6` | IPv6 address | +| `unix` | Unix domain socket path | It is recommended to also use the general [socket-level attributes][] - `net.sock.peer.addr` when available, `net.sock.peer.name` and `net.sock.peer.port` when don't match `net.peer.name` and `net.peer.port` (if [intermediary](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.7) is detected). @@ -128,7 +136,7 @@ For an HTTP client span, `SpanKind` MUST be `Client`. If set, `http.url` must be the originally requested URL, before any HTTP-redirects that may happen when executing the request. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Required | @@ -233,20 +241,20 @@ Given an inbound request for a route (e.g. `"/users/:userID?"`) the `name` attri If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | -| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds` | Required | | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds` | Required | | `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | Recommended | +| `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | [`net.host.name`](span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | | [`net.host.port`](span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | | [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Optional | | [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [6] | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. -SHOULD include the [application root](#http-server-definitions) if there is one. +SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. **[2]:** This is not necessarily the same as `net.sock.peer.addr`, which would identify the network-level peer, which may be a proxy. @@ -262,7 +270,7 @@ the closest proxy. **[3]:** Determined by using the first of the following that applies -- The [primary server name](#http-server-definitions) of the matched virtual host. MUST only +- The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. @@ -272,7 +280,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[4]:** Determined by using the first of the following that applies -- Port identifier of the [primary server host](#http-server-definitions) of the matched virtual host. +- Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header @@ -283,8 +291,8 @@ SHOULD NOT be set if only IP address is available and capturing name would requi Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* `http.scheme` * `http.target` +* `http.scheme` * [`net.host.name`](span-general.md) * [`net.host.port`](span-general.md)