From 741ac62a157536e5727218f645f64c1f3e035b00 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 4 Mar 2022 17:51:37 +0100 Subject: [PATCH] Bump semantic conventions tool to v0.11.0 and refine enum wording (#2399) --- .vscode/settings.json | 2 +- Makefile | 2 +- semantic_conventions/README.md | 6 +++--- specification/metrics/semantic_conventions/rpc.md | 2 +- specification/resource/semantic_conventions/README.md | 2 +- specification/resource/semantic_conventions/cloud.md | 4 ++-- specification/resource/semantic_conventions/host.md | 2 +- specification/resource/semantic_conventions/os.md | 2 +- specification/trace/semantic_conventions/database.md | 2 +- specification/trace/semantic_conventions/faas.md | 4 ++-- specification/trace/semantic_conventions/http.md | 2 +- specification/trace/semantic_conventions/rpc.md | 2 +- specification/trace/semantic_conventions/span-general.md | 4 ++-- 13 files changed, 18 insertions(+), 18 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 1a9c18384..210a6529a 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.8.0/semantic-conventions/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.11.0/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, diff --git a/Makefile b/Makefile index e0d64e4e8..d3e25d65c 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.8.0 +SEMCONVGEN_VERSION=0.11.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 9eb8e978f..1afd7e987 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 conventions](../specification/common/attribute-naming.md). -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.8.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.11.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.8.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.11.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.8.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.11.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/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index 9c5efe3e8..f264c175b 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -77,7 +77,7 @@ or not they should be on the server, client or both. * [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) * [`net.peer.name`](../../trace/semantic_conventions/span-general.md) -`rpc.system` MUST be one of the following or, if none of the listed values apply, a custom value: +`rpc.system` 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 | |---|---| diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index ab5fe29d4..c71753450 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -114,7 +114,7 @@ The identifier SHOULD be stable across different versions of an implementation. | `telemetry.sdk.version` | string | The version string of the telemetry SDK. | `1.2.3` | No | | `telemetry.auto.version` | string | The version string of the auto instrumentation agent, if used. | `1.2.3` | No | -`telemetry.sdk.language` MUST be one of the following or, if none of the listed values apply, a custom value: +`telemetry.sdk.language` 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 | |---|---| diff --git a/specification/resource/semantic_conventions/cloud.md b/specification/resource/semantic_conventions/cloud.md index dcb444dc7..78a2c11de 100644 --- a/specification/resource/semantic_conventions/cloud.md +++ b/specification/resource/semantic_conventions/cloud.md @@ -21,7 +21,7 @@ **[3]:** The prefix of the service SHOULD match the one specified in `cloud.provider`. -`cloud.provider` MUST be one of the following or, if none of the listed values apply, a custom value: +`cloud.provider` 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 | |---|---| @@ -31,7 +31,7 @@ | `gcp` | Google Cloud Platform | | `tencent_cloud` | Tencent Cloud | -`cloud.platform` MUST be one of the following or, if none of the listed values apply, a custom value: +`cloud.platform` 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 | |---|---| diff --git a/specification/resource/semantic_conventions/host.md b/specification/resource/semantic_conventions/host.md index 0bcb19093..b8b0aa742 100644 --- a/specification/resource/semantic_conventions/host.md +++ b/specification/resource/semantic_conventions/host.md @@ -17,7 +17,7 @@ | `host.image.id` | string | VM image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` | No | | `host.image.version` | string | The version string of the VM image as defined in [Version Attributes](README.md#version-attributes). | `0.1` | No | -`host.arch` MUST be one of the following or, if none of the listed values apply, a custom value: +`host.arch` 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 | |---|---| diff --git a/specification/resource/semantic_conventions/os.md b/specification/resource/semantic_conventions/os.md index 0303c3d0c..982be0745 100644 --- a/specification/resource/semantic_conventions/os.md +++ b/specification/resource/semantic_conventions/os.md @@ -16,7 +16,7 @@ In case of virtualized environments, this is the operating system as it is obser | `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | No | | `os.version` | string | The version string of the operating system as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `14.2.1`; `18.04.1` | No | -`os.type` MUST be one of the following or, if none of the listed values apply, a custom value: +`os.type` 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 | |---|---| diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index a9f55b8ad..0f3817916 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -56,7 +56,7 @@ Some database systems may allow a connection to switch to a different `db.user`, * [`net.peer.name`](span-general.md) * [`net.peer.ip`](span-general.md) -`db.system` MUST be one of the following or, if none of the listed values apply, a custom value: +`db.system` 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 | |---|---| diff --git a/specification/trace/semantic_conventions/faas.md b/specification/trace/semantic_conventions/faas.md index b681f4739..1740dcd7b 100644 --- a/specification/trace/semantic_conventions/faas.md +++ b/specification/trace/semantic_conventions/faas.md @@ -134,7 +134,7 @@ which the invoked FaaS instance reports about itself, if it's instrumented. **[4]:** For some cloud providers, like AWS or GCP, the region in which a function is hosted is essential to uniquely identify the function and also part of its endpoint. Since it's part of the endpoint being called, the region is always known to clients. In these cases, `faas.invoked_region` MUST be set accordingly. If the region is unknown to the client or not required for identifying the invoked function, setting `faas.invoked_region` is optional. -`faas.invoked_provider` MUST be one of the following or, if none of the listed values apply, a custom value: +`faas.invoked_provider` 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 | |---|---| @@ -165,7 +165,7 @@ For `faas` spans with trigger `datasource`, it is recommended to set the followi | `faas.document.time` | string | A string containing the time when the data was accessed in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime). | `2020-01-23T13:47:06Z` | Yes | | `faas.document.name` | string | The document name/table subjected to the operation. For example, in Cloud Storage or S3 is the name of the file, and in Cosmos DB the table name. | `myFile.txt`; `myTableName` | No | -`faas.document.operation` MUST be one of the following or, if none of the listed values apply, a custom value: +`faas.document.operation` 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 | |---|---| diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 4ff7df04d..4e5c0e9d7 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -80,7 +80,7 @@ Don't set the span status description if the reason can be inferred from `http.s **[3]:** 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. -`http.flavor` MUST be one of the following or, if none of the listed values apply, a custom value: +`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 | |---|---| diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 67f835d68..d06db4d51 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -73,7 +73,7 @@ Examples of span names: * [`net.peer.ip`](span-general.md) * [`net.peer.name`](span-general.md) -`rpc.system` MUST be one of the following or, if none of the listed values apply, a custom value: +`rpc.system` 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 | |---|---| diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 6a5697f4d..9bad0c5a5 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -61,7 +61,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case. -`net.host.connection.type` MUST be one of the following or, if none of the listed values apply, a custom value: +`net.host.connection.type` 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 | |---|---| @@ -71,7 +71,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `unavailable` | unavailable | | `unknown` | unknown | -`net.host.connection.subtype` MUST be one of the following or, if none of the listed values apply, a custom value: +`net.host.connection.subtype` 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 | |---|---|