Rename Optional requirement level to Opt-In

open-telemetry · Feb 17, 2023 · 05fd28f · 05fd28f
1 parent 6baebe9
commit 05fd28f
Show file tree

Hide file tree

Showing 12 changed files with 16 additions and 16 deletions.
diff --git a/semantic-conventions/semconv.schema.json b/semantic-conventions/semconv.schema.json
@@ -341,7 +341,7 @@
 				{
 					"properties": {
 						"requirement_level": {
-							"description": "specifies the attribute requirement level. Can be 'required', 'conditionally_required', 'recommended', or 'optional'. When omitted, the attribute is 'recommended'. When set to 'conditionally_required', the string provided as <condition> MUST specify the conditions under which the attribute is required.",
+							"description": "specifies the attribute requirement level. Can be 'required', 'conditionally_required', 'recommended', or 'opt_in'. When omitted, the attribute is 'recommended'. When set to 'conditionally_required', the string provided as <condition> MUST specify the conditions under which the attribute is required.",
 							"oneOf": [
 								{
 									"const": "required"
@@ -378,7 +378,7 @@
 									]
 								},
 								{
-									"const": "optional"
+									"const": "opt_in"
 								}
 							]
 						},

diff --git a/semantic-conventions/src/opentelemetry/semconv/model/semantic_attribute.py b/semantic-conventions/src/opentelemetry/semconv/model/semantic_attribute.py
@@ -32,7 +32,7 @@ class RequirementLevel(Enum):
     REQUIRED = 1
     CONDITIONALLY_REQUIRED = 2
     RECOMMENDED = 3
-    OPTIONAL = 4
+    OPT_IN = 4
 
 
 class StabilityLevel(Enum):
@@ -137,7 +137,7 @@ def parse(
                 "required": RequirementLevel.REQUIRED,
                 "conditionally_required": RequirementLevel.CONDITIONALLY_REQUIRED,
                 "recommended": RequirementLevel.RECOMMENDED,
-                "optional": RequirementLevel.OPTIONAL,
+                "opt_in": RequirementLevel.OPT_IN,
             }
             requirement_level_msg = ""
             requirement_level_val = attribute.get("requirement_level", "")

diff --git a/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py b/semantic-conventions/src/opentelemetry/semconv/templating/markdown/__init__.py
@@ -156,8 +156,8 @@ def to_markdown_attr(
                 # We put the condition in the notes after the table
                 self.render_ctx.add_note(attribute.requirement_level_msg)
                 required = f"Conditionally Required: [{ len(self.render_ctx.notes)}]"
-        elif attribute.requirement_level == RequirementLevel.OPTIONAL:
-            required = "Optional"
+        elif attribute.requirement_level == RequirementLevel.OPT_IN:
+            required = "Opt-In"
         else:  # attribute.requirement_level == Required.RECOMMENDED or None
             # check if there are any notes
             if (

diff --git a/semantic-conventions/src/tests/data/markdown/empty/expected.md b/semantic-conventions/src/tests/data/markdown/empty/expected.md
@@ -79,7 +79,7 @@ Note that the items marked with [1] are different from the mapping defined in th
 | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. |
 | `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required: if and only if one was received/sent. |
 | `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | Recommended |
-| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Optional |
+| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Opt-In |
 | `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | Recommended |
 
 It is recommended to also use the general [network attributes][], especially `net.peer.ip`. 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.

diff --git a/semantic-conventions/src/tests/data/markdown/empty/input.md b/semantic-conventions/src/tests/data/markdown/empty/input.md
@@ -79,7 +79,7 @@ Note that the items marked with [1] are different from the mapping defined in th
 | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. |
 | `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required: if and only if one was received/sent. |
 | `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | Recommended |
-| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Optional |
+| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Opt-In |
 | `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | Recommended |
 
 It is recommended to also use the general [network attributes][], especially `net.peer.ip`. 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.

diff --git a/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md b/semantic-conventions/src/tests/data/markdown/metrics_tables/expected.md
@@ -27,5 +27,5 @@
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `bar.egg.type` | string | Type of egg. | `chicken`; `emu`; `dragon` | Conditionally Required: if available to instrumentation. |
-| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Optional |
+| `http.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Opt-In |
 <!-- endsemconv -->
diff --git a/semantic-conventions/src/tests/data/markdown/missing_end_tag/input.md b/semantic-conventions/src/tests/data/markdown/missing_end_tag/input.md
@@ -12,7 +12,7 @@
 | `http.scheme` | The URI scheme identifying the used protocol: `"http"` or `"https"` | Defined later. |
 | `http.status_code` | [HTTP response status code][]. E.g. `200` (integer) | Conditionally Required: if and only if one was received/sent. |
 | `http.status_text` | [HTTP reason phrase][]. E.g. `"OK"` | Recommended |
-| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Optional |
+| `http.flavor` | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. |  Opt-In |
 | `http.user_agent` | Value of the HTTP [User-Agent][] header sent by the client. | Recommended |
 
 It is recommended to also use the general [network attributes][], especially `net.peer.ip`. 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.

diff --git a/semantic-conventions/src/tests/data/markdown/ref/expected.md b/semantic-conventions/src/tests/data/markdown/ref/expected.md
@@ -4,7 +4,7 @@
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `rpc.service` | string | The service name, must be equal to the $service part in the span name. | `EchoService` | Required |
-| [`net.peer.name`](input_general.md) | string | override brief. [1] | `example.com` | Optional |
+| [`net.peer.name`](input_general.md) | string | override brief. [1] | `example.com` | Opt-In |
 | [`net.peer.port`](input_general.md) | int | It describes the server port the client is connecting to | `80`; `8080`; `443` | Required |
 | [`net.sock.peer.addr`](input_general.md) | string | Remote socket peer address. | `127.0.0.1`; `/tmp/mysql.sock` | Required |
 | [`net.sock.peer.port`](input_general.md) | int | Remote socket peer port. | `16456` | Conditionally Required: <condition> |

diff --git a/semantic-conventions/src/tests/data/markdown/ref/rpc.yaml b/semantic-conventions/src/tests/data/markdown/ref/rpc.yaml
@@ -23,7 +23,7 @@ groups:
         requirement_level: required
         brief: 'It describes the server port the client is connecting to'
       - ref: net.peer.name
-        requirement_level: optional
+        requirement_level: opt_in
         brief: override brief.
         note: override note.
       - ref: net.sock.peer.addr

diff --git a/semantic-conventions/src/tests/data/yaml/errors/wrong_multiple_requirement_levels.yaml b/semantic-conventions/src/tests/data/yaml/errors/wrong_multiple_requirement_levels.yaml
@@ -9,5 +9,5 @@ groups:
         type: boolean
         brief: 'test'
         requirement_level: required
-        requirement_level: optional
+        requirement_level: opt_in
         examples: [true, false]
diff --git a/semantic-conventions/src/tests/data/yaml/metrics.yaml b/semantic-conventions/src/tests/data/yaml/metrics.yaml
@@ -34,7 +34,7 @@ groups:
     unit: "{cartons}"
     attributes: 
       - ref: http.method
-        requirement_level: optional
+        requirement_level: opt_in
       - ref: bar.egg.type
         requirement_level: 
           conditionally_required: "if available to instrumentation."
diff --git a/semantic-conventions/syntax.md b/semantic-conventions/syntax.md
@@ -94,7 +94,7 @@ member ::= id value [brief] [note]
 requirement_level ::= "required"
          |   "conditionally_required" <condition>
          |   "recommended" [condition] # Default if not specified
-         |   "optional"
+         |   "opt_in"
 
 # EXPERIMENTAL: Using this is NOT ALLOWED in the specification currently.
 sampling_relevant ::= boolean
@@ -231,7 +231,7 @@ An attribute is defined by:
    It carries no particular semantic meaning but can be used e.g. for filtering
    in the markdown generator.
 - `requirement_level`, optional, specifies if the attribute is mandatory.
-   Can be "required", "conditionally_required", "recommended" or "optional". When omitted, the attribute is "recommended".
+   Can be "required", "conditionally_required", "recommended" or "opt_in". When omitted, the attribute is "recommended".
    When set to "conditionally_required", the string provided as `<condition>` MUST specify
    the conditions under which the attribute is required.
 - `sampling_relevant`, optional EXPERIMENTAL boolean,