Las variables de entorno funcionan bien para un puñado de ajustes, pero se vuelven difíciles de manejar cuando necesitas varios exporters, processors personalizados o reglas de muestreo. La configuración declarativa las reemplaza con un único archivo YAML que describe todo el SDK: el resource, los propagadores y los providers de tracer, meter y logger. El esquema alcanzó una versión estable en 2026, lo que significa que es seguro diseñar en torno a él. El soporte en cada SDK sigue siendo desigual, así que lee la sección de estado antes de adoptarlo.

Actívala

Guarda un archivo y apunta el SDK a él con una variable de entorno:

export OTEL_CONFIG_FILE=/etc/otel/otel-config.yaml

Cuando OTEL_CONFIG_FILE está definida, un SDK que soporta la configuración declarativa se construye a sí mismo a partir del archivo. Las demás variables OTEL_* se ignoran entonces a menos que el archivo las referencie, como se describe más abajo.

Un ejemplo completo

otel-config.yaml:

file_format: "1.2"

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
  detection/development:
    detectors:
      - service:
      - host:
      - process:
      - container:

propagator:
  composite:
    - tracecontext:
    - baggage:

tracer_provider:
  sampler:
    parent_based:
      root:
        always_on:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/traces

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/metrics

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/logs

Usa el valor de file_format que especifique la documentación de tu SDK, ya que los SDK adoptan las nuevas versiones del esquema en momentos distintos. Cómo leer el archivo:

• resource describe el servicio. attributes_list toma la cadena habitual clave=valor,clave=valor, y los detectors añaden automáticamente información de host, proceso y contenedor. Las propiedades que terminan en /development todavía son experimentales y pueden no existir en todos los SDK.
• propagator lista los propagadores de contexto, aquí el trace context de W3C y baggage.
• tracer_provider contiene el sampler y los span processors. Aquí un batch processor envía spans mediante un exporter OTLP HTTP.
• meter_provider contiene los metric readers. Un reader periodic exporta según un intervalo.
• logger_provider hace lo mismo para los logs.
• otlp_http vs otlp_grpc: cambia el nombre del exporter y el endpoint (http://localhost:4317 para gRPC) para cambiar de protocolo.

Sustitución de variables de entorno

Dentro del archivo, ${VAR} lee una variable de entorno y ${VAR:-default} aporta un valor predeterminado cuando no está definida. Por lo demás, las variables de entorno se ignoran, que es el punto: nada cambia de comportamiento a menos que el archivo lo pida. Eso facilita ver qué es configurable por entorno:

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}

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

El mismo archivo funciona entonces en desarrollo (valores predeterminados) y en producción (la plataforma define las variables).

Destinos por señal y configuraciones más ricas

La configuración declarativa brilla en cosas que las variables de entorno no expresan bien, como enviar los mismos spans a dos lugares o ajustar un processor:

tracer_provider:
  processors:
    - batch:
        schedule_delay: 2000
        max_queue_size: 4096
        exporter:
          otlp_http:
            endpoint: http://collector:4318/v1/traces
    - simple:
        exporter:
          console:

Aquí los spans van a un Collector en lotes y también se imprimen en la consola, lo que es útil para depuración local. Consulta la documentación de tu SDK para los nombres exactos de propiedades que soporta, porque los processors, samplers y exporters disponibles dependen de la implementación.

Qué lenguajes la soportan

La especificación y el esquema son estables, pero cada lenguaje los implementa a su propio ritmo:

• Disponible: C++, Go, Java, JavaScript y PHP tienen implementaciones, y el agente de Java documenta su propia configuración.
• En desarrollo: .NET y Python.
• La documentación todavía describe el soporte entre implementaciones como experimental, así que trata la función como algo que hay que probar para tu lenguaje antes de depender de ella.
• El propio Collector usa la implementación de Go para configurar su telemetría interna.

Si tu lenguaje aún no está listo, sigue usando variables de entorno. Los dos modelos son intencionadamente compatibles: los nombres de variable mostrados en los ejemplos de sustitución son los mismos que usarías sin un archivo.

Cómo elegir entre ambos

Usa variables de entorno cuando	Usa un archivo declarativo cuando
Defines unas pocas opciones por servicio	Necesitas varios exporters o processors
Tu plataforma ya inyecta el entorno (Operator, Helm)	Quieres toda la configuración del SDK revisada en un solo archivo
El soporte declarativo de tu lenguaje falta o es inmaduro	Quieres el mismo formato de configuración en varios lenguajes

Un híbrido razonable es montar un archivo compartido desde un ConfigMap y dejar que las variables de entorno aporten solo los valores por entorno mediante sustitución ${...}.

Entrega el archivo

Docker Compose:

services:
  checkout:
    image: myorg/checkout:1.4.2
    environment:
      OTEL_CONFIG_FILE: /etc/otel/otel-config.yaml
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_RESOURCE_ATTRIBUTES: service.version=1.4.2,deployment.environment.name=staging
    volumes:
      - ./otel-config.yaml:/etc/otel/otel-config.yaml:ro

Kubernetes: pon el archivo en un ConfigMap, móntalo y define OTEL_CONFIG_FILE en el Deployment. Un cambio en el ConfigMap en Git se despliega como cualquier otro cambio, pero los SDK leen el archivo al arrancar, así que reinicia los pods para recogerlo.

Trampas

• Un error en el archivo puede impedir que el SDK inicie sus providers. Pruébalo en un entorno de preproducción, y observa la salida de log del SDK al arrancar (OTEL_LOG_LEVEL=debug temporalmente).
• No pongas secretos directamente en el archivo. Usa ${VAR} e inyecta el valor desde un Secret.
• La reconfiguración dinámica en tiempo de ejecución todavía no forma parte de esta especificación. Cambiar el archivo requiere un reinicio.
• Algunas variables de entorno individuales están previstas para deprecación porque no interoperan bien, aunque deprecada no significa eliminada.

Para el esquema completo y las notas por lenguaje, consulta la documentación de configuración declarativa.