File-based configuration for Java in Splunk Observability Cloud

Explains how file‑based YAML configuration is consumed by OpenTelemetry SDK autoconfiguration and by the Splunk Distribution of the OpenTelemetry Java agent, including Splunk‑specific extensions and practical examples.

File‑based configuration enables declarative configuration of OpenTelemetry components in Java using a YAML file instead of relying solely on environment variables.

File‑based configuration can be applied both when using SDK autoconfiguration directly and when running applications with the Splunk Distribution of the OpenTelemetry Java agent. The configuration file provides a centralized and version‑controlled way to manage telemetry settings across different environments. For more information about configuring the Java agent, see the official documentation.

File‑based configuration complements environment variable–based configuration but does not fully replace it.

Note: The examples in this section illustrate configuration structure and usage patterns. They do not cover all environment variables or system properties supported by Java instrumentation.

Before you begin

Before using file‑based configuration in Java, ensure that:

  • Your Java environment supports OpenTelemetry SDK autoconfiguration or the Splunk Distribution of the OpenTelemetry Java agent.
  • You can provide a YAML configuration file at application startup.
  • You understand how configuration is resolved during SDK or agent initialization.

Enabling file‑based configuration

To enable file‑based configuration, set the OTEL_EXPERIMENTAL_CONFIG_FILE environment variable to the path of the configuration file
CODE 
OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/sdk-config.yaml

How it is applied

When OTEL_EXPERIMENTAL_CONFIG_FILE is set, the OpenTelemetry SDK autoconfiguration process automatically loads and applies the configuration defined in the YAML file.

Java‑specific behavior

In Java, file‑based configuration is applied during SDK autoconfiguration. The SDK initializes its components based on the contents of the configuration file without requiring language‑specific setup code for each component.

Splunk‑specific configuration

In addition to the standard configuration options supported by the Splunk Distribution of the OpenTelemetry Java agent, you can define Splunk‑specific settings that extend the default behavior of the agent. These settings provide additional capabilities such as continuous profiling, Splunk‑optimized exporters, and enhanced telemetry controls.

To learn more about how the Java agent is instrumented and configured, see the official documentation.

All Splunk‑specific configuration must be defined under a root‑level configuration block named splunk.

Profiling settings

The following example shows how to configure continuous profiling using file‑based configuration. Environment variable equivalents are provided in comments to help illustrate how the YAML structure maps to existing configuration options.

For additional information, see the following documentation:

CODE 
distribution:
  splunk:
    profiling:
      exporter:
        otlp_log_http:
          endpoint: ""                # SPLUNK_PROFILER_LOGS_ENDPOINT

      # always_on, cpu_profiler, memory_profiler, callgraphs may contain language-specific key-value pairs
      always_on:
        cpu_profiler:                 # SPLUNK_PROFILER_ENABLED
          sampling_interval: 10       # SPLUNK_PROFILER_CALL_STACK_INTERVAL
        memory_profiler:              # SPLUNK_PROFILER_MEMORY_ENABLED

      callgraphs:                     # SPLUNK_SNAPSHOT_PROFILER_ENABLED
        sampling_interval: 10         # SPLUNK_SNAPSHOT_SAMPLING_INTERVAL
        selection_probability: 0.01   # SPLUNK_SNAPSHOT_SELECTION_PROBABILITY
Language distributions may specify additional configuration values in locations where it makes the most sense from a convention and usability perspective.

Configuration examples

The following example shows common configuration for traces, metrics, and logs using OTLP/HTTP exporters. The SPLUNK_ACCESS_TOKEN value is resolved using environment variable substitution.
JSON 
tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ""
            headers:
              - name: "X-SF-TOKEN"
                value: ${SPLUNK_ACCESS_TOKEN}

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: ""
            headers:
              - name: "X-SF-TOKEN"
                value: ${SPLUNK_ACCESS_TOKEN}

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ""

Limitations

File‑based configuration does not support every setting that can be configured through environment variables.

Some options must be applied early during application startup or JVM initialization and therefore continue to require environment variables or JVM system properties.