Rename Optional attribute requirement level to Opt-In

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

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)
 
 <!-- tocstop -->
@@ -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,19 +46,19 @@ 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.
 
 ## Recommended
 
 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
 

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
 

specification/trace/semantic_conventions/http.md

@@ -115,9 +115,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.<key>` | string[] | HTTP request headers, `<key>` 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.<key>` | string[] | HTTP response headers, `<key>` 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.<key>` | string[] | HTTP request headers, `<key>` 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.<key>` | string[] | HTTP response headers, `<key>` 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.
@@ -242,16 +242,16 @@ Given an inbound request for a route (e.g. `"/users/:userID?"`) the `name` attri
 If the route cannot be determined, the `name` attribute MUST be set as defined in the general semantic conventions for HTTP.
 
 <!-- semconv trace.http.server(full) -->
-| Attribute  | Type | Description  | Examples  | Requirement Level |
-|---|---|---|---|---|
+| Attribute  | Type | Description  | Examples  | Requirement Level                                     |
+|---|---|---|---|-------------------------------------------------------|
 | `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [1] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available |
-| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds` | Required |
-| `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | Recommended |
-| `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.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [6] |
+| `http.target` | string | The full request target as passed in a HTTP request line or equivalent. | `/path/12314/?q=ddds` | Required                                              |
+| `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | Recommended                                           |
+| `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` | 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.
 SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.

specification/trace/semantic_conventions/rpc.md

@@ -207,8 +207,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.<key>`  | string[] | gRPC request metadata, `<key>` 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.<key>` | string[] | gRPC response metadata, `<key>` 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.<key>`  | string[] | gRPC request metadata, `<key>` 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.<key>` | string[] | gRPC response metadata, `<key>` 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.