From 8a5b2f8c081aff01bb0ad9e89c6636c0e4d87e81 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 20 Jan 2023 14:48:47 +0100 Subject: [PATCH 1/6] Bump semantic convention tooling to v0.15.0 --- .vscode/settings.json | 2 +- Makefile | 2 +- semantic_conventions/README.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index aacbf2968fd..451d90814f6 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,7 +10,7 @@ "MD040": false, }, "yaml.schemas": { - "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.14.0/semantic-conventions/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.15.0/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, diff --git a/Makefile b/Makefile index 4a7ae02f170..b56bdc46d93 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.14.0 +SEMCONVGEN_VERSION=0.15.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index 7e7ea5d2ba7..e9e974b72ae 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -17,12 +17,12 @@ i.e.: Semantic conventions for the spec MUST adhere to the [attribute naming](../specification/common/attribute-naming.md) and [requirement level](../specification/common/attribute-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.14.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.15.0/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.14.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.15.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -33,7 +33,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run make table-generation ``` -For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.14.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.15.0/semantic-conventions) in the OpenTelemetry build tools repository. Using this build tool, it is also possible to generate code for use in OpenTelemetry language projects. From 3f5aa1846d42e989a45953267f65bf28310885ff Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 20 Jan 2023 15:24:36 +0000 Subject: [PATCH 2/6] Re-generate tables --- .../trace/semantic_conventions/http.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 794784228f2..a607f467cbc 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -78,6 +78,10 @@ sections below. | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [3] | | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [4] | +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* `http.method` + **[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. **[2]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. @@ -96,10 +100,6 @@ sections below. | `3.0` | HTTP/3 | | `SPDY` | SPDY protocol. | | `QUIC` | QUIC protocol. | - -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: - -* `http.method` 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). @@ -138,6 +138,12 @@ before any HTTP-redirects that may happen when executing the request. | [`net.peer.name`](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 | | [`net.peer.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* `http.url` +* [`net.peer.name`](span-general.md) +* [`net.peer.port`](span-general.md) + **[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`. **[2]:** 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). @@ -153,12 +159,6 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[4]:** 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. **[5]:** If not default (`80` for `http` scheme, `443` for `https`). - -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: - -* `http.url` -* [`net.peer.name`](span-general.md) -* [`net.peer.port`](span-general.md) Note that in some cases host and port identifiers in the `Host` header might be different from the `net.peer.name` and `net.peer.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. @@ -248,6 +248,13 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | [`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] | +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` +* [`net.host.name`](span-general.md) +* [`net.host.port`](span-general.md) + **[1]:** 'http.route' MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. **[2]:** This is not necessarily the same as `net.sock.peer.addr`, which would @@ -282,13 +289,6 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** If not default (`80` for `http` scheme, `443` for `https`). **[6]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. - -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` -* [`net.host.name`](span-general.md) -* [`net.host.port`](span-general.md) `http.route` MUST be provided at span creation time if and only if it's already available. If it becomes available after span starts, instrumentation MUST populate it anytime before span ends. From cd067eb23832005eae8f29a5cf65692a57efbe7e Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 20 Jan 2023 15:44:03 +0000 Subject: [PATCH 3/6] Add changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 640bf155f37..05eba84c36d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,9 @@ release. ### Semantic Conventions +- Enable semantic convention tooling for metrics in spec + ([#3118](https://github.com/open-telemetry/opentelemetry-specification/pull/3118)) + ### Compatibility ### OpenTelemetry Protocol From 0ee9c4fdb45e9e4b6f3c9f61b0c9714f1cd9c526 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 20 Jan 2023 15:54:56 +0000 Subject: [PATCH 4/6] Bump semantic convention tooling to v0.15.1 --- .vscode/settings.json | 2 +- Makefile | 2 +- semantic_conventions/README.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 451d90814f6..1346afcd11f 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,7 +10,7 @@ "MD040": false, }, "yaml.schemas": { - "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.15.0/semantic-conventions/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.15.1/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, diff --git a/Makefile b/Makefile index b56bdc46d93..8e3d033f1c9 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.15.0 +SEMCONVGEN_VERSION=0.15.1 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index e9e974b72ae..ef7887420f7 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -17,12 +17,12 @@ i.e.: Semantic conventions for the spec MUST adhere to the [attribute naming](../specification/common/attribute-naming.md) and [requirement level](../specification/common/attribute-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.15.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.15.1/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.15.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.15.1/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -33,7 +33,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run make table-generation ``` -For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.15.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.15.1/semantic-conventions) in the OpenTelemetry build tools repository. Using this build tool, it is also possible to generate code for use in OpenTelemetry language projects. From cb9a17667a4d66251d00bb071c69f023ea1be71d Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 20 Jan 2023 15:55:37 +0000 Subject: [PATCH 5/6] Re-generate tables --- .../trace/semantic_conventions/http.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index a607f467cbc..eaa2e5ec40f 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -78,10 +78,6 @@ sections below. | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [3] | | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [4] | -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: - -* `http.method` - **[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. **[2]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD accept both IPv4 and IPv6 formats for the address in `net.sock.peer.addr` if `net.sock.family` is not set. This is to support instrumentations that follow previous versions of this document. @@ -90,6 +86,10 @@ Following attributes MUST be provided **at span creation time** (when provided a **[4]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* `http.method` + `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 | @@ -138,12 +138,6 @@ before any HTTP-redirects that may happen when executing the request. | [`net.peer.name`](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 | | [`net.peer.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. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: - -* `http.url` -* [`net.peer.name`](span-general.md) -* [`net.peer.port`](span-general.md) - **[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`. **[2]:** 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). @@ -159,6 +153,12 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup. **[4]:** 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. **[5]:** If not default (`80` for `http` scheme, `443` for `https`). + +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* `http.url` +* [`net.peer.name`](span-general.md) +* [`net.peer.port`](span-general.md) Note that in some cases host and port identifiers in the `Host` header might be different from the `net.peer.name` and `net.peer.port`, in this case instrumentation MAY populate `Host` header on `http.request.header.host` attribute even if it's not enabled by user. @@ -248,13 +248,6 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | [`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] | -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` -* [`net.host.name`](span-general.md) -* [`net.host.port`](span-general.md) - **[1]:** 'http.route' MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. **[2]:** This is not necessarily the same as `net.sock.peer.addr`, which would @@ -289,6 +282,13 @@ SHOULD NOT be set if only IP address is available and capturing name would requi **[5]:** If not default (`80` for `http` scheme, `443` for `https`). **[6]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. + +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` +* [`net.host.name`](span-general.md) +* [`net.host.port`](span-general.md) `http.route` MUST be provided at span creation time if and only if it's already available. If it becomes available after span starts, instrumentation MUST populate it anytime before span ends. From 5ca305b1e0ca1cd58af89bf4ff664143ccc91f10 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 20 Jan 2023 22:34:17 +0100 Subject: [PATCH 6/6] Fix changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 05eba84c36d..a85d94f6eb2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ release. ### Semantic Conventions - Enable semantic convention tooling for metrics in spec - ([#3118](https://github.com/open-telemetry/opentelemetry-specification/pull/3118)) + ([#3119](https://github.com/open-telemetry/opentelemetry-specification/pull/3119)) ### Compatibility