File-based configuration for Node.js in Splunk Observability Cloud

Overview

Declarative Configuration

Declarative configuration is enabled through a single environment variable and uses a structured configuration file validated against the OpenTelemetry Configuration Schema. When enabled, the configuration file becomes the authoritative source of configuration for the SDK and auto‑instrumentation.

Environment Variable

Activation

To enable file‑based configuration, set:

OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/config.yaml

When OTEL_EXPERIMENTAL_CONFIG_FILE is set:

1. The file at the specified path is parsed into a configuration model.
2. The model is used to create fully configured SDK components.
3. All other SDK environment variables must be ignored, except those referenced inside the configuration file for environment variable substitution.

This ensures consistency between the structured configuration model and the flat environment variable model.

Customizing configuration models

Users may merge multiple configuration sources by:

• parsing multiple configuration files and merging their models,

• overlaying selected environment variables onto the parsed model,

• applying custom logic before creating SDK components.

Recommended starting points

OpenTelemetry provides two reference configuration files:

• otel-sdk-migration-config.yaml — includes environment variable substitution,

• otel-sdk-config.yaml — a clean starting point without substitutions.

Starter Configuration Example

The example below illustrates a fully structured configuration file that can be used as a reference when enabling file‑based configuration for Splunk OpenTelemetry for Node.js.

file_format: "1.0-rc.2"
disabled: false
log_level: warn
distribution:
  splunk:
    use_bundled_instrumentations: true
    runtime_metrics:
      collection_interval: 30000
    instrumentations:
      http:
        trace_response_header_enabled: true
      redis:
        include_command_args: true
    profiling:
      exporter:
        otlp_log_http:
          endpoint: "http://localhost:4318/v1/logs"
      always_on:
        cpu_profiler:
          sampling_interval: 1000
        memory_profiler:
      callgraphs:
        sampling_interval: 1
        selection_probability: 0.01
logger_provider:
  processors:
    - batch:
        schedule_delay: 5000
        export_timeout: 30000
        max_queue_size: 1024
        max_export_batch_size: 256
        exporter:
          otlp_http:
            endpoint: "http://:4318/v1/logs"
            compression: gzip
            timeout: 10000
            encoding: protobuf
  limits:
    attribute_value_length_limit: 8192
    attribute_count_limit: 512
meter_provider:
  readers:
    - periodic:
        interval: 60000
        timeout: 30000
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/metrics
            compression: gzip
            timeout: 10000
            encoding: protobuf
            temporality_preference: delta
            default_histogram_aggregation: base2_exponential_bucket_histogram
        cardinality_limits:
          default: 2000
          counter: 2000
          gauge: 2000
          histogram: 2000
          observable_counter: 2000
          observable_gauge: 2000
          observable_up_down_counter: 2000
          up_down_counter: 2000
  views:
    - selector:
        instrument_name: my-instrument
        instrument_type: histogram
        unit: ms
        meter_name: my-meter
        meter_version: 1.0.0
        meter_schema_url: https://opentelemetry.io/schemas/1.16.0
      stream:
        name: new_instrument_name
        description: new_description
        aggregation:
          explicit_bucket_histogram:
            boundaries: [0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000]
            record_min_max: true
        aggregation_cardinality_limit: 2000
        attribute_keys:
          included: [key1, key2]
          excluded: [key3]
propagator:
  composite:
    - tracecontext:
    - baggage:
    - b3:
    - b3multi:
  composite_list: "tracecontext,baggage,b3,b3multi,xray"
tracer_provider:
  processors:
    - batch:
        schedule_delay: 5000
        export_timeout: 30000
        max_queue_size: 2048
        max_export_batch_size: 256
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/traces
            headers:
              - name: api-key
                value: "1234"
            compression: gzip
            timeout: 10000
            encoding: protobuf
  sampler:
    parent_based:
      root:
        always_on:
      remote_parent_sampled:
        always_on:
      remote_parent_not_sampled:
        always_on:
      local_parent_sampled:
        always_on:
      local_parent_not_sampled:
        always_on:
resource:
  attributes:
    - name: service.name
      value: test_service
    - name: service.version
      value: "1.3.0"
    - name: string_key
      value: test_value
      type: string
    - name: bool_key
      value: true
      type: bool
    - name: int_key
      value: 1
      type: int

Supported configuration fields

Splunk OpenTelemetry Auto‑Instrumentation for Node.js supports a subset of the OpenTelemetry configuration schema, along with several Splunk‑specific extensions. The fields listed below represent the configuration areas that the Node.js implementation can currently parse and apply when using a file‑based configuration file. Fields not included here are ignored or not yet implemented.

Core OTel configuration

These fields define general SDK behavior and metadata:

• file_format — declares the schema version used by the configuration file

• disabled — enables or disables auto‑instrumentation

• log_level — controls SDK and instrumentation logging verbosity

• resource.attributes — defines service metadata such as service name, version, and custom attributes

• propagator — specifies which context propagation formats are enabled

Telemetry pipelines

These sections configure how traces, metrics, and logs are collected and exported:

• tracer_provider — tracing processors, exporters, and sampling configuration

• meter_provider — metric readers, exporters, and views

• logger_provider — log processors and exporters

Instrumentation configuration

The instrumentation section allows configuring individual instrumentations and their settings directly in the configuration file. Availability of specific options depends on the instrumentation implementation.

Splunk extensions

Splunk provides additional configuration options under the distribution.splunk section. These extensions complement the standard OTel configuration model and enable Splunk‑specific functionality such as:

• bundled instrumentations

• runtime metrics

• profiling (CPU, memory, callgraphs)

• Splunk‑specific instrumentation settings

• Splunk OTLP log exporter for profiling data