Bump semantic conventions tool to v0.11.0 and refine enum wording (#2399)

.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"
         ]
     },

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

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.

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 |
 |---|---|

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 |
 |---|---|

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 |
 |---|---|

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 |
 |---|---|

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 |
 |---|---|

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 |
 |---|---|

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 |
 |---|---|

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 |
 |---|---|

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 |
 |---|---|

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 |
 |---|---|