From a4fd4311b62ab515855d1407699b5ba7d054612f Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Tue, 27 Jun 2023 15:29:01 +0200 Subject: [PATCH 1/5] Moved HTTP semantic conventions to a dedicated topic-based structure Signed-off-by: Alexander Wert --- semantic_conventions/http-common.yaml | 6 +- semantic_conventions/metrics/http.yaml | 8 +- semantic_conventions/trace/http.yaml | 4 +- specification/README.md | 18 ++++ specification/http/README.md | 38 +++++++++ .../http-metrics.md | 82 +++++++++---------- .../http.md => http/http-spans.md} | 50 +++++------ .../metrics/semantic_conventions/README.md | 2 +- .../trace/semantic_conventions/README.md | 2 +- .../trace/semantic_conventions/faas.md | 4 +- .../instrumentation/aws-lambda.md | 6 +- .../trace/semantic_conventions/rpc.md | 2 +- 12 files changed, 139 insertions(+), 83 deletions(-) create mode 100644 specification/README.md create mode 100644 specification/http/README.md rename specification/{metrics/semantic_conventions => http}/http-metrics.md (78%) rename specification/{trace/semantic_conventions/http.md => http/http-spans.md} (85%) diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml index 3a4ed4dc62..5f7fdd58f6 100644 --- a/semantic_conventions/http-common.yaml +++ b/semantic_conventions/http-common.yaml @@ -111,14 +111,14 @@ groups: 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. + SHOULD include the [application root](/specification/http/http-spans.md#http-server-definitions) if there is one. - ref: server.address 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 + - The [primary server name](/specification/http/http-spans.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. @@ -132,7 +132,7 @@ groups: 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 [primary server host](/specification/http/http-spans.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/metrics/http.yaml b/semantic_conventions/metrics/http.yaml index 5a90d7ca45..cb39118bd6 100644 --- a/semantic_conventions/metrics/http.yaml +++ b/semantic_conventions/metrics/http.yaml @@ -11,7 +11,7 @@ groups: 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 + - The [primary server name](/specification/http/http-spans.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. @@ -26,7 +26,7 @@ groups: 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 [primary server host](/specification/http/http-spans.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 @@ -74,7 +74,7 @@ groups: 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 + - The [primary server name](/specification/http/http-spans.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. @@ -89,7 +89,7 @@ groups: 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 [primary server host](/specification/http/http-spans.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/trace/http.yaml b/semantic_conventions/trace/http.yaml index 9694cae7d4..65f53216e6 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -100,7 +100,7 @@ groups: 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 + - The [primary server name](/specification/http/http-spans.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. @@ -116,7 +116,7 @@ groups: 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 [primary server host](/specification/http/http-spans.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/specification/README.md b/specification/README.md new file mode 100644 index 0000000000..52cfe0620b --- /dev/null +++ b/specification/README.md @@ -0,0 +1,18 @@ +# Semantic Conventions + +**Status**: [Mixed][DocumentStatus] + +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 attribute names, types, meaning and valid values, and provide descriptions and example usage. +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. + +Semantic Conventions are defined for the following areas: +* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. + +Semantic Conventions by signals: +* [Resource](resource/semantic_conventions/README.md): Semantic Conventions for resources. +* [Trace](trace/semantic_conventions/README.md): Semantic Conventions for traces and spans. +* [Metrics](metrics/semantic_conventions/README.md): Semantic Conventions for metrics. +* [Logs](logs/semantic_conventions/README.md): Semantic Conventions for logs and event data. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/http/README.md b/specification/http/README.md new file mode 100644 index 0000000000..d5c5424c27 --- /dev/null +++ b/specification/http/README.md @@ -0,0 +1,38 @@ +# Semantic conventions for HTTP + +**Status**: [Experimental, Feature-freeze][DocumentStatus] + +This document defines semantic conventions for HTTP spans, metrics and logs. +They can be used for http and https schemes +and various HTTP versions like 1.1, 2 and SPDY. + +> **Warning** +> Existing HTTP instrumentations that are using +> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/http/http-spans.md) +> (or prior): +> +> * SHOULD NOT change the version of the HTTP or networking attributes that they emit +> until the HTTP semantic conventions are marked stable (HTTP stabilization will +> include stabilization of a core set of networking attributes which are also used +> in HTTP instrumentations). +> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` +> in the existing major version which is a comma-separated list of values. +> The only values defined so far are: +> * `http` - emit the new, stable HTTP and networking attributes, +> and stop emitting the old experimental HTTP and networking attributes +> that the instrumentation emitted previously. +> * `http/dup` - emit both the old and the stable HTTP and networking attributes, +> allowing for a seamless transition. +> * The default behavior (in the absence of one of these values) is to continue +> emitting whatever version of the old experimental HTTP and networking attributes +> the instrumentation was emitting previously. +> * SHOULD maintain (security patching at a minimum) the existing major version +> for at least six months after it starts emitting both sets of attributes. +> * SHOULD drop the environment variable in the next major version (stable +> next major version SHOULD NOT be released prior to October 1, 2023). + +Semantic conventions for HTTP are defined for the following signals: +* [HTTP Spans](http-spans.md): Semantic Conventions for HTTP client and server *spans*. +* [HTTP Metrics](http-metrics.md): Semantic Conventions for HTTP client and server *metrics*. + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/http/http-metrics.md similarity index 78% rename from specification/metrics/semantic_conventions/http-metrics.md rename to specification/http/http-metrics.md index 6cee733125..d5833da467 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/http/http-metrics.md @@ -28,7 +28,7 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > **Warning** > Existing HTTP instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) +> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/http/http-metrics.md) > (or prior): > > * SHOULD NOT change the version of the HTTP or networking attributes that they emit @@ -77,14 +77,14 @@ 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.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.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `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. [3] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`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. [3] | `3.1.1` | Recommended | +| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | +| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `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. -SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. +SHOULD include the [application root](/specification/http/http-spans.md#http-server-definitions) if there is one. **[2]:** 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) @@ -106,7 +106,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[4]:** 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 +- The [primary server name](/specification/http/http-spans.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. @@ -116,7 +116,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** 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 [primary server host](/specification/http/http-spans.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 @@ -153,8 +153,8 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | +| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In | +| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [3] | `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]:** HTTP request method value SHOULD be "known" to the instrumentation. @@ -175,7 +175,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[2]:** 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 +- The [primary server name](/specification/http/http-spans.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,7 +185,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[3]:** 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 [primary server host](/specification/http/http-spans.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 @@ -224,14 +224,14 @@ This metric is optional. | `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.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `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. [3] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`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. [3] | `3.1.1` | Recommended | +| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | +| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `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. -SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. +SHOULD include the [application root](/specification/http/http-spans.md#http-server-definitions) if there is one. **[2]:** 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) @@ -253,7 +253,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[4]:** 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 +- The [primary server name](/specification/http/http-spans.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. @@ -263,7 +263,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** 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 [primary server host](/specification/http/http-spans.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 @@ -302,14 +302,14 @@ This metric is optional. | `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.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | | `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. [3] | `3.1.1` | Recommended | -| [`server.address`](../../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | -| [`server.port`](../../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Opt-In | +| [`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. [3] | `3.1.1` | Recommended | +| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Opt-In | +| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `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. -SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. +SHOULD include the [application root](/specification/http/http-spans.md#http-server-definitions) if there is one. **[2]:** 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) @@ -331,7 +331,7 @@ Tracing instrumentations that do so, MUST also set `http.request.method_original **[4]:** 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 +- The [primary server name](/specification/http/http-spans.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. @@ -341,7 +341,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** 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 [primary server host](/specification/http/http-spans.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 @@ -387,11 +387,11 @@ 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.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `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 | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`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 | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | **[1]:** 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) @@ -456,11 +456,11 @@ This metric is optional. |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `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 | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`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 | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | **[1]:** 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) @@ -525,11 +525,11 @@ This metric is optional. |---|---|---|---|---| | `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | | `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 | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | -| [`server.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`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 | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `example.com` | Required | +| [`server.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | **[1]:** 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) diff --git a/specification/trace/semantic_conventions/http.md b/specification/http/http-spans.md similarity index 85% rename from specification/trace/semantic_conventions/http.md rename to specification/http/http-spans.md index 64e57ca3cb..c5a666a454 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/http/http-spans.md @@ -30,7 +30,7 @@ and various HTTP versions like 1.1, 2 and SPDY. > **Warning** > Existing HTTP instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) +> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/http/http-spans.md) > (or prior): > > * SHOULD NOT change the version of the HTTP or networking attributes that they emit @@ -96,10 +96,10 @@ sections below. | `http.request.body.size` | 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.body.size` | 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.request.method` | string | HTTP request method. [2] | `GET`; `POST`; `HEAD` | Required | -| [`network.protocol.name`](span-general.md) | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `http`; `spdy` | Recommended: if not default (`http`). | -| [`network.protocol.version`](span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | Recommended | -| [`network.transport`](span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] | -| [`network.type`](span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | +| [`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. | `http`; `spdy` | Recommended: if not default (`http`). | +| [`network.protocol.version`](../trace/semantic_conventions/span-general.md) | string | Version of the application layer protocol used. See note below. [3] | `1.0`; `1.1`; `2.0` | Recommended | +| [`network.transport`](../trace/semantic_conventions/span-general.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Conditionally Required: [4] | +| [`network.type`](../trace/semantic_conventions/span-general.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended | | `user_agent.original` | 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 | **[1]:** If and only if it's different than `http.request.method`. @@ -193,11 +193,11 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `http.resend_count` | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | -| [`server.address`](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 | -| [`server.port`](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] | -| [`server.socket.address`](span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](span-general.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended: If different than `server.address`. | -| [`server.socket.port`](span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | +| [`server.address`](../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 | +| [`server.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] | +| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Physical server IP address or Unix socket address. If set from the client, should simply use the socket's peer address, and not attempt to find any actual server IP (i.e., if set from client, this may represent some proxy server instead of the logical server). | `10.5.3.2` | Recommended: If different than `server.address`. | +| [`server.socket.domain`](../trace/semantic_conventions/span-general.md) | string | The domain name of an immediate peer. [5] | `proxy.example.com` | Recommended: If different than `server.address`. | +| [`server.socket.port`](../trace/semantic_conventions/span-general.md) | int | Physical server port. | `16456` | Recommended: If different than `server.port`. | | `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | **[1]:** 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). @@ -223,8 +223,8 @@ If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: -* [`server.address`](span-general.md) -* [`server.port`](span-general.md) +* [`server.address`](../trace/semantic_conventions/span-general.md) +* [`server.port`](../trace/semantic_conventions/span-general.md) * `url.full` @@ -323,20 +323,20 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `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 | -| [`client.address`](span-general.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended | -| [`client.port`](span-general.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended | -| [`client.socket.address`](span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | -| [`server.address`](span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Recommended | -| [`server.port`](span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | -| [`server.socket.address`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | -| [`server.socket.port`](span-general.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | +| [`client.address`](../trace/semantic_conventions/span-general.md) | string | Client address - unix domain socket name, IPv4 or IPv6 address. [2] | `83.164.160.102` | Recommended | +| [`client.port`](../trace/semantic_conventions/span-general.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [3] | `65123` | Recommended | +| [`client.socket.address`](../trace/semantic_conventions/span-general.md) | string | Immediate client peer address - unix domain socket name, IPv4 or IPv6 address. | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | +| [`client.socket.port`](../trace/semantic_conventions/span-general.md) | int | Immediate client peer port number | `35555` | Recommended: If different than `client.port`. | +| [`server.address`](../trace/semantic_conventions/span-general.md) | string | Name of the local HTTP server that received the request. [4] | `example.com` | Recommended | +| [`server.port`](../trace/semantic_conventions/span-general.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | +| [`server.socket.address`](../trace/semantic_conventions/span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.5.3.2` | Opt-In | +| [`server.socket.port`](../trace/semantic_conventions/span-general.md) | int | Local socket port. Useful in case of a multi-port host. | `16456` | Opt-In | | `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | | `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | | `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. -SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one. +SHOULD include the [application root](/specification/http/http-spans.md#http-server-definitions) if there is one. **[2]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. @@ -344,7 +344,7 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/ **[4]:** 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 +- The [primary server name](/specification/http/http-spans.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. @@ -354,7 +354,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** 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 [primary server host](/specification/http/http-spans.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 @@ -367,8 +367,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: -* [`server.address`](span-general.md) -* [`server.port`](span-general.md) +* [`server.address`](../trace/semantic_conventions/span-general.md) +* [`server.port`](../trace/semantic_conventions/span-general.md) * `url.path` * `url.query` * `url.scheme` diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index 5c33d27ec2..d72e784def 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -24,7 +24,7 @@ linkTitle: Semantic Conventions The following semantic conventions surrounding metrics are defined: -* [HTTP](http-metrics.md): For HTTP client and server metrics. +* [HTTP](/specification/http/http-metrics.md): For HTTP client and server metrics. * [RPC](rpc-metrics.md): For RPC client and server metrics. * [Database](database-metrics.md): For SQL and NoSQL client metrics. * [System](system-metrics.md): For standard system metrics. diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md index db72375a15..2f13673a57 100644 --- a/specification/trace/semantic_conventions/README.md +++ b/specification/trace/semantic_conventions/README.md @@ -16,7 +16,7 @@ can still be easily correlated and cross-analyzed. The following semantic conventions for spans are defined: * [General](span-general.md): General semantic attributes that may be used in describing different kinds of operations. -* [HTTP](http.md): For HTTP client and server spans. +* [HTTP](/specification/http/http-spans.md): For HTTP client and server spans. * [Database](database.md): For SQL and NoSQL client call spans. * [RPC/RMI](rpc.md): For remote procedure call (e.g., gRPC) spans. * [Messaging](messaging.md): For messaging systems (queues, publish/subscribe, etc.) spans. diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index 54076663fa..ad358e6b76 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/trace/semantic_conventions/faas.md @@ -30,7 +30,7 @@ See also the [additional instructions for instrumenting AWS Lambda](instrumentat ## General Attributes -Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](http.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. +Span `name` should be set to the function name being executed. Depending on the value of the `faas.trigger` attribute, additional attributes MUST be set. For example, an `http` trigger SHOULD follow the [HTTP Server semantic conventions](/specification/http/http-spans.md#http-server-semantic-conventions). For more information, refer to the [Function Trigger Type](#function-trigger-type) section. If Spans following this convention are produced, a Resource of type `faas` MUST exist following the [Resource semantic convention](../../resource/semantic_conventions/faas.md#function-as-a-service). @@ -211,7 +211,7 @@ FaaS instrumentations that produce `faas` spans with trigger `datasource`, SHOUL ### HTTP -The function responsibility is to provide an answer to an inbound HTTP request. The `faas` span SHOULD follow the recommendations described in the [HTTP Server semantic conventions](http.md#http-server-semantic-conventions). +The function responsibility is to provide an answer to an inbound HTTP request. The `faas` span SHOULD follow the recommendations described in the [HTTP Server semantic conventions](/specification/http/http-spans.md#http-server-semantic-conventions). ### PubSub diff --git a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md index ea59a171a8..3d3611b2c3 100644 --- a/specification/trace/semantic_conventions/instrumentation/aws-lambda.md +++ b/specification/trace/semantic_conventions/instrumentation/aws-lambda.md @@ -3,7 +3,7 @@ **Status**: [Experimental][DocumentStatus] This document defines how to apply semantic conventions when instrumenting an AWS Lambda request handler. AWS -Lambda largely follows the conventions for [FaaS][faas] while [HTTP](../http.md) conventions are also +Lambda largely follows the conventions for [FaaS][faas] while [HTTP](/specification/http/http-spans.md) conventions are also applicable when handlers are for HTTP requests. There are a variety of triggers for Lambda functions, and this document will grow over time to cover all the @@ -78,11 +78,11 @@ configuration for a REST API, in which case only a deserialized body payload is gateway is configured to proxy to the Lambda function, the instrumented request handler will have access to all the information about the HTTP request in the form of an API Gateway Proxy Request Event. -The Lambda span name and the [`http.route` span attribute](../http.md#http-server-semantic-conventions) SHOULD +The Lambda span name and the [`http.route` span attribute](/specification/http/http-spans.md#http-server-semantic-conventions) SHOULD be set to the [resource property][] from the proxy request event, which corresponds to the user configured HTTP route instead of the function name. -[`faas.trigger`][faas] MUST be set to `http`. [HTTP attributes](../http.md) SHOULD be set based on the +[`faas.trigger`][faas] MUST be set to `http`. [HTTP attributes](/specification/http/http-spans.md) SHOULD be set based on the available information in the Lambda event initiated by the proxy request. `http.scheme` is available as the `x-forwarded-proto` header in the Lambda event. Refer to the [input event format][] for more details. diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 9a1f2ce927..cb00687111 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -197,7 +197,7 @@ The event name MUST be `message`. ### Distinction from HTTP spans -HTTP calls can generally be represented using just [HTTP spans](./http.md). +HTTP calls can generally be represented using just [HTTP spans](/specification/http/http-spans.md). If they address a particular remote service and method known to the caller, i.e., when it is a remote procedure call transported over HTTP, the `rpc.*` attributes might be added additionally on that span, or in a separate RPC span that is a parent of the transporting HTTP call. Note that _method_ in this context is about the called remote procedure and _not_ the HTTP verb (GET, POST, etc.). From da286998899dd141c31d4b6e72086838c5cb0769 Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Tue, 27 Jun 2023 15:40:00 +0200 Subject: [PATCH 2/5] minor clarification on intermediate navigation Signed-off-by: Alexander Wert --- specification/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/README.md b/specification/README.md index 52cfe0620b..878001c8b0 100644 --- a/specification/README.md +++ b/specification/README.md @@ -8,6 +8,7 @@ The benefit to using Semantic Conventions is in following a common naming scheme Semantic Conventions are defined for the following areas: * [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. +* *Other areas can be found in the signal specific Semantic Conventions below* Semantic Conventions by signals: * [Resource](resource/semantic_conventions/README.md): Semantic Conventions for resources. From 146d19ef349aa5aac548dea7afe68ea1386f83b0 Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Tue, 27 Jun 2023 15:44:19 +0200 Subject: [PATCH 3/5] fixed markdownlint issues Signed-off-by: Alexander Wert --- specification/README.md | 4 +++- specification/http/README.md | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/specification/README.md b/specification/README.md index 878001c8b0..4992c37104 100644 --- a/specification/README.md +++ b/specification/README.md @@ -2,15 +2,17 @@ **Status**: [Mixed][DocumentStatus] -The Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it. +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 attribute names, types, meaning and valid values, and provide descriptions and example usage. 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. Semantic Conventions are defined for the following areas: + * [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations. * *Other areas can be found in the signal specific Semantic Conventions below* Semantic Conventions by signals: + * [Resource](resource/semantic_conventions/README.md): Semantic Conventions for resources. * [Trace](trace/semantic_conventions/README.md): Semantic Conventions for traces and spans. * [Metrics](metrics/semantic_conventions/README.md): Semantic Conventions for metrics. diff --git a/specification/http/README.md b/specification/http/README.md index d5c5424c27..b6b3f1d0dd 100644 --- a/specification/http/README.md +++ b/specification/http/README.md @@ -32,6 +32,7 @@ and various HTTP versions like 1.1, 2 and SPDY. > next major version SHOULD NOT be released prior to October 1, 2023). Semantic conventions for HTTP are defined for the following signals: + * [HTTP Spans](http-spans.md): Semantic Conventions for HTTP client and server *spans*. * [HTTP Metrics](http-metrics.md): Semantic Conventions for HTTP client and server *metrics*. From 2a134eaabd8101f90620157a0e1864d7386c1a95 Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Tue, 27 Jun 2023 16:42:34 +0200 Subject: [PATCH 4/5] fixing comments from first reviews Signed-off-by: Alexander Wert --- specification/README.md | 6 +----- specification/http/README.md | 2 +- specification/http/http-metrics.md | 2 +- specification/http/http-spans.md | 2 +- 4 files changed, 4 insertions(+), 8 deletions(-) diff --git a/specification/README.md b/specification/README.md index 4992c37104..d32dab002d 100644 --- a/specification/README.md +++ b/specification/README.md @@ -1,6 +1,4 @@ -# Semantic Conventions - -**Status**: [Mixed][DocumentStatus] +# OpenTelemetry 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 attribute names, types, meaning and valid values, and provide descriptions and example usage. @@ -17,5 +15,3 @@ Semantic Conventions by signals: * [Trace](trace/semantic_conventions/README.md): Semantic Conventions for traces and spans. * [Metrics](metrics/semantic_conventions/README.md): Semantic Conventions for metrics. * [Logs](logs/semantic_conventions/README.md): Semantic Conventions for logs and event data. - -[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md diff --git a/specification/http/README.md b/specification/http/README.md index b6b3f1d0dd..a3ca562d5b 100644 --- a/specification/http/README.md +++ b/specification/http/README.md @@ -8,7 +8,7 @@ and various HTTP versions like 1.1, 2 and SPDY. > **Warning** > Existing HTTP instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/http/http-spans.md) +> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior): > > * SHOULD NOT change the version of the HTTP or networking attributes that they emit diff --git a/specification/http/http-metrics.md b/specification/http/http-metrics.md index d5833da467..51c517c5e3 100644 --- a/specification/http/http-metrics.md +++ b/specification/http/http-metrics.md @@ -28,7 +28,7 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > **Warning** > Existing HTTP instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/http/http-metrics.md) +> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) > (or prior): > > * SHOULD NOT change the version of the HTTP or networking attributes that they emit diff --git a/specification/http/http-spans.md b/specification/http/http-spans.md index c5a666a454..c8d3428cb8 100644 --- a/specification/http/http-spans.md +++ b/specification/http/http-spans.md @@ -30,7 +30,7 @@ and various HTTP versions like 1.1, 2 and SPDY. > **Warning** > Existing HTTP instrumentations that are using -> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/http/http-spans.md) +> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior): > > * SHOULD NOT change the version of the HTTP or networking attributes that they emit From 14bf685b9b240261c8cf01a259b699053ad1a71b Mon Sep 17 00:00:00 2001 From: Alexander Wert Date: Wed, 28 Jun 2023 09:18:03 +0200 Subject: [PATCH 5/5] Adapted description of the Semantic Conventions. Signed-off-by: Alexander Wert --- specification/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/README.md b/specification/README.md index d32dab002d..94fed57ab6 100644 --- a/specification/README.md +++ b/specification/README.md @@ -1,7 +1,7 @@ # OpenTelemetry 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 attribute names, types, meaning and valid values, and provide descriptions and example usage. +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. Semantic Conventions are defined for the following areas: