Skip to content

Commit 2031727

Browse files
authored
Lay initial groundwork for file configuration (open-telemetry#3360)
Initial followup to [OTEP open-telemetry#225](open-telemetry/oteps#225). This lays the initial groundwork for file configuration in the specification. There are placeholders TODOs for many various followup tasks. Additional work is also needed to figure out how to merge [SDK Configuration](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-configuration.md), [SDK Environment Variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md) and file configuration into a cohesive story. This PR proposes the configuration schema live in `opentelemetry-specification/specification/configuration/schema/`, which implies that at some point additional build steps will be needed to confirm changes to the schema are valid and allowed. cc @MrAlias, @codeboten
1 parent 056ddf5 commit 2031727

File tree

3 files changed

+91
-0
lines changed

3 files changed

+91
-0
lines changed

CHANGELOG.md

+3
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@ release.
3131

3232
### SDK Configuration
3333

34+
- Lay initial groundwork for file configuration
35+
([#3360](https://github.com/open-telemetry/opentelemetry-specification/pull/3360))
36+
3437
### Telemetry Schemas
3538

3639
### Common
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
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))
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"$id": "https://opentelemetry.io/otelconfig/OpenTelemetryConfiguration",
3+
"$schema": "https://json-schema.org/draft/2020-12/schema",
4+
"title": "OpenTelemetryConfiguration",
5+
"type": "object",
6+
"additionalProperties": false,
7+
"properties": {
8+
"file_format": {
9+
"type": "number"
10+
}
11+
},
12+
"required": [
13+
"file_format"
14+
]
15+
}

0 commit comments

Comments
 (0)