From 156f9424fe5d83d8543119224c3af6ae9af518cf Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 19 Jun 2023 14:35:45 -0700 Subject: [PATCH] Make server.address and server.port to opt-in on HTTP server metrics (#109) --- CHANGELOG.md | 3 + semantic_conventions/http-common.yaml | 3 - semantic_conventions/metrics/http.yaml | 104 ++++++++++-------- .../semantic_conventions/http-metrics.md | 24 ++-- 4 files changed, 68 insertions(+), 66 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ff5be5d0f8..32b10a0d12 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -86,3 +86,6 @@ release. ([#56](https://github.com/open-telemetry/semantic-conventions/pull/56)) - Make `url.query` conditionally required for HTTP spans. ([#118](https://github.com/open-telemetry/semantic-conventions/pull/118)) +- Change `server.address` and `server.port` requirement levels on HTTP server metrics + from `required` to `opt_in`. + ([#109](https://github.com/open-telemetry/semantic-conventions/pull/109)) diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml index 06e326f65e..5cef876d6c 100644 --- a/semantic_conventions/http-common.yaml +++ b/semantic_conventions/http-common.yaml @@ -65,7 +65,6 @@ groups: SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. - ref: server.address - requirement_level: required brief: > Name of the local HTTP server that received the request. note: | @@ -80,8 +79,6 @@ groups: SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - ref: server.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: | diff --git a/semantic_conventions/metrics/http.yaml b/semantic_conventions/metrics/http.yaml index 6a5089b6de..5a90d7ca45 100644 --- a/semantic_conventions/metrics/http.yaml +++ b/semantic_conventions/metrics/http.yaml @@ -1,17 +1,60 @@ groups: - - id: metric.http.server.duration - type: metric - metric_name: http.server.duration - brief: "Measures the duration of inbound HTTP requests." - instrument: histogram - unit: "s" + - id: metric_attributes.http.server + type: attribute_group + brief: 'HTTP server attributes' extends: attributes.http.server + attributes: + - ref: server.address + brief: > + Name of the local HTTP server that received the request. + requirement_level: opt_in + 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: server.port + brief: > + Port of the local HTTP server that received the request. + requirement_level: opt_in + 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 + # todo (lmolkova) build tools don't populate grandparent attributes + - ref: http.request.method + - ref: http.response.status_code + - ref: network.protocol.name + - ref: network.protocol.version + + - id: metric_attributes.http.client + type: attribute_group + brief: 'HTTP client attributes' + extends: attributes.http.client attributes: # todo (lmolkova) build tools don't populate grandparent attributes - ref: http.request.method - ref: http.response.status_code - ref: network.protocol.name - ref: network.protocol.version + - ref: server.socket.address + + - id: metric.http.server.duration + type: metric + metric_name: http.server.duration + brief: "Measures the duration of inbound HTTP requests." + instrument: histogram + unit: "s" + extends: metric_attributes.http.server - id: metric.http.server.active_requests type: metric @@ -25,7 +68,7 @@ groups: requirement_level: required examples: ["http", "https"] - ref: server.address - requirement_level: required + requirement_level: opt_in brief: > Name of the local HTTP server that received the request. note: | @@ -40,8 +83,7 @@ groups: SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. - ref: server.port - requirement_level: - conditionally_required: If not default (`80` for `http` scheme, `443` for `https`). + requirement_level: opt_in brief: > Port of the local HTTP server that received the request. note: | @@ -58,14 +100,7 @@ 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.request.method - - ref: http.response.status_code - - ref: network.protocol.name - - ref: network.protocol.version + extends: metric_attributes.http.server - id: metric.http.server.response.size type: metric @@ -73,13 +108,7 @@ 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.request.method - - ref: http.response.status_code - - ref: network.protocol.name - - ref: network.protocol.version + extends: metric_attributes.http.server - id: metric.http.client.duration type: metric @@ -87,27 +116,15 @@ groups: brief: "Measures the duration of outbound HTTP requests." instrument: histogram unit: "s" - extends: attributes.http.client - attributes: - - ref: http.request.method - - ref: http.response.status_code - - ref: network.protocol.name - - ref: network.protocol.version - - ref: server.socket.address + extends: metric_attributes.http.client + - id: metric.http.client.request.size type: metric metric_name: http.client.request.size 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.request.method - - ref: http.response.status_code - - ref: network.protocol.name - - ref: network.protocol.version - - ref: server.socket.address + extends: metric_attributes.http.client - id: metric.http.client.response.size type: metric @@ -115,11 +132,4 @@ 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.request.method - - ref: http.response.status_code - - ref: network.protocol.name - - ref: network.protocol.version - - ref: server.socket.address + extends: metric_attributes.http.client diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 250357fc0f..63d106b01f 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -77,8 +77,8 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Opt-In | +| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Opt-In | | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. @@ -102,8 +102,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi - 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`). ### Metric: `http.server.active_requests` @@ -120,8 +118,8 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Conditionally Required: [3] | +| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [1] | `example.com` | Opt-In | +| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [2] | `80`; `8080`; `443` | Opt-In | | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** Determined by using the first of the following that applies @@ -140,8 +138,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi - 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 - -**[3]:** If not default (`80` for `http` scheme, `443` for `https`). ### Metric: `http.server.request.size` @@ -162,8 +158,8 @@ This metric is optional. | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Opt-In | +| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Opt-In | | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. @@ -187,8 +183,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi - 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`). ### Metric: `http.server.response.size` @@ -209,8 +203,8 @@ This metric is optional. | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../../trace/semantic_conventions/span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [2] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Required | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [3] | `example.com` | Opt-In | +| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [4] | `80`; `8080`; `443` | Opt-In | | `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. @@ -234,8 +228,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi - 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 Client