Los SDK de OpenTelemetry comparten un conjunto común de variables de entorno, así que la misma configuración funciona para Java, Python, Node.js, .NET y otros. Es la forma más común de configurar una aplicación, y encaja perfectamente con contenedores y Kubernetes, ya que la plataforma define el entorno. Esta guía cubre las variables que más usarás.

Cada SDK de lenguaje implementa la especificación a su propio ritmo, así que verifica las variables menos comunes en la documentación de tu lenguaje.

Lo esencial

export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=staging
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

• OTEL_SERVICE_NAME define service.name, el atributo más importante, porque los backends agrupan todo por él. Si no se define, obtienes un nombre unknown_service. Tiene precedencia sobre service.name dentro de OTEL_RESOURCE_ATTRIBUTES.
• OTEL_RESOURCE_ATTRIBUTES es una lista separada por comas de pares clave=valor que describen el servicio, como su versión y entorno.
• OTEL_EXPORTER_OTLP_ENDPOINT es adónde va la telemetría. Apúntalo a un Collector.
• OTEL_EXPORTER_OTLP_PROTOCOL es grpc, http/protobuf o http/json.

Endpoints y protocolos: el puerto debe coincidir

Los valores predeterminados son http://localhost:4318 para HTTP y http://localhost:4317 para gRPC. Para los protocolos HTTP, el SDK añade v1/traces, v1/metrics y v1/logs al endpoint base. Si defines un endpoint por señal, como OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, se usa exactamente como se da, sin añadir nada.

El error más común es una discrepancia: enviar gRPC al puerto 4318 o HTTP al 4317. Elige el protocolo y el puerto juntos. El protocolo predeterminado de la especificación es http/protobuf, pero algunos SDK usan gRPC por defecto, así que defínelo explícitamente.

Selección de exporter

export OTEL_TRACES_EXPORTER=otlp      # predeterminado
export OTEL_METRICS_EXPORTER=otlp     # predeterminado
export OTEL_LOGS_EXPORTER=otlp        # predeterminado

Los valores incluyen otlp, console (imprimir en la terminal, útil para depurar) y none para desactivar una señal. Algunos lenguajes soportan otros, como prometheus para métricas o zipkin para trazas.

Opciones del exporter OTLP

export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer abc123,x-tenant=team-a"
export OTEL_EXPORTER_OTLP_TIMEOUT=10000       # milisegundos en la mayoría de SDK
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/ssl/ca.pem
export OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE=/etc/ssl/client.pem
export OTEL_EXPORTER_OTLP_CLIENT_KEY=/etc/ssl/client.key

Cada una de estas tiene variantes por señal, como OTEL_EXPORTER_OTLP_TRACES_TIMEOUT u OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, que tienen precedencia sobre la variable base. HEADERS es una lista separada por comas de pares clave=valor, y todos los valores son cadenas. Usa un endpoint https:// para TLS, y las variables de certificado para autoridades certificadoras privadas o TLS mutuo.

Propagación y muestreo

export OTEL_PROPAGATORS=tracecontext,baggage    # predeterminado
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

• OTEL_PROPAGATORS decide qué encabezados transportan el contexto de la traza entre servicios. El valor predeterminado es tracecontext,baggage (W3C). Todos los servicios de una ruta de petición deben usar propagadores compatibles, o las trazas se rompen en la frontera. Añade b3 u otros solo cuando debas interoperar con sistemas más antiguos.
• OTEL_TRACES_SAMPLER es por defecto parentbased_always_on, que registra todo y sigue la decisión del llamante. Para head sampling, parentbased_traceidratio con OTEL_TRACES_SAMPLER_ARG=0.1 conserva aproximadamente el diez por ciento de las trazas nuevas respetando la decisión de un padre. La guía de muestreo cubre cuándo muestrear en el Collector en su lugar.

Batching y límites

Los ajustes de batch controlan el uso de memoria y la frecuencia de exportación. Valores predeterminados de la especificación:

Variable	Valor predeterminado
OTEL_BSP_SCHEDULE_DELAY	5000 ms
OTEL_BSP_MAX_QUEUE_SIZE	2048
OTEL_BSP_MAX_EXPORT_BATCH_SIZE	512
OTEL_BSP_EXPORT_TIMEOUT	30000 ms
OTEL_BLRP_SCHEDULE_DELAY	1000 ms
OTEL_METRIC_EXPORT_INTERVAL	60000 ms
OTEL_ATTRIBUTE_COUNT_LIMIT	128
OTEL_SPAN_EVENT_COUNT_LIMIT	128

BSP es el span batch processor y BLRP es el log record batch processor. Aumenta el tamaño de la cola si ves spans descartados bajo carga, y reduce el intervalo de métricas durante las pruebas (por ejemplo 10000) para no esperar un minuto por un punto de datos.

Interruptores operativos

export OTEL_SDK_DISABLED=true     # desactiva la telemetría sin quitar la instrumentación
export OTEL_LOG_LEVEL=debug       # el nivel de log de diagnóstico del propio SDK (por defecto info)

OTEL_SDK_DISABLED es un interruptor de emergencia rápido. El logging de depuración es muy verboso, así que no lo dejes activado en producción.

Ponerlo en Docker Compose y Kubernetes

Compose:

services:
  checkout:
    image: myorg/checkout:1.4.2
    environment:
      OTEL_SERVICE_NAME: checkout
      OTEL_RESOURCE_ATTRIBUTES: service.version=1.4.2,deployment.environment.name=staging
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
      OTEL_TRACES_SAMPLER: parentbased_traceidratio
      OTEL_TRACES_SAMPLER_ARG: "0.25"

Kubernetes:

env:
  - name: OTEL_SERVICE_NAME
    value: checkout
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://otel-collector.observability.svc.cluster.local:4318
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: k8s.pod.name=$(POD_NAME),deployment.environment.name=staging
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name

La guía del Operator muestra cómo inyectarlas automáticamente, con un recurso Instrumentation, para que los equipos de aplicación no las definan a mano.

Orden de precedencia y trampas

• La configuración en código suele ganar a las variables de entorno, y las variables por señal ganan a las generales.
• Una variable que tu SDK no reconoce se ignora en silencio. Comprueba la página de configuración del lenguaje cuando un ajuste parezca no hacer nada.
• No pongas secretos en OTEL_RESOURCE_ATTRIBUTES. Se convierte en una etiqueta de cada pieza de telemetría.
• Cuando un endpoint contiene una ruta (por ejemplo detrás de un proxy), usa las variables de endpoint por señal para que no se añada nada.
• Mantén la lista de variables en un solo lugar por servicio (un archivo Compose o un archivo de valores de Helm), para que los cambios se revisen.

Para la lista completa, consulta la especificación de variables de entorno del SDK y la configuración del exporter OTLP.