Adopt attribute requirement levels in semantic conventions (#2594)

.vscode/settings.json

@@ -10,7 +10,7 @@
         "MD040": false,
     },
     "yaml.schemas": {
-        "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.11.0/semantic-conventions/semconv.schema.json": [
+        "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.12.0/semantic-conventions/semconv.schema.json": [
             "semantic_conventions/**/*.yaml"
         ]
     },

CHANGELOG.md

@@ -21,6 +21,8 @@ release.
 
 - Add `net.app.protocol.*` attributes
   ([#2602](https://github.com/open-telemetry/opentelemetry-specification/pull/2602)).
+- Adopt attribute requirement levels in semantic conventions
+  ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594))
 
 ### Compatibility
 

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.11.0
+SEMCONVGEN_VERSION=0.12.0
 
 # TODO: add `yamllint` step to `all` after making sure it works on Mac.
 .PHONY: all

internal/tools/schema_check.sh

@@ -6,7 +6,7 @@
 
 set -e
 
-BUILD_TOOL_SCHEMAS_VERSION=0.11.0
+BUILD_TOOL_SCHEMAS_VERSION=0.12.0
 
 # List of vesions 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")

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.11.0/semantic-conventions/syntax.md)
+Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.12.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.11.0/semantic-conventions/README.md) for what extension you need.
+[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.12.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.11.0/semantic-conventions)
+For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.12.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.

semantic_conventions/resource/faas.yaml

@@ -6,7 +6,7 @@ groups:
     attributes:
       - id: name
         type: string
-        required: always
+        requirement_level: required
         brief: >
           The name of the single function that this runtime instance executes.
         note: |

semantic_conventions/resource/os.yaml

@@ -44,7 +44,7 @@ groups:
             - id: z_os
               value: 'z_os'
               brief: "IBM z/OS"
-        required: always
+        requirement_level: required
         brief: 'The operating system type.'
       - id: description
         type: string

semantic_conventions/resource/process.yaml

@@ -11,35 +11,35 @@ groups:
         examples: [1234]
       - id: executable.name
         type: string
-        required:
-          conditional: "See below"
+        requirement_level:
+          conditionally_required: See alternative attributes below.
         brief: >
           The name of the process executable. On Linux based systems, can be set
           to the `Name` in `proc/[pid]/status`. On Windows, can be set to the
           base name of `GetProcessImageFileNameW`.
         examples: ['otelcol']
       - id: executable.path
         type: string
-        required:
-          conditional: "See below"
+        requirement_level:
+          conditionally_required: See alternative attributes below.
         brief: >
           The full path to the process executable. On Linux based systems, can
           be set to the target of `proc/[pid]/exe`. On Windows, can be set to the
           result of `GetProcessImageFileNameW`.
         examples: ['/usr/bin/cmd/otelcol']
       - id: command
         type: string
-        required:
-          conditional: "See below"
+        requirement_level:
+          conditionally_required: See alternative attributes below.
         brief: >
           The command used to launch the process (i.e. the command name). On Linux
           based systems, can be set to the zeroth string in `proc/[pid]/cmdline`.
           On Windows, can be set to the first parameter extracted from `GetCommandLineW`.
         examples: ['cmd/otelcol']
       - id: command_line
         type: string
-        required:
-          conditional: "See below"
+        requirement_level:
+          conditionally_required: See alternative attributes below.
         brief: >
           The full command used to launch the process as a single string representing
           the full command. On Windows, can be set to the result of `GetCommandLineW`.
@@ -48,8 +48,8 @@ groups:
         examples: ['C:\cmd\otecol --config="my directory\config.yaml"']
       - id: command_args
         type: string[]
-        required:
-          conditional: "See below"
+        requirement_level:
+          conditionally_required: See alternative attributes below.
         brief: >
           All the command arguments (including the command/executable itself) as
           received by the process. On Linux-based systems (and some other Unixoid
@@ -62,6 +62,14 @@ groups:
         brief: >
           The username of the user that owns the process.
         examples: 'root'
+    constraints:
+      - any_of:
+          - process.executable.name
+          - process.executable.path
+          - process.command
+          - process.command_line
+          - process.command_args
+
   - id: process.runtime
     prefix: process.runtime
     brief: >

semantic_conventions/resource/service.yaml

@@ -6,7 +6,7 @@ groups:
     attributes:
       - id: name
         type: string
-        required: always
+        requirement_level: required
         brief: >
           Logical name of the service.
         note: >

semantic_conventions/resource/webengine.yaml

@@ -6,7 +6,7 @@ groups:
     attributes:
       - id: name
         type: string
-        required: always
+        requirement_level: required
         brief: >
           The name of the web engine.
         examples: ['WildFly']

semantic_conventions/trace/cloudevents.yaml

@@ -8,25 +8,25 @@ groups:
     attributes:
       - id: event_id
         type: string
-        required: always
+        requirement_level: required
         brief: >
           The [event_id](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) uniquely identifies the event.
         examples: ['123e4567-e89b-12d3-a456-426614174000', '0001']
       - id: event_source
         type: string
-        required: always
+        requirement_level: required
         brief: >
           The [source](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) identifies the context in which an event happened.
         examples: ['https://github.com/cloudevents', '/cloudevents/spec/pull/123', 'my-service' ]
       - id: event_spec_version
         type: string
-        required: always
+        requirement_level: required
         brief: >
           The [version of the CloudEvents specification](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#specversion) which the event uses.
         examples: '1.0'
       - id: event_type
         type: string
-        required: always
+        requirement_level: required
         brief: >
           The [event_type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) contains a value describing the type of event related to the originating occurrence.
         examples: ['com.github.pull_request.opened', 'com.example.object.deleted.v2']

semantic_conventions/trace/database.yaml

@@ -8,7 +8,7 @@ groups:
       - id: system
         tag: connection-level
         brief: An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers.
-        required: always
+        requirement_level: required
         type:
           allow_custom_values: true
           members:
@@ -175,8 +175,8 @@ groups:
       - id: name
         tag: call-level
         type: string
-        required:
-          conditional: Required, if applicable.
+        requirement_level:
+          conditionally_required: If applicable.
         brief: >
           This attribute is used to report the name of the database being accessed.
           For commands that switch the database, this should be set to the target database
@@ -190,18 +190,18 @@ groups:
       - id: statement
         tag: call-level
         type: string
-        required:
-          conditional: >
-            Required if applicable and not explicitly disabled via instrumentation configuration.
+        requirement_level:
+          conditionally_required: >
+            If applicable and not explicitly disabled via instrumentation configuration.
         brief: >
           The database statement being executed.
         note: The value may be sanitized to exclude sensitive information.
         examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"']
       - id: operation
         tag: call-level
         type: string
-        required:
-          conditional: Required, if `db.statement` is not applicable.
+        requirement_level:
+          conditionally_required: If `db.statement` is not applicable.
         brief: >
           The name of the operation being executed, e.g. the [MongoDB command name](https://docs.mongodb.com/manual/reference/command/#database-operations)
           such as `findAndModify`, or the SQL keyword.
@@ -215,20 +215,20 @@ groups:
         examples: ['findAndModify', 'HMSET', 'SELECT']
       - ref: net.peer.name
         tag: connection-level
-        required:
-          conditional: See below.
+        requirement_level:
+          conditionally_required: See alternative attributes below.
       - ref: net.peer.ip
         tag: connection-level
-        required:
-          conditional: See below.
+        requirement_level:
+          conditionally_required: See alternative attributes below.
       - ref: net.peer.port
         tag: connection-level
-        required:
-          conditional: Required if using a port other than the default port for this DBMS.
+        requirement_level:
+          conditionally_required: If using a port other than the default port for this DBMS.
       - ref: net.transport
         tag: connection-level
-        required:
-          conditional: Recommended in general, required for in-process databases (`"inproc"`).
+        requirement_level:
+          conditionally_required: If database type is in-process (`"inproc"`), recommended for other database types.
     constraints:
       - any_of:
           - 'net.peer.name'
@@ -294,8 +294,7 @@ groups:
       - id: table
         type: string
         tag: call-level-tech-specific-cassandra
-        required:
-          conditional: Recommended if available.
+        requirement_level: recommended
         brief: The name of the primary table that the operation is acting upon, including the keyspace name (if applicable).
         note: >
           This mirrors the db.sql.table attribute but references cassandra rather than sql.
@@ -337,8 +336,8 @@ groups:
     attributes:
       - id: database_index
         type: int
-        required:
-          conditional: Required, if other than the default database (`0`).
+        requirement_level:
+          conditionally_required: If other than the default database (`0`).
         tag: call-level-tech-specific
         brief: >
           The index of the database being accessed as used in the [`SELECT` command](https://redis.io/commands/select), provided as an integer.
@@ -353,7 +352,7 @@ groups:
     attributes:
       - id: collection
         type: string
-        required: always
+        requirement_level: required
         tag: call-level-tech-specific
         brief: >
           The collection being accessed within the database stated in `db.name`.
@@ -368,8 +367,7 @@ groups:
       - id: table
         tag: call-level-tech-specific
         type: string
-        required:
-          conditional: Recommended if available.
+        requirement_level: recommended
         brief: The name of the primary table that the operation is acting upon, including the database name (if applicable).
         note: >
           It is not recommended to attempt any client-side parsing of

semantic_conventions/trace/faas.yaml

@@ -50,14 +50,14 @@ groups:
     attributes:
       - id: collection
         type: string
-        required: always
+        requirement_level: required
         brief: >
           The name of the source on which the triggering operation was performed.
           For example, in Cloud Storage or S3 corresponds to the bucket name,
           and in Cosmos DB to the database name.
         examples: ['myBucketName', 'myDbName']
       - id: operation
-        required: always
+        requirement_level: required
         type:
           allow_custom_values: true
           members:
@@ -73,7 +73,7 @@ groups:
         brief: 'Describes the type of the operation that was performed on the data.'
       - id: time
         type: string
-        required: always
+        requirement_level: required
         brief: >
           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)
@@ -111,7 +111,7 @@ groups:
     attributes:
       - id: time
         type: string
-        required: always
+        requirement_level: required
         brief: >
           A string containing the function invocation time in the
           [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
@@ -137,7 +137,7 @@ groups:
           A boolean that is true if the serverless function is executed for the
           first time (aka cold-start).
       - ref: faas.trigger
-        required: always
+        requirement_level: required
 
   - id: faas_span.out
     extends: faas_span
@@ -148,7 +148,7 @@ groups:
     attributes:
       - id: invoked_name
         type: string
-        required: always
+        requirement_level: required
         brief: >
           The name of the invoked function.
         note: >
@@ -174,16 +174,16 @@ groups:
             - id: 'tencent_cloud'
               value: 'tencent_cloud'
               brief: 'Tencent Cloud'
-        required: always
+        requirement_level: required
         brief: >
           The cloud provider of the invoked function.
         note: >
           SHOULD be equal to the `cloud.provider` resource attribute of the
           invoked function.
       - id: invoked_region
         type: string
-        required:
-          conditional: >
+        requirement_level:
+          conditionally_required: >
             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