Skip to content

Commit

Permalink
Lay initial groundwork for file configuration (#3360)
Browse files Browse the repository at this point in the history
Initial followup to [OTEP
#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
  • Loading branch information
jack-berg authored Apr 12, 2023
1 parent b1207ff commit 9fc6984
Show file tree
Hide file tree
Showing 3 changed files with 91 additions and 0 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ release.

### SDK Configuration

- Lay initial groundwork for file configuration
([#3360](https://github.com/open-telemetry/opentelemetry-specification/pull/3360))

### Telemetry Schemas

### Common
Expand Down
73 changes: 73 additions & 0 deletions specification/configuration/file-configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# File Configuration

**Status**: [Experimental](../document-status.md)

<!-- toc -->

- [Overview](#overview)
- [Configuration Model](#configuration-model)
* [Stability Definition](#stability-definition)
- [Configuration file](#configuration-file)
- [SDK Configuration](#sdk-configuration)
* [In-Memory Configuration Model](#in-memory-configuration-model)
* [Operations](#operations)
- [References](#references)

<!-- tocstop -->

## 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 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 Model

The configuration model is defined
in [./schema/](./schema/opentelemetry_configuration.json) using
the [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 [Configuration Model](#configuration-model).

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.

### In-Memory Configuration Model

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

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))
Original file line number Diff line number Diff line change
@@ -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"
]
}

0 comments on commit 9fc6984

Please sign in to comment.