diff --git a/CHANGELOG.md b/CHANGELOG.md index 8de6d0fc0c6..e41f7297294 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,9 @@ release. ### SDK Configuration +- Define file configuration parse and create operations. + ([#3437](https://github.com/open-telemetry/opentelemetry-specification/pull/3437)) + ### Common ### Supplementary Guidelines diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 6e62a25d998..e9a40ba4d26 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -15,6 +15,8 @@ linkTitle: File - [SDK Configuration](#sdk-configuration) * [In-Memory Configuration Model](#in-memory-configuration-model) * [Operations](#operations) + + [Parse](#parse) + + [Create](#create) - [References](#references) @@ -66,10 +68,54 @@ name `Configuration` is RECOMMENDED. ### Operations -TODO: define how to parse configuration file to configuration model +SDK implementations of configuration MUST provide the following operations. -TODO: define how to apply configuration model to produce configured sdk -components +Note: Because these operations are stateless pure functions, they are not +defined as part of any type, class, interface, etc. SDKs may organize them in +whatever manner is idiomatic for the language. + +TODO: Add operation to update SDK components with new configuration for usage +with OpAmp + +#### Parse + +Parse and validate a [configuration file](#configuration-file). + +**Parameters:** + +* `file`: The [configuration file](#configuration-file) to parse. This MAY be a + file path, or language specific file data structure, or a stream of a file's content. + +**Returns:** [configuration model](#in-memory-configuration-model) + +This SHOULD return an error if: + +* The `file` doesn't exist or is invalid +* The parsed `file` content does not conform to + the [configuration model](#configuration-model) schema. + +TODO: define behavior if some portion of configuration model is not supported + +#### Create + +Interpret [configuration model](#in-memory-configuration-model) and return SDK components. + +**Parameters:** + +* `configuration` - The configuration model. + +**Returns:** Top level SDK components: + +* `TracerProvider` +* `MeterProvider` +* `LoggerProvider` +* `Propagators` + +The multiple responses MAY be returned using a tuple, or some other data +structure encapsulating the components. + +This SHOULD return an error if it encounters an error in `configuration` (i.e. +fail fast). ## References