|
| 1 | +# File Configuration |
| 2 | + |
| 3 | +**Status**: [Experimental](../document-status.md) |
| 4 | + |
| 5 | +<!-- toc --> |
| 6 | + |
| 7 | +- [Overview](#overview) |
| 8 | +- [Configuration Model](#configuration-model) |
| 9 | + * [Stability Definition](#stability-definition) |
| 10 | +- [Configuration file](#configuration-file) |
| 11 | +- [SDK Configuration](#sdk-configuration) |
| 12 | + * [In-Memory Configuration Model](#in-memory-configuration-model) |
| 13 | + * [Operations](#operations) |
| 14 | +- [References](#references) |
| 15 | + |
| 16 | +<!-- tocstop --> |
| 17 | + |
| 18 | +## Overview |
| 19 | + |
| 20 | +File configuration provides a mechanism for configuring OpenTelemetry which is |
| 21 | +more expressive and full-featured than |
| 22 | +the [environment variable](../sdk-environment-variables.md) based scheme, and |
| 23 | +language agnostic in a way not possible |
| 24 | +with [programmatic configuration](../sdk-configuration.md#programmatic). |
| 25 | + |
| 26 | +File configuration defines a [Configuration Model](#configuration-model), |
| 27 | +which can be expressed in a [configuration file](#configuration-file). |
| 28 | +Configuration files can be validated against the Configuration Schema, and |
| 29 | +interpreted to produce configured OpenTelemetry components. |
| 30 | + |
| 31 | +## Configuration Model |
| 32 | + |
| 33 | +The configuration model is defined |
| 34 | +in [./schema/](./schema/opentelemetry_configuration.json) using |
| 35 | +the [JSON Schema](https://json-schema.org/). |
| 36 | + |
| 37 | +### Stability Definition |
| 38 | + |
| 39 | +TODO: define stability guarantees and backwards compatibility |
| 40 | + |
| 41 | +## Configuration file |
| 42 | + |
| 43 | +A configuration file is a file representation of |
| 44 | +the [Configuration Model](#configuration-model). |
| 45 | + |
| 46 | +TODO: define acceptable file formats |
| 47 | + |
| 48 | +TODO: define environment variable substitution |
| 49 | + |
| 50 | +## SDK Configuration |
| 51 | + |
| 52 | +SDK configuration defines the interfaces and operations that SDKs are expected |
| 53 | +to expose to enable file based configuration. |
| 54 | + |
| 55 | +### In-Memory Configuration Model |
| 56 | + |
| 57 | +SDKs SHOULD provide an in-memory representation of |
| 58 | +the [Configuration Model](#configuration-model). In general, SDKs are encouraged |
| 59 | +to provide this in-memory representation in a manner that is idiomatic for their |
| 60 | +language. If an SDK needs to expose a class or interface, the |
| 61 | +name `Configuration` is RECOMMENDED. |
| 62 | + |
| 63 | +### Operations |
| 64 | + |
| 65 | +TODO: define how to parse configuration file to configuration model |
| 66 | + |
| 67 | +TODO: define how to apply configuration model to produce configured sdk |
| 68 | +components |
| 69 | + |
| 70 | +## References |
| 71 | + |
| 72 | +* Configuration |
| 73 | + proposal ([OTEP #225](https://github.com/open-telemetry/oteps/pull/225)) |
0 commit comments