Prefer arrays of name value pairs over objects (#115)

* Prefer arrays of name value pairs over objects * .resource.attributes are name, value, type * Fix validator shell tests * Apply suggestions from code review Co-authored-by: Alex Boten <[email protected]> --------- Co-authored-by: Alex Boten <[email protected]>
open-telemetry · Sep 19, 2024 · f89f35a · f89f35a
1 parent a377d99
commit f89f35a
Show file tree

Hide file tree

Showing 10 changed files with 139 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -15,8 +15,6 @@ The [examples](./examples) repository contains a variety of sample configuration
 - [sdk-migration-config.yaml](./examples/sdk-migration-config.yaml): Includes env var substitution references to all [standard env vars](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) which map cleanly to file configuration (see notes in the example for the set of env vars which are not referenced). Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][]. This is a great starting point for transitioning from env var based configuration to file based configuration.
 - [sdk-config.yaml](./examples/sdk-config.yaml): Represents the typical default configuration. This is a good starting point if you are not using env var based configuration or wish to transition fully to file based configuration. Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][].
 
-[env var substitution]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/file-configuration.md#environment-variable-substitution
-
 ## Code generation
 
 There are [several tools](https://json-schema.org/implementations.html) available to generate code from a JSON schema. The following shows an example for generating code from the JSON schema in Go:
@@ -70,6 +68,24 @@ Properties should be modeled using the most appropriate data structures and type
 
 In instances where there is a type mismatch between the JSON schema and equivalent standard env var, an alternative version of the property may be provided to resolve the mismatch. For example, resource attributes are configured at `.resource.attributes`, but `.resource.attributes_list` is available with a format matching that of `OTEL_RESOURCE_ATTRIBUTES`. Alternative properties are reserved for cases where there is a demonstrated need for platforms to be able to participate in configuration and there is no reasonable alternative.
 
+### Name-value pairs
+
+When a type requires a configurable list of name-value pairs (i.e. resource attributes, HTTP headers), model using an array of objects, each with `name` and `value` properties. While an array of name-value objects is slightly more verbose than an object where each key-value is an entry, the latter is preferred because:
+
+* Avoids user input as keys, which ensures conformity with the [snake_case properties](#property-name-case) rule.
+* Allows both the names and the values to be targets for [env var substitution]. For example:
+
+    ```yaml
+   tracer_provider:
+     processors:
+       - batch:
+           exporter:
+             otlp:
+               headers:
+                - name: ${AUTHORIZATION_HEADER_NAME:-api-key}
+                  value: ${AUTHORIZATION_HEADER_VALUE}
+    ```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)
@@ -89,3 +105,6 @@ Maintainers ([@open-telemetry/configuration-maintainers](https://github.com/orgs
 - [Tyler Yahn](https://github.com/tsloughter), Splunk
 
 *Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer).*
+
+[env var substitution]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/file-configuration.md#environment-variable-substitution
+
diff --git a/examples/anchors.yaml b/examples/anchors.yaml
@@ -8,7 +8,8 @@ exporters:
     client_key: /app/cert.pem
     client_certificate: /app/cert.pem
     headers:
-      api-key: !!str 1234
+      - name: api-key
+        value: "1234"
     compression: gzip
     timeout: 10000
 

diff --git a/examples/kitchen-sink.yaml b/examples/kitchen-sink.yaml
@@ -78,7 +78,8 @@ logger_provider:
             #
             # Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_HEADERS
             headers:
-              api-key: "1234"
+              - name: api-key
+                value: "1234"
             # Configure headers. Entries have lower priority than entries from .headers.
             #
             # The value is a list of comma separated key-value pairs,  matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
@@ -190,7 +191,8 @@ meter_provider:
             #
             # Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS
             headers:
-              api-key: !!str 1234
+              - name: api-key
+                value: "1234"
             # Configure headers. Entries have lower priority than entries from .headers.
             #
             # The value is a list of comma separated key-value pairs,  matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
@@ -321,7 +323,8 @@ tracer_provider:
             #
             # Environment variable: OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS
             headers:
-              api-key: !!str 1234
+              - name: api-key
+                value: "1234"
             # Configure headers. Entries have lower priority than entries from .headers.
             #
             # The value is a list of comma separated key-value pairs,  matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
@@ -423,12 +426,40 @@ tracer_provider:
 resource:
   # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
   #
+  # Each entry must contain .name and .value, and may optionally include .type, which defaults to "string" if not set. The value must match the type. Known types include: string, bool, int, double, string_array, bool_array, int_array, double_array.
+  #
   # Environment variable: OTEL_RESOURCE_ATTRIBUTES
   attributes:
     # Configure `service.name` resource attribute
     #
     # Environment variable: OTEL_SERVICE_NAME
-    service.name: !!str "unknown_service"
+    - name: service.name
+      value: unknown_service
+    # Configure other resource attributes with explicit types.
+    - name: string_key
+      value: value
+      type: string
+    - name: bool_key
+      value: true
+      type: bool
+    - name: int_key
+      value: 1
+      type: int
+    - name: double_key
+      value: 1.1
+      type: double
+    - name: string_array_key
+      value: ["value1", "value2"]
+      type: string_array
+    - name: bool_array_key
+      value: [ true, false ]
+      type: bool_array
+    - name: int_array_key
+      value: [ 1, 2 ]
+      type: int_array
+    - name: double_array_key
+      value: [ 1.1, 2.2 ]
+      type: double_array
   # Configure resource attributes. Entries have lower priority than entries from .resource.attributes.
   #
   # The value is a list of comma separated key-value pairs,  matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.

diff --git a/examples/sdk-config.yaml b/examples/sdk-config.yaml
@@ -16,7 +16,8 @@ resource:
   # Configure resource attributes.
   attributes:
     # Configure `service.name` resource attribute
-    service.name: unknown_service
+    - name: service.name
+      value: unknown_service
 
 # Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits.
 attribute_limits:
@@ -62,7 +63,7 @@ tracer_provider:
             # Configure max time (in milliseconds) to wait for each export.
             timeout: 10000
             # Configure headers:
-            headers: {}
+            headers: []
   # Configure span limits. See also attribute_limits.
   limits:
     # Configure max span attribute value size. Overrides attribute_limits.attribute_value_length_limit.
@@ -131,7 +132,7 @@ meter_provider:
             # Configure max time (in milliseconds) to wait for each export.
             timeout: 10000
             # Configure headers:
-            headers: {}
+            headers: []
             # Configure temporality preference.
             temporality_preference: cumulative
             # Configure default histogram aggregation.
@@ -170,7 +171,7 @@ logger_provider:
             # Configure max time (in milliseconds) to wait for each export.
             timeout: 10000
             # Configure headers:
-            headers: {}
+            headers: []
   # Configure log record limits. See also attribute_limits.
   limits:
     # Configure max log record attribute value size. Overrides attribute_limits.attribute_value_length_limit.

diff --git a/examples/sdk-migration-config.yaml b/examples/sdk-migration-config.yaml
@@ -46,7 +46,8 @@ resource:
   # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
   attributes:
     # Configure `service.name` resource attribute
-    service.name: ${OTEL_SERVICE_NAME:-unknown_service}
+    - name: service.name
+      value: ${OTEL_SERVICE_NAME:-unknown_service}
   # Configure resource attributes. Entries have lower priority than entries from .resource.attributes.
   #
   # The value is a list of comma separated key-value pairs, matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
@@ -96,7 +97,7 @@ tracer_provider:
             # Configure max time (in milliseconds) to wait for each export.
             timeout: ${OTEL_EXPORTER_OTLP_TRACES_TIMEOUT:-10000}
             # Configure headers:
-            headers: {}
+            headers: []
             # Configure headers. Entries have lower priority than entries from .headers.
             #
             # The value is a list of comma separated key-value pairs,  matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
@@ -168,12 +169,12 @@ meter_provider:
             compression: ${OTEL_EXPORTER_OTLP_METRICS_COMPRESSION:-gzip}
             # Configure max time (in milliseconds) to wait for each export.
             timeout: ${OTEL_EXPORTER_OTLP_METRICS_TIMEOUT:-10000}
-            # Configure headers:
-            headers: {}
+            # Configure headers.
+            headers: []
             # Configure headers. Entries have lower priority than entries from .headers.
             #
             # The value is a list of comma separated key-value pairs,  matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
-            headers_list: "{OTEL_EXPORTER_OTLP_METRICS_HEADERS}"
+            headers_list: ${OTEL_EXPORTER_OTLP_METRICS_HEADERS}
             # Configure temporality preference.
             temporality_preference: ${OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE:-cumulative}
             # Configure default histogram aggregation.
@@ -211,12 +212,12 @@ logger_provider:
             compression: ${OTEL_EXPORTER_OTLP_LOGS_COMPRESSION:-gzip}
             # Configure max time (in milliseconds) to wait for each export.
             timeout: ${OTEL_EXPORTER_OTLP_LOGS_TIMEOUT:-10000}
-            # Configure headers:
-            headers: {}
+            # Configure headers.
+            headers: []
             # Configure headers. Entries have lower priority than entries from .headers.
             #
             # The value is a list of comma separated key-value pairs,  matching the format of OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_LOGS_HEADERS. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
-            headers_list: "{OTEL_EXPORTER_OTLP_LOGS_HEADERS}"
+            headers_list: ${OTEL_EXPORTER_OTLP_LOGS_HEADERS}
   # Configure log record limits. See also attribute_limits.
   limits:
     # Configure max log record attribute value size. Overrides attribute_limits.attribute_value_length_limit.

diff --git a/schema/common.json b/schema/common.json
@@ -4,15 +4,6 @@
     "title": "Common",
     "type": ["object", "null"],
     "$defs": {
-        "Headers": {
-            "type": ["object", "null"],
-            "title": "Headers",
-            "patternProperties": {
-                ".*": {
-                    "type": ["string", "null"]
-                }
-            }
-        },
         "IncludeExclude": {
             "type": "object",
             "additionalProperties": false,
@@ -43,6 +34,21 @@
                 }
             }
         },
+        "NameStringValuePair": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "value": {
+                    "type": ["string", "null"]
+                }
+            },
+            "required": [
+                "name", "value"
+            ]
+        },
         "Otlp": {
             "type": ["object", "null"],
             "additionalProperties": false,
@@ -64,7 +70,10 @@
                     "type": ["string", "null"]
                 },
                 "headers": {
-                    "$ref": "#/$defs/Headers"
+                    "type": "array",
+                    "items": {
+                        "$ref": "common.json#/$defs/NameStringValuePair"
+                    }
                 },
                 "headers_list": {
                     "type": ["string", "null"]

diff --git a/schema/meter_provider.json b/schema/meter_provider.json
@@ -170,7 +170,10 @@
                     "type": ["string", "null"]
                 },
                 "headers": {
-                    "$ref": "common.json#/$defs/Headers"
+                    "type": "array",
+                    "items": {
+                        "$ref": "common.json#/$defs/NameStringValuePair"
+                    }
                 },
                 "headers_list": {
                     "type": ["string", "null"]

diff --git a/schema/resource.json b/schema/resource.json
@@ -6,7 +6,10 @@
     "additionalProperties": false,
     "properties": {
         "attributes": {
-            "$ref": "#/$defs/Attributes"
+            "type": "array",
+            "items": {
+                "$ref": "#/$defs/AttributeNameValue"
+            }
         },
         "detectors": {
             "$ref": "#/$defs/Detectors"
@@ -19,10 +22,42 @@
         }
     },
     "$defs": {
-        "Attributes": {
-            "title": "Attributes",
-            "type": ["object", "null"],
-            "additionalProperties": true
+        "AttributeNameValue": {
+            "title": "AttributeNameValue",
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "value": {
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "number"},
+                        {"type": "boolean"},
+                        {"type": "null"},
+                        {"type": "array", "items": {"type": "string"}},
+                        {"type": "array", "items": {"type": "boolean"}},
+                        {"type": "array", "items": {"type": "number"}}
+                    ]
+                },
+                "type": {
+                    "enum": [
+                        null,
+                        "string",
+                        "bool",
+                        "int",
+                        "double",
+                        "string_array",
+                        "bool_array",
+                        "int_array",
+                        "double_array"
+                    ]
+                }
+            },
+            "required": [
+                "name", "value"
+            ]
         },
         "Detectors": {
             "title": "Detectors",

diff --git a/validator/shelltests/hex_integer.yaml b/validator/shelltests/hex_integer.yaml
@@ -9,7 +9,8 @@ resource:
   # Configure resource attributes.
   attributes:
     # Configure `service.name` resource attribute
-    service.name: "${OTEL_SERVICE_NAME:-unknown_service}"
+    - name: service.name
+      value: "${OTEL_SERVICE_NAME:-unknown_service}"
 
 attribute_limits:
   # Configure max attribute value size.

diff --git a/validator/shelltests/string_for_int.yaml b/validator/shelltests/string_for_int.yaml
@@ -9,7 +9,8 @@ resource:
   # Configure resource attributes.
   attributes:
     # Configure `service.name` resource attribute
-    service.name: "${OTEL_SERVICE_NAME:-unknown_service}"
+    - name: service.name
+      value: "${OTEL_SERVICE_NAME:-unknown_service}"
 
 attribute_limits:
   # Configure max attribute value size.