@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. The full set of variables this package consumes:

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_NODE_RESOURCE_DETECTORS	Resource detectors to enable (env, host, os, process, serviceinstance, all, none)
OTEL_PROPAGATORS	Propagators: tracecontext, baggage, b3, b3multi
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_TRACES_SAMPLER	Sampler name (e.g. parentbased_always_on, traceidratio)
OTEL_TRACES_SAMPLER_ARG	Sampler argument (e.g. ratio value)
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP endpoint (all signals)
OTEL_EXPORTER_OTLP_HEADERS	OTLP headers (all signals)
OTEL_EXPORTER_OTLP_PROTOCOL	OTLP protocol: grpc, http/protobuf, http/json
OTEL_EXPORTER_OTLP_TIMEOUT	OTLP request timeout (all signals)
OTEL_EXPORTER_OTLP_COMPRESSION	OTLP compression (all signals): gzip, none
OTEL_EXPORTER_OTLP_CERTIFICATE	OTLP server CA certificate file (all signals)
OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE	OTLP client certificate file for mTLS (all signals)
OTEL_EXPORTER_OTLP_CLIENT_KEY	OTLP client private key file for mTLS (all signals)
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	Per-signal override (traces)
OTEL_EXPORTER_OTLP_TRACES_HEADERS	Per-signal override (traces)
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL	Per-signal override (traces)
OTEL_EXPORTER_OTLP_TRACES_TIMEOUT	Per-signal override (traces)
OTEL_EXPORTER_OTLP_TRACES_COMPRESSION	Per-signal override (traces)
OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE	Per-signal override (traces)
OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE	Per-signal override (traces)
OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY	Per-signal override (traces)
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	Per-signal override (metrics)
OTEL_EXPORTER_OTLP_METRICS_HEADERS	Per-signal override (metrics)
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL	Per-signal override (metrics)
OTEL_EXPORTER_OTLP_METRICS_TIMEOUT	Per-signal override (metrics)
OTEL_EXPORTER_OTLP_METRICS_COMPRESSION	Per-signal override (metrics)
OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE	Per-signal override (metrics)
OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE	Per-signal override (metrics)
OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY	Per-signal override (metrics)
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE	Metric temporality preference: cumulative, delta, lowmemory
OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION	Default histogram aggregation: explicit_bucket_histogram, base2_exponential_bucket_histogram
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Per-signal override (logs)
OTEL_EXPORTER_OTLP_LOGS_HEADERS	Per-signal override (logs)
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL	Per-signal override (logs)
OTEL_EXPORTER_OTLP_LOGS_TIMEOUT	Per-signal override (logs)
OTEL_EXPORTER_OTLP_LOGS_COMPRESSION	Per-signal override (logs)
OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE	Per-signal override (logs)
OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE	Per-signal override (logs)
OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY	Per-signal override (logs)
OTEL_EXPORTER_PROMETHEUS_HOST	Prometheus exporter bind host
OTEL_EXPORTER_PROMETHEUS_PORT	Prometheus exporter bind port
OTEL_METRIC_EXPORT_INTERVAL	Periodic metric reader export interval (ms)
OTEL_METRIC_EXPORT_TIMEOUT	Periodic metric reader export timeout (ms)
OTEL_METRICS_EXEMPLAR_FILTER	Exemplar filter: always_on, always_off, trace_based
OTEL_BSP_SCHEDULE_DELAY	Batch span processor: schedule delay (ms)
OTEL_BSP_EXPORT_TIMEOUT	Batch span processor: export timeout (ms)
OTEL_BSP_MAX_QUEUE_SIZE	Batch span processor: max queue size
OTEL_BSP_MAX_EXPORT_BATCH_SIZE	Batch span processor: max export batch size
OTEL_BLRP_SCHEDULE_DELAY	Batch log record processor: schedule delay (ms)
OTEL_BLRP_EXPORT_TIMEOUT	Batch log record processor: export timeout (ms)
OTEL_BLRP_MAX_QUEUE_SIZE	Batch log record processor: max queue size
OTEL_BLRP_MAX_EXPORT_BATCH_SIZE	Batch log record processor: max export batch size
OTEL_ATTRIBUTE_COUNT_LIMIT	Default max attributes per span/log/event/link
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT	Default max attribute value length
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT	Max attributes per span
OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT	Max span attribute value length
OTEL_SPAN_EVENT_COUNT_LIMIT	Max events per span
OTEL_SPAN_LINK_COUNT_LIMIT	Max links per span
OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT	Max attributes per span event
OTEL_LINK_ATTRIBUTE_COUNT_LIMIT	Max attributes per span link
OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT	Max attributes per log record
OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT	Max log record attribute value length

See src/EnvironmentConfigFactory.ts for the exact parsing logic.

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)
• 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 constant in scripts/generate-config.js

2. Run from this package directory:

   npm run generate:config

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

4. Update SUPPORTED_FILE_FORMAT_MAJOR / SUPPORTED_FILE_FORMAT_MINOR in src/FileConfigFactory.ts if the new schema version is outside the currently-supported range

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

The generation script (scripts/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)
• Removes the duplicate type declarations that json-schema-to-typescript emits for structurally-identical sub-schemas (e.g. the second 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
• 1.1

For a per-field view of which schema fields the SDK currently applies, see the JS row in the cross-SDK language support status doc maintained in the opentelemetry-configuration repo. That doc is the source of truth for declarative-config conformance across all SDKs.

Useful links

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

License

Apache 2.0 - See LICENSE for more information.