Merge branch 'main' of /~https://github.com/open-telemetry/opentelemetr…

…y-configuration into annotation-guidance
open-telemetry · Jan 15, 2025 · 102356c · 102356c
2 parents 345e863 + 134fa1e
commit 102356c
Show file tree

Hide file tree

Showing 11 changed files with 839 additions and 402 deletions.
diff --git a/README.md b/README.md
@@ -42,6 +42,12 @@ Allowable changes:
 
 The following rules are enforced when modeling the configuration schema:
 
+### Which JSON schema version?
+
+The schema is modeled using JSON schema [draft 2020-12](https://json-schema.org/draft/2020-12).
+
+This is reflected in top level schema documents by setting `"$schema": "https://json-schema.org/draft/2020-12/schema"`.
+
 ### What properties are part of schema?
 
 Only properties which are described in [opentelemetry-specification](/~https://github.com/open-telemetry/opentelemetry-specification) or [semantic-conventions](/~https://github.com/open-telemetry/semantic-conventions) are modeled in the schema. However, it's acceptable to allow additional properties specific to a particular language or implementation, and not covered by the schema. Model these by setting `"additionalProperties": true` (see [JSON schema additionalProperties](https://json-schema.org/understanding-json-schema/reference/object#additionalproperties)). Types should set `"additionalProperties": false` by default unless requested by an opentelemetry component [maintainer](/~https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer) which supports additional options.
@@ -172,13 +178,26 @@ Another example:
         ]
       },
       "type": {
-        "type": ["string", "null"],
-        "enum": [null, "string", "bool", "int", "double", "string_array", "bool_array", "int_array", "double_array"]
+        "$ref": "#/$defs/AttributeType"
       }
     },
     "required": [
       "name", "value"
     ]
+  },
+  "AttributeType": {
+    "type": ["string", "null"],
+    "enum": [
+      null,
+      "string",
+      "bool",
+      "int",
+      "double",
+      "string_array",
+      "bool_array",
+      "int_array",
+      "double_array"
+    ]
   }
 }
 ```
@@ -194,6 +213,49 @@ Despite these potential benefits, these keywords should be omitted:
 * The titles of `object` and `enum` types produced by code generation tools should be defined using key values in [$defs](https://json-schema.org/understanding-json-schema/structuring#defs). Setting the `title` keyword introduces multiple sources of truth and possible conflict.
 * As described in [description generation](./CONTRIBUTING.md#description-generation), we use a different mechanism to describe the semantics of types and properties. Setting the `description` keyword introduces multiple sources of truth and possible conflict.
 
+## Schemas and subschemas
+
+In JSON Schema, a [schema](https://json-schema.org/learn/glossary#schema) is a document, and a [subschema](https://json-schema.org/learn/glossary#subschema) is contained in surrounding parent schema. Subschemas can be nested in various ways:
+
+A property can directly describe a complex set of requirements including nested structures:
+
+```json
+{
+  "properties": {
+    "shape": {
+      "type": "object",
+      "properties": {
+        "color": { "type": "string" },
+        "sides": { "type": "int" }
+      }
+    }
+  }
+}
+```
+
+Or a property can reference a subschema residing in a schema document's [$defs](https://json-schema.org/understanding-json-schema/structuring#defs):
+
+```json
+{
+  "properties": {
+    "shape": {
+      "$ref": "#/$defs/Shape"
+    }
+  },
+  "$defs": {
+    "Shape": {
+      "type": "object",
+      "properties": {
+        "color": { "type": "string" },
+        "sides": { "type": "int" }
+      }
+    }
+  }
+}
+```
+
+In order to promote stylistic consistency and allow for reuse of concepts, `object` and `enum` types should be defined in either as a top level schema document or as a subschema in a schema document's `$defs`.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

diff --git a/examples/kitchen-sink.yaml b/examples/kitchen-sink.yaml
diff --git a/examples/sdk-config.yaml b/examples/sdk-config.yaml
@@ -23,16 +23,19 @@ resource:
       value: unknown_service
 # Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits.
 attribute_limits:
-  # Configure max attribute value size.
+  # Configure max attribute value size. 
+  # Value must be non-negative.
   # If omitted or null, there is no limit.
   attribute_value_length_limit:
-  # Configure max attribute count.
+  # Configure max attribute count. 
+  # Value must be non-negative.
   # If omitted or null, 128 is used.
   attribute_count_limit: 128
 # Configure text map context propagators.
 # If omitted, tracecontext and baggage are used.
 propagator:
-  # Configure the set of propagators to include in the composite text map propagator. Built-in values include: tracecontext, baggage, b3, b3multi, jaeger, none. Known third party values include: xray, ottrace. For behavior of values see /~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration.
+  # Configure the set of propagators to include in the composite text map propagator. 
+  # Built-in values include: tracecontext, baggage, b3, b3multi, jaeger, none. Known third party values include: xray, ottrace. For behavior of values see /~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration.
   composite: [ tracecontext, baggage ]
 # Configure tracer provider.
 # If omitted, a noop tracer provider is used.
@@ -41,16 +44,18 @@ tracer_provider:
   processors:
     - # Configure a batch span processor.
       batch:
-        # Configure delay interval (in milliseconds) between two consecutive exports.
+        # Configure delay interval (in milliseconds) between two consecutive exports. 
+        # Value must be non-negative.
         # If omitted or null, 5000 is used.
         schedule_delay: 5000
-        # Configure maximum allowed time (in milliseconds) to export data.
+        # Configure maximum allowed time (in milliseconds) to export data. 
+        # Value must be non-negative. A value of 0 indicates no limit (infinity).
         # If omitted or null, 30000 is used.
         export_timeout: 30000
-        # Configure maximum queue size.
+        # Configure maximum queue size. Value must be positive.
         # If omitted or null, 2048 is used.
         max_queue_size: 2048
-        # Configure maximum batch size.
+        # Configure maximum batch size. Value must be positive.
         # If omitted or null, 512 is used.
         max_export_batch_size: 512
         # Configure exporter.
@@ -60,42 +65,53 @@ tracer_provider:
             # Configure endpoint, including the trace specific path.
             # If omitted or null, http://localhost:4318/v1/traces is used.
             endpoint: http://localhost:4318/v1/traces
-            # Configure certificate. Absolute path to certificate file.
+            # Configure certificate. 
+            # Absolute path to certificate file.
             # If omitted or null, system default certificate verification is used for secure connections.
             certificate:
-            # Configure mTLS private client key. Absolute path to client key in PEM format. If set, .client_certificate must also be set.
+            # Configure mTLS private client key. 
+            # Absolute path to client key in PEM format. If set, .client_certificate must also be set.
             # If omitted or null, mTLS is not used.
             client_key:
-            # Configure mTLS client certificate. Absolute path to certificate file. If set, .client_key must also be set.
+            # Configure mTLS client certificate. 
+            # Absolute path to certificate file. If set, .client_key must also be set.
             # If omitted or null, mTLS is not used.
             client_certificate:
-            # Configure compression. Values include: gzip, none. Implementations may support other compression algorithms.
+            # Configure compression.
+            # Values include: gzip, none. Implementations may support other compression algorithms.
             # If omitted or null, none is used.
             compression: gzip
-            # Configure max time (in milliseconds) to wait for each export.
+            # Configure max time (in milliseconds) to wait for each export. 
+            # Value must be non-negative. A value of 0 indicates no limit (infinity).
             # If omitted or null, 10000 is used.
             timeout: 10000
             # Configure headers. Entries have higher priority than entries from .headers_list.
             # If an entry's .value is null, the entry is ignored.
             headers: []
   # Configure span limits. See also attribute_limits.
   limits:
-    # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit.
+    # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. 
+    # Value must be non-negative.
     # If omitted or null, there is no limit.
     attribute_value_length_limit:
-    # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit.
+    # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. 
+    # Value must be non-negative.
     # If omitted or null, 128 is used.
     attribute_count_limit: 128
-    # Configure max span event count.
+    # Configure max span event count. 
+    # Value must be non-negative.
     # If omitted or null, 128 is used.
     event_count_limit: 128
-    # Configure max span link count.
+    # Configure max span link count. 
+    # Value must be non-negative.
     # If omitted or null, 128 is used.
     link_count_limit: 128
-    # Configure max attributes per span event.
+    # Configure max attributes per span event. 
+    # Value must be non-negative.
     # If omitted or null, 128 is used.
     event_attribute_count_limit: 128
-    # Configure max attributes per span link.
+    # Configure max attributes per span link. 
+    # Value must be non-negative.
     # If omitted or null, 128 is used.
     link_attribute_count_limit: 128
   # Configure the sampler.
@@ -135,10 +151,12 @@ meter_provider:
   readers:
     - # Configure a periodic metric reader.
       periodic:
-        # Configure delay interval (in milliseconds) between start of two consecutive exports.
+        # Configure delay interval (in milliseconds) between start of two consecutive exports. 
+        # Value must be non-negative.
         # If omitted or null, 60000 is used.
         interval: 60000
-        # Configure maximum allowed time (in milliseconds) to export data.
+        # Configure maximum allowed time (in milliseconds) to export data. 
+        # Value must be non-negative. A value of 0 indicates no limit (infinity).
         # If omitted or null, 30000 is used.
         timeout: 30000
         # Configure exporter.
@@ -148,31 +166,39 @@ meter_provider:
             # Configure endpoint, including the metric specific path.
             # If omitted or null, http://localhost:4318/v1/metrics is used.
             endpoint: http://localhost:4318/v1/metrics
-            # Configure certificate. Absolute path to certificate file.
+            # Configure certificate. 
+            # Absolute path to certificate file.
             # If omitted or null, system default certificate verification is used for secure connections.
             certificate:
-            # Configure mTLS private client key. Absolute path to client key in PEM format. If set, .client_certificate must also be set.
+            # Configure mTLS private client key. 
+            # Absolute path to client key in PEM format. If set, .client_certificate must also be set.
             # If omitted or null, mTLS is not used.
             client_key:
-            # Configure mTLS client certificate. Absolute path to certificate file. If set, .client_key must also be set.
+            # Configure mTLS client certificate. 
+            # Absolute path to certificate file. If set, .client_key must also be set.
             # If omitted or null, mTLS is not used.
             client_certificate:
-            # Configure compression. Values include: gzip, none. Implementations may support other compression algorithms.
+            # Configure compression.
+            # Values include: gzip, none. Implementations may support other compression algorithms.
             # If omitted or null, none is used.
             compression: gzip
-            # Configure max time (in milliseconds) to wait for each export.
+            # Configure max time (in milliseconds) to wait for each export. 
+            # Value must be non-negative. A value of 0 indicates no limit (infinity).
             # If omitted or null, 10000 is used.
             timeout: 10000
             # Configure headers. Entries have higher priority than entries from .headers_list.
             # If an entry's .value is null, the entry is ignored.
             headers: []
-            # Configure temporality preference. Values include: cumulative, delta, low_memory. For behavior of values, see /~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md.
+            # Configure temporality preference. 
+            # Values include: cumulative, delta, low_memory. For behavior of values, see /~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md.
             # If omitted or null, cumulative is used.
             temporality_preference: cumulative
-            # Configure default histogram aggregation. Values include: explicit_bucket_histogram, base2_exponential_bucket_histogram. For behavior of values, see /~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md.
+            # Configure default histogram aggregation. 
+            # Values include: explicit_bucket_histogram, base2_exponential_bucket_histogram. For behavior of values, see /~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md.
             # If omitted or null, explicit_bucket_histogram is used.
             default_histogram_aggregation: explicit_bucket_histogram
-  # Configure the exemplar filter. Values include: trace_based, always_on, always_off. For behavior of values see /~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#metrics-sdk-configuration.
+  # Configure the exemplar filter. 
+  # Values include: trace_based, always_on, always_off. For behavior of values see /~https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#metrics-sdk-configuration.
   # If omitted or null, trace_based is used.
   exemplar_filter: trace_based
 # Configure logger provider.
@@ -182,46 +208,55 @@ logger_provider:
   processors:
     - # Configure a batch log record processor.
       batch:
-        # Configure delay interval (in milliseconds) between two consecutive exports.
+        # Configure delay interval (in milliseconds) between two consecutive exports. 
+        # Value must be non-negative.
         # If omitted or null, 1000 is used.
         schedule_delay: 1000
-        # Configure maximum allowed time (in milliseconds) to export data.
+        # Configure maximum allowed time (in milliseconds) to export data. 
+        # Value must be non-negative. A value of 0 indicates no limit (infinity).
         # If omitted or null, 30000 is used.
         export_timeout: 30000
-        # Configure maximum queue size.
+        # Configure maximum queue size. Value must be positive.
         # If omitted or null, 2048 is used.
         max_queue_size: 2048
-        # Configure maximum batch size.
+        # Configure maximum batch size. Value must be positive.
         # If omitted or null, 512 is used.
         max_export_batch_size: 512
         # Configure exporter.
         exporter:
           # Configure exporter to be OTLP with HTTP transport.
           otlp_http:
             endpoint: http://localhost:4318/v1/logs
-            # Configure certificate. Absolute path to certificate file.
+            # Configure certificate. 
+            # Absolute path to certificate file.
             # If omitted or null, system default certificate verification is used for secure connections.
             certificate:
-            # Configure mTLS private client key. Absolute path to client key in PEM format. If set, .client_certificate must also be set.
+            # Configure mTLS private client key. 
+            # Absolute path to client key in PEM format. If set, .client_certificate must also be set.
             # If omitted or null, mTLS is not used.
             client_key:
-            # Configure mTLS client certificate. Absolute path to certificate file. If set, .client_key must also be set.
+            # Configure mTLS client certificate. 
+            # Absolute path to certificate file. If set, .client_key must also be set.
             # If omitted or null, mTLS is not used.
             client_certificate:
-            # Configure compression. Values include: gzip, none. Implementations may support other compression algorithms.
+            # Configure compression.
+            # Values include: gzip, none. Implementations may support other compression algorithms.
             # If omitted or null, none is used.
             compression: gzip
-            # Configure max time (in milliseconds) to wait for each export.
+            # Configure max time (in milliseconds) to wait for each export. 
+            # Value must be non-negative. A value of 0 indicates no limit (infinity).
             # If omitted or null, 10000 is used.
             timeout: 10000
             # Configure headers. Entries have higher priority than entries from .headers_list.
             # If an entry's .value is null, the entry is ignored.
             headers: []
   # Configure log record limits. See also attribute_limits.
   limits:
-    # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit.
+    # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. 
+    # Value must be non-negative.
     # If omitted or null, there is no limit.
     attribute_value_length_limit:
-    # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit.
+    # Configure max attribute count. Overrides .attribute_limits.attribute_count_limit. 
+    # Value must be non-negative.
     # If omitted or null, 128 is used.
     attribute_count_limit: 128