From 2ac4970925cd7b4808b21de1f45e2c77e9e07f3e Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 3 Apr 2023 14:14:39 -0500 Subject: [PATCH 1/7] Lay initial groundwork for file configuration --- .../configuration/file-configuration.md | 69 +++++++++++++++++++ .../schema/opentelemetry_configuration.json | 15 ++++ verify1.14.0 | 0 3 files changed, 84 insertions(+) create mode 100644 specification/configuration/file-configuration.md create mode 100644 specification/configuration/schema/opentelemetry_configuration.json create mode 100644 verify1.14.0 diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md new file mode 100644 index 00000000000..2007c39b4a2 --- /dev/null +++ b/specification/configuration/file-configuration.md @@ -0,0 +1,69 @@ +# File Configuration + +**Status**: [Experimental](../document-status.md) + + + +- [Overview](#overview) +- [Configuration Schema](#configuration-schema) + * [Stability Definition](#stability-definition) +- [Configuration file](#configuration-file) +- [SDK Configuration](#sdk-configuration) + * [Configuration Model](#configuration-model) + * [Operations](#operations) +- [References](#references) + + + +## Overview + +File configuration provides a mechanism for configuring OpenTelemetry which is +more expressive and full-featured than +the [environment variable](../sdk-environment-variables.md) based scheme, and +language agnostic in a way not possible +with [programmatic configuration](../sdk-configuration.md#programmatic). + +File configuration defines a [Configuration Schema](#configuration-schema), +which can be expressed in a [configuration file](#configuration-file). +Configuration files can be validated against the Configuration Schema, and +interpreted to produce configured OpenTelemetry components. + +## Configuration Schema + +The configuration schema is defined in [./schema/](./schema) +using [JSON Schema](https://json-schema.org/). + +### Stability Definition + +TODO: define stability guarantees and backwards compatibility + +## Configuration file + +A configuration file is a file representation of the model defined +by [./Configuration Schema](#configuration-schema). + +TODO: define acceptable file formats + +TODO: define environment variable substitution + +## SDK Configuration + +SDK configuration defines the interfaces and operations that SDKs are expected +to expose to enable file based configuration. + +### Configuration Model + +`Configuration` is an in-memory representation of the model defined +by [./Configuration Schema](#configuration-schema). + +### Operations + +TODO: define how to parse configuration file to configuration model + +TODO: define how to apply configuration model to produce configured sdk +components + +## References + +* Configuration + proposal ([OTEP #225](https://github.com/open-telemetry/oteps/pull/225)) diff --git a/specification/configuration/schema/opentelemetry_configuration.json b/specification/configuration/schema/opentelemetry_configuration.json new file mode 100644 index 00000000000..5d4f202f5d1 --- /dev/null +++ b/specification/configuration/schema/opentelemetry_configuration.json @@ -0,0 +1,15 @@ +{ + "$id": "https://opentelemetry.io/otelconfig/OpenTelemetryConfiguration", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "OpenTelemetryConfiguration", + "type": "object", + "additionalProperties": false, + "properties": { + "file_format": { + "type": "number" + } + }, + "required": [ + "file_format" + ] +} \ No newline at end of file diff --git a/verify1.14.0 b/verify1.14.0 new file mode 100644 index 00000000000..e69de29bb2d From 7f75031ba5ca21f5640c8a3cefa932de7b2c24ab Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 3 Apr 2023 14:25:31 -0500 Subject: [PATCH 2/7] Add changelog entry --- CHANGELOG.md | 3 +++ verify1.14.0 | 0 2 files changed, 3 insertions(+) delete mode 100644 verify1.14.0 diff --git a/CHANGELOG.md b/CHANGELOG.md index 09c20979e87..ee8b4927246 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -65,6 +65,9 @@ release. ### SDK Configuration +- Lay initial groundwork for file configuration + ([#3360](https://github.com/open-telemetry/opentelemetry-specification/pull/3360)) + ### Telemetry Schemas ### Common diff --git a/verify1.14.0 b/verify1.14.0 deleted file mode 100644 index e69de29bb2d..00000000000 From 6f68f8850f887e3abe54afbb1d932ecd4c459d7f Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 3 Apr 2023 15:53:31 -0500 Subject: [PATCH 3/7] Fix dir link --- specification/configuration/file-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 2007c39b4a2..9d3d90d53e7 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -30,7 +30,7 @@ interpreted to produce configured OpenTelemetry components. ## Configuration Schema -The configuration schema is defined in [./schema/](./schema) +The configuration schema is defined in [./schema/](./schema/) using [JSON Schema](https://json-schema.org/). ### Stability Definition From afb26d6466b337f8e475c12ca2c6462b7cc4c4ab Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 3 Apr 2023 16:20:37 -0500 Subject: [PATCH 4/7] docfx --- specification/configuration/file-configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 9d3d90d53e7..586140e9bb3 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -30,7 +30,8 @@ interpreted to produce configured OpenTelemetry components. ## Configuration Schema -The configuration schema is defined in [./schema/](./schema/) +The configuration schema is defined +in [./schema/](./schema/opentelemetry_configuration.json) using [JSON Schema](https://json-schema.org/). ### Stability Definition From 580befd4004522497af36dce09451bb7c594658e Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Tue, 4 Apr 2023 16:09:12 -0500 Subject: [PATCH 5/7] Configuration Schema -> Configuration Model --- .../configuration/file-configuration.md | 24 +++++++++---------- .../schema/opentelemetry_configuration.json | 2 +- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 586140e9bb3..42cebd2b0b0 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -5,11 +5,11 @@ - [Overview](#overview) -- [Configuration Schema](#configuration-schema) +- [Configuration Model](#configuration-model) * [Stability Definition](#stability-definition) - [Configuration file](#configuration-file) - [SDK Configuration](#sdk-configuration) - * [Configuration Model](#configuration-model) + * [In-Memory Configuration Model](#in-memory-configuration-model) * [Operations](#operations) - [References](#references) @@ -23,16 +23,16 @@ the [environment variable](../sdk-environment-variables.md) based scheme, and language agnostic in a way not possible with [programmatic configuration](../sdk-configuration.md#programmatic). -File configuration defines a [Configuration Schema](#configuration-schema), +File configuration defines a [Configuration Model](#configuration-model), which can be expressed in a [configuration file](#configuration-file). Configuration files can be validated against the Configuration Schema, and interpreted to produce configured OpenTelemetry components. -## Configuration Schema +## Configuration Model -The configuration schema is defined -in [./schema/](./schema/opentelemetry_configuration.json) -using [JSON Schema](https://json-schema.org/). +The configuration model is defined +in [./schema/](./schema/opentelemetry_configuration.json) using +the [JSON Schema](https://json-schema.org/). ### Stability Definition @@ -40,8 +40,8 @@ TODO: define stability guarantees and backwards compatibility ## Configuration file -A configuration file is a file representation of the model defined -by [./Configuration Schema](#configuration-schema). +A configuration file is a file representation of +the [Configuration Model](#configuration-model). TODO: define acceptable file formats @@ -52,10 +52,10 @@ TODO: define environment variable substitution SDK configuration defines the interfaces and operations that SDKs are expected to expose to enable file based configuration. -### Configuration Model +### In-Memory Configuration Model -`Configuration` is an in-memory representation of the model defined -by [./Configuration Schema](#configuration-schema). +SDKs SHOULD define an in-memory representation of +the [Configuration Model](#configuration-model) called `Configuration`. ### Operations diff --git a/specification/configuration/schema/opentelemetry_configuration.json b/specification/configuration/schema/opentelemetry_configuration.json index 5d4f202f5d1..2dc9cb04f8a 100644 --- a/specification/configuration/schema/opentelemetry_configuration.json +++ b/specification/configuration/schema/opentelemetry_configuration.json @@ -12,4 +12,4 @@ "required": [ "file_format" ] -} \ No newline at end of file +} From 1a69ff1900de8ba3e9397e1b8acef98176ab3a70 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Tue, 11 Apr 2023 11:40:34 -0500 Subject: [PATCH 6/7] PR feedback --- specification/configuration/file-configuration.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 42cebd2b0b0..988ef434ce5 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -54,8 +54,11 @@ to expose to enable file based configuration. ### In-Memory Configuration Model -SDKs SHOULD define an in-memory representation of -the [Configuration Model](#configuration-model) called `Configuration`. +SDKs SHOULD provide an in-memory representation of +the [Configuration Model](#configuration-model). In general, SDKs are encouraged +to provide this in-memory representation in a manner that is idiomatic for their +language. If an SDK needs to expose a class or interface, the +name `Configuration` is recommended. ### Operations From 97965ff6409979e2db55b9213b219906625a640f Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Tue, 11 Apr 2023 11:42:10 -0500 Subject: [PATCH 7/7] normative recommended --- specification/configuration/file-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 988ef434ce5..dbe949b2c7b 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -58,7 +58,7 @@ SDKs SHOULD provide an in-memory representation of the [Configuration Model](#configuration-model). In general, SDKs are encouraged to provide this in-memory representation in a manner that is idiomatic for their language. If an SDK needs to expose a class or interface, the -name `Configuration` is recommended. +name `Configuration` is RECOMMENDED. ### Operations