OpenTelemetry Declarative Configuration

Note: This is an experimental package under active development. New releases may include breaking changes.

This package implements the OpenTelemetry declarative configuration specification for Node.js. It parses configuration from a YAML file or environment variables and produces a ConfigurationModel that the OpenTelemetry SDK uses to initialize providers.

Installation

npm install @opentelemetry/configuration
Copy

Usage

createConfigFactory() selects the configuration source automatically:

• If OTEL_CONFIG_FILE points to a valid .yaml/.yml file, configuration is read from that file.
• Otherwise, configuration is assembled from standard OpenTelemetry environment variables.

import { createConfigFactory } from '@opentelemetry/configuration';

const factory = createConfigFactory();
const config = factory.getConfigModel();
Copy

YAML file configuration

Set OTEL_CONFIG_FILE to the path of your configuration file:

OTEL_CONFIG_FILE=./otel-config.yaml node app.js
Copy

Example:

file_format: "1.0"
resource:
  attributes:
    - name: service.name
      value: my-service
tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/traces
Copy

Environment variable substitution is supported using ${VAR_NAME}, ${VAR_NAME:-default}, ${env:VAR_NAME}, and ${env:VAR_NAME:-default} syntax. Use $$ for a literal $.

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_ENDPOINT:-http://localhost:4318}/v1/traces
Copy

Environment variable configuration

When no config file is set, the factory reads from the standard OpenTelemetry SDK environment variables:

Development

Generated files

src/generated/ is auto-generated — do not edit manually. It contains:

• types.ts — TypeScript interfaces derived from the JSON schema (via json-schema-to-typescript)
• schema.ts — The raw JSON schema exported as a constant (retained for reference; not used at runtime)
• validator.js — Pre-compiled ajv validator (ahead-of-time compiled from the schema at build time; eliminates runtime ajv.compile())
• validator.d.ts — TypeScript declarations for validator.js

Regenerating after a schema version bump

1. Update the CONFIG_VERSION variable in scripts/config/generate-config.sh

2. Run from this package directory:

   npm run generate:config
   Copy

3. Review the diff in src/generated/types.ts, src/generated/schema.ts, and src/generated/validator.js

4. Update supportedFileVersionPattern in src/FileConfigFactory.ts if the new version falls outside the current regex

5. Update EnvironmentConfigFactory.ts and utils.ts if new fields need env var mapping

The generation script (scripts/config/generate-config.js) handles several post-processing steps:

• Renames the root type from OpenTelemetryConfiguration to ConfigurationModel
• Makes file_format optional (required at parse time but not needed when constructing the model in code)
• Replaces narrow index signatures ([k: string]: {} | null) with [k: string]: unknown
• Deduplicates structurally-identical TLS types (GrpcTls1/HttpTls1 → GrpcTls/HttpTls)
• Produces a pre-compiled ajv validator (validator.js + validator.d.ts) for use at runtime

Defaults

Both config paths apply the same spec-defined defaults so consumers see consistent behaviour regardless of config source:

FileConfigFactory applies these via applyConfigDefaults() after schema validation. EnvironmentConfigFactory applies them via initializeDefaultConfiguration() in the constructor, then overlays env var values on top.

One intentional exception in both paths: AttributeNameValue.type is not defaulted even though the spec says "if omitted, string is used". This is a semantic default for SDK code interpreting resource attributes, not a config-parser concern. SDK code reading resource.attributes should apply attr.type ?? 'string' at the point of use.

Supported schema versions

• 1.0

Useful links

• OpenTelemetry Declarative Configuration Specification
• OpenTelemetry for Node.js
• OpenTelemetry Community

License

Apache 2.0 - See LICENSE for more information.