JSON Schema Definitions for OpenTelemetry Declarative Configuration

This repository contains the JSON schema that defines the OpenTelemetry configuration. This schema can be utilized to generate model code for implementations and to validate the structure of a configuration file. The repository comes as a result of OTEP #225, where JSON schema was chosen for the following reasons:

• support for client-side validation
• code generation
• broad support across languages

Starter templates

The examples directory contains a variety of sample configuration files to help get started and illustrate useful patterns. The following are noteworthy:

• sdk-migration-config.yaml: Includes env var substitution references to all standard env vars which map cleanly to declarative configuration (see notes in the example for the set of env vars which are not referenced). Note, SDKs parsing configuration files ignore all env vars besides those referenced via env var substitution. This is a great starting point for transitioning from env var based configuration to file based configuration.
• sdk-config.yaml: Represents the typical default configuration. This is a good starting point if you are not using env var based configuration or wish to transition fully to file based configuration. Note, SDKs parsing configuration files ignore all env vars besides those referenced via env var substitution.

Code generation

There are several tools available to generate code from a JSON schema. The following shows an example for generating code from the JSON schema in Go:

go-jsonschema \
    -p telemetry \
    --schema-package=https://opentelemetry.io/otelconfig/opentelemetry_configuration.json=github.com/open-telemetry/opentelemetry-collector/schema \
    ./schema/opentelemetry_configuration.json

Stability definition

Before reaching 1.0, each minor version change is equivalent to major version change. That is, there are no guarantees about compatibility and all changes are permitted. As of 1.0, we provide the following stability guarantees:

• For major version: No guarantees.
• For minor versions: TBD

Allowable changes:

• For major versions: All changes are permitted.
• For minor versions: TBD

Contributing

See CONTRIBUTING.md

Approvers (@open-telemetry/configuration-approvers):

• Brett McBride, Deakin University
• Marc Alff, Oracle

Find more about the approver role in community repository.

Maintainers (@open-telemetry/configuration-maintainers):

• Alex Boten, Honeycomb
• Jack Berg, New Relic
• Tristan Sloughter, MyDecisiveAI
• Tyler Yahn, Splunk

Find more about the maintainer role in community repository.