@opentelemetry/configuration

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

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();

YAML file configuration

Set OTEL_CONFIG_FILE to the path of your configuration file:

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

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

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

Environment variable configuration

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

Variable	Description
OTEL_SDK_DISABLED	Disable the SDK entirely
OTEL_LOG_LEVEL	Internal SDK log level
OTEL_SERVICE_NAME	Service name resource attribute
OTEL_RESOURCE_ATTRIBUTES	Comma-separated resource attributes
OTEL_TRACES_EXPORTER	Traces exporter(s): otlp, console, none
OTEL_METRICS_EXPORTER	Metrics exporter(s): otlp, prometheus, console, none
OTEL_LOGS_EXPORTER	Logs exporter(s): otlp, console, none
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP protocol: grpc, http/protobuf, http/json
OTEL_PROPAGATORS	Propagators: tracecontext, baggage, b3, b3multi

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

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

• Run from this package directory:

  npm run generate:config
  

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

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

• 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:

Field	Default
disabled	false
log_level	info
attribute_limits.attribute_count_limit	128

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.