From ec84e5dcd77f36e79c0fe9bb1444d62be79dbb38 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 1 Mar 2023 15:13:24 -0800 Subject: [PATCH] Rename Optional attribute requirement level to Opt-In (#3228) --- .vscode/settings.json | 2 +- Makefile | 2 +- internal/tools/schema_check.sh | 2 +- semantic_conventions/README.md | 6 +++--- .../resource/cloud_provider/heroku.yaml | 6 +++--- semantic_conventions/trace/http.yaml | 2 +- .../common/attribute-requirement-level.md | 14 +++++++------- .../semantic_conventions/hardware-metrics.md | 4 ++-- .../semantic_conventions/cloud_provider/heroku.md | 6 +++--- specification/trace/semantic_conventions/http.md | 8 ++++---- specification/trace/semantic_conventions/rpc.md | 4 ++-- 11 files changed, 28 insertions(+), 28 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 7673ce19c62..c216d9b9ef9 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.16.0/semantic-conventions/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.17.0/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, diff --git a/Makefile b/Makefile index 1c11955baa1..947b23f5f09 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.16.0 +SEMCONVGEN_VERSION=0.17.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 7794f306454..d096d747709 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,7 +6,7 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.16.0 +BUILD_TOOL_SCHEMAS_VERSION=0.17.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index c9684ba792e..99688841421 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -19,12 +19,12 @@ Semantic conventions for the spec MUST adhere to the [attribute requirement level](../specification/common/attribute-requirement-level.md), and [metric requirement level](../specification/metrics/metric-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.16.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.17.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.16.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.17.0/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -35,7 +35,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.16.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.17.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. diff --git a/semantic_conventions/resource/cloud_provider/heroku.yaml b/semantic_conventions/resource/cloud_provider/heroku.yaml index 4e8f30902a7..e73eddc1e70 100644 --- a/semantic_conventions/resource/cloud_provider/heroku.yaml +++ b/semantic_conventions/resource/cloud_provider/heroku.yaml @@ -10,16 +10,16 @@ groups: brief: > Time and date the release was created examples: [ '2022-10-23T18:00:42Z' ] - requirement_level: optional + requirement_level: opt_in - id: release.commit type: string brief: > Commit hash for the current release examples: [ 'e6134959463efd8966b20e75b913cafe3f5ec' ] - requirement_level: optional + requirement_level: opt_in - id: app.id type: string brief: > Unique identifier for the application examples: [ '2daa2797-e42b-4624-9322-ec3f968df4da' ] - requirement_level: optional + requirement_level: opt_in diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index 6b2eefbeacb..daccc90f44a 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -149,5 +149,5 @@ groups: if it's sent in absolute-form. - Port identifier of the `Host` header - ref: net.sock.host.addr - requirement_level: optional + requirement_level: opt_in - ref: net.sock.host.port diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index e015ef89eb1..c0301594093 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -10,7 +10,7 @@ - [Required](#required) - [Conditionally Required](#conditionally-required) - [Recommended](#recommended) -- [Optional](#optional) +- [Opt-In](#opt-in) - [Performance suggestions](#performance-suggestions) @@ -24,11 +24,11 @@ The following attribute requirement levels are specified: - [Required](#required) - [Conditionally Required](#conditionally-required) - [Recommended](#recommended) -- [Optional](#optional) +- [Opt-In](#opt-in) The requirement level for attribute is defined by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When defining requirement levels, semantic conventions MUST take into account signal-specific requirements. -For example, Metric attributes that may have high cardinality can only be defined with `Optional` level. +For example, Metric attributes that may have high cardinality can only be defined with `Opt-In` level. Semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. @@ -46,7 +46,7 @@ All instrumentations MUST add the attribute when given condition is satisfied. S `http.route` is an example of a conditionally required attribute to be populated when instrumented HTTP framework provides route information for the instrumented request. Some low-level HTTP server implementations do not support routing and corresponding instrumentations can't populate the attribute. -When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Optional` requirement level on the attribute. +When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.sock.peer.addr` is available, instrumentation can do a DNS lookup, cache and populate `net.sock.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. @@ -54,11 +54,11 @@ For example, `net.peer.name` is `Conditionally Required` by [Database convention Instrumentations SHOULD add the attribute by default if it's readily available and can be [efficiently populated](#performance-suggestions). Instrumentations MAY offer a configuration option to disable Recommended attributes. -Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD use the `Optional` requirement level on them if the attributes are logically applicable. +Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD use the `Opt-In` requirement level on them if the attributes are logically applicable. -## Optional +## Opt-In -Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Optional` attributes. +Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Opt-In` attributes. ## Performance suggestions diff --git a/specification/metrics/semantic_conventions/hardware-metrics.md b/specification/metrics/semantic_conventions/hardware-metrics.md index 7422a6d1ec8..cdda1211c5b 100644 --- a/specification/metrics/semantic_conventions/hardware-metrics.md +++ b/specification/metrics/semantic_conventions/hardware-metrics.md @@ -42,10 +42,10 @@ Additionally, it is recommended that all metrics in `hw.` instruments have the below attributes: | Attribute Key | Description | Example | Requirement Level | -| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- | +| ------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |-------------------| | `id` | An identifier for the hardware component, unique within the monitored host | `win32battery_battery_testsysa33_1` | Required | | `name` | An easily-recognizable name for the hardware component | `eth0` | Recommended | -| `parent` | Unique identifier of the parent component (typically the `id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | Optional | +| `parent` | Unique identifier of the parent component (typically the `id` attribute of the enclosure, or disk controller) | `dellStorage_perc_0` | Opt-In | ## Metric Instruments diff --git a/specification/resource/semantic_conventions/cloud_provider/heroku.md b/specification/resource/semantic_conventions/cloud_provider/heroku.md index a339fa19ba2..9030d2f93ea 100644 --- a/specification/resource/semantic_conventions/cloud_provider/heroku.md +++ b/specification/resource/semantic_conventions/cloud_provider/heroku.md @@ -9,9 +9,9 @@ | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | Optional | -| `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Optional | -| `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | Optional | +| `heroku.release.creation_timestamp` | string | Time and date the release was created | `2022-10-23T18:00:42Z` | Opt-In | +| `heroku.release.commit` | string | Commit hash for the current release | `e6134959463efd8966b20e75b913cafe3f5ec` | Opt-In | +| `heroku.app.id` | string | Unique identifier for the application | `2daa2797-e42b-4624-9322-ec3f968df4da` | Opt-In | **Mapping:** diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 2f8f850b3e0..014c9cf5d89 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -113,9 +113,9 @@ It is recommended to also use the general [socket-level attributes][] - `net.soc ### HTTP request and response headers | Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Optional | -| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Optional | +|---|---|---|---|-------------------| +| `http.request.header.` | string[] | HTTP request headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.request.header.content_type=["application/json"]`; `http.request.header.x_forwarded_for=["1.2.3.4", "1.2.3.5"]` | Opt-In | +| `http.response.header.` | string[] | HTTP response headers, `` being the normalized HTTP Header name (lowercase, with `-` characters replaced by `_`), the value being the header values. [1] [2] | `http.response.header.content_type=["application/json"]`; `http.response.header.my_custom_header=["abc", "def"]` | Opt-In | **[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request/response headers can be a security risk - explicit configuration helps avoid leaking sensitive information. @@ -248,7 +248,7 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | `http.scheme` | string | The URI scheme identifying the used protocol. | `http`; `https` | Required | | [`net.host.name`](span-general.md) | string | Name of the local HTTP server that received the request. [3] | `localhost` | Required | | [`net.host.port`](span-general.md) | int | Port of the local HTTP server that received the request. [4] | `8080` | Conditionally Required: [5] | -| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Optional | +| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host. | `192.168.0.1` | Opt-In | | [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [6] | **[1]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index b78b9647dae..28c080294a7 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -212,8 +212,8 @@ The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC stat | Attribute | Type | Description | Examples | Requirement Level | |-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------| -| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional | -| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional | +| `rpc.grpc.request.metadata.` | string[] | gRPC request metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Opt-In | +| `rpc.grpc.response.metadata.` | string[] | gRPC response metadata, `` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Opt-In | **[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured. Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.