From e107198d0d82e344cc4112ca43fe0f31fc133eef Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Mon, 28 Oct 2024 13:43:35 -0500 Subject: [PATCH] Declarative config: clarify null vs empty (#4269) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #4181 cc @open-telemetry/configuration-approvers --------- Co-authored-by: Robert Pająk --- CHANGELOG.md | 3 ++ specification/configuration/data-model.md | 2 +- specification/configuration/sdk.md | 34 +++++++++++++++++------ 3 files changed, 30 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7215ad24c71..485b3ba69d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,9 @@ release. ### SDK Configuration +- Clarify declarative configuration parse requirements for null vs empty. + ([#4269](https://github.com/open-telemetry/opentelemetry-specification/pull/4269)) + ### Common ### Supplementary Guidelines diff --git a/specification/configuration/data-model.md b/specification/configuration/data-model.md index 6b7abcac269..4b3f9bfc52a 100644 --- a/specification/configuration/data-model.md +++ b/specification/configuration/data-model.md @@ -86,7 +86,7 @@ results are allowed) and an error describing the parse failure to the user. Node types MUST be interpreted after environment variable substitution takes place. This ensures the environment string representation of boolean, integer, -or floating point fields can be properly converted to expected types. +or floating point properties can be properly converted to expected types. It MUST NOT be possible to inject YAML structures by environment variables. For example, see references to `INVALID_MAP_VALUE` environment variable below. diff --git a/specification/configuration/sdk.md b/specification/configuration/sdk.md index 7baa0e18367..25024edecea 100644 --- a/specification/configuration/sdk.md +++ b/specification/configuration/sdk.md @@ -179,7 +179,24 @@ Parse and validate a [configuration file](./data-model.md#file-based-configurati Parse MUST perform [environment variable substitution](./data-model.md#environment-variable-substitution). -Parse MUST interpret null as equivalent to unset. +Parse MUST differentiate between properties that are missing and properties that +are present but null. For example, consider the following snippet, +noting `.meter_provider.views[0].stream.drop` is present but null: + +```yaml +meter_provider: + views: + - selector: + name: some.metric.name + stream: + aggregation: + drop: +``` + +As a result, the view stream should be configured with the `drop` aggregation. +Note that some aggregations have additional arguments, but `drop` does not. The +user MUST not be required to specify an empty object (i.e. `drop: {}`) in these +cases. When encountering a reference to a [SDK extension component](#sdk-extension-components) which is not built in to @@ -212,14 +229,15 @@ Interpret configuration model and return SDK components. The multiple responses MAY be returned using a tuple, or some other data structure encapsulating the components. -If a field is null or unset and a default value is defined, Create MUST ensure -the SDK component is configured with the default value. If a field is null or -unset and no default value is defined, Create SHOULD return an error. For -example, if configuring +If a property has a default value defined (i.e. is _not_ required) and is +missing or present but null, Create MUST ensure the SDK component is configured +with the default value. If a property is required and is missing or present but +null, Create SHOULD return an error. For example, if configuring the [span batching processor](../trace/sdk.md#batching-processor) and -the `scheduleDelayMillis` field is null or unset, the component is configured -with the default value of `5000`. However, if the `exporter` field is null or -unset, Create fails fast since there is no default value for `exporter`. +the `scheduleDelayMillis` property is missing or present but null, the component +is configured with the default value of `5000`. However, if the `exporter` +property is missing or present but null, Create fails fast since there is no +default value for `exporter`. When encountering a reference to a [SDK extension component](#sdk-extension-components) which is not built in to