Toda configuración del Collector es un único documento YAML que sigue las mismas pocas reglas. Aprender esas reglas una vez te permite leer cualquier configuración del Collector, incluidas las que se distribuyen con los charts de Helm y el Operator. Esta guía cubre la estructura, el esquema de nombres, cómo se activan los componentes, cómo dividir y fusionar archivos y cómo inyectar variables de entorno.

Los cinco tipos de componente

Sección	Trabajo	Ejemplos
receivers	Recibir datos	otlp, prometheus, filelog, hostmetrics
processors	Transformar, filtrar, enriquecer, agrupar	batch, memory_limiter, k8s_attributes, tail_sampling
exporters	Enviar datos hacia fuera	otlp, otlphttp, debug, prometheus
connectors	Unir dos pipelines, actuando como exporter en uno y como receiver en otro	spanmetrics, forward, routing
extensions	Añadir capacidades junto a los pipelines	health_check, zpages, file_storage, extensiones de autenticación

Una sexta sección, service, los conecta entre sí.

Los componentes están apagados hasta que service los habilita

Esta es la fuente de confusión más común. Configurar un receiver no lo activa. Un componente solo surte efecto cuando un pipeline de service lo referencia:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  debug:
  otlp_grpc:
    endpoint: gateway.example.com:4317

service:
  extensions: [health_check, zpages]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_grpc]
    metrics:
      receivers: [otlp]
      exporters: [otlp_grpc]
    logs:
      receivers: [otlp]
      exporters: [otlp_grpc]

Un componente que está definido pero nunca se referencia se ignora, lo que es útil para mantener variantes en un archivo pero fácil de olvidar cuando no llega nada. Los pipelines se llaman traces, metrics y logs, y un receiver, processor o exporter debe soportar la señal del pipeline al que se une.

Nombres: type y type/name

El identificador de un componente es su tipo, opcionalmente seguido de /nombre. Usa nombres para configurar el mismo tipo de componente más de una vez:

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true
  otlp/vendor:
    endpoint: otlp.vendor.example.com:4317

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/tempo, otlp/vendor]   # distribuye a dos backends

Cada identificador debe ser único. La distribución de arriba envía cada span a ambos destinos.

Pipelines en detalle

• El orden de los processors importa. Los datos pasan por los processors en el orden en que se listan. Pon memory_limiter primero y batch al final (consulta la guía de resiliencia).
• Un componente puede aparecer en varios pipelines. Cada pipeline que usa un processor obtiene su propia instancia.
• Los connectors tienden puentes entre pipelines. Un connector se lista como exporter de un pipeline y receiver de otro. Por ejemplo, spanmetrics convierte spans en métricas:

connectors:
  spanmetrics:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/tempo, spanmetrics]
    metrics:
      receivers: [otlp, spanmetrics]
      processors: [batch]
      exporters: [otlphttp/prometheus]

Variables de entorno

Usa ${env:NOMBRE} en cualquier lugar donde se espere un valor, y valores predeterminados al estilo bash con :-:

exporters:
  otlp:
    endpoint: ${env:OTLP_ENDPOINT:-gateway.example.com:4317}
    headers:
      authorization: Bearer ${env:API_TOKEN}

Para escribir un signo de dólar literal, usa $$. Como los secretos llegan por variable de entorno, el archivo en sí se mantiene libre de ellos y puede subirse a Git.

Fuentes de configuración y fusión de archivos

--config acepta una ruta, o una URI esquema:valor con los esquemas file, env, yaml, http y https:

otelcol --config=file:/etc/otelcol/base.yaml --config=file:/etc/otelcol/overrides.yaml
otelcol --config=env:MY_CONFIG_IN_AN_ENVVAR
otelcol --config="yaml:exporters::debug::verbosity: normal"

Cuando pasas varias opciones --config, el Collector las fusiona en una sola configuración. Cada archivo puede ser parcial, pero el resultado fusionado debe estar completo, porque el Collector no añade componentes por ti. Usa esto para mantener un archivo base compartido y una pequeña sobrescritura por entorno.

También puedes incrustar otro archivo en un valor:

exporters: ${file:exporters.yaml}

Los providers http y https cargan la configuración desde una URL, lo que es cómodo pero significa que el comportamiento del Collector depende de ese servidor, así que úsalos de forma deliberada.

Valida

otelcol validate --config=config.yaml
# o con la imagen contrib
docker run --rm -v $(pwd)/config.yaml:/etc/otelcol/config.yaml:ro \
  otel/opentelemetry-collector-contrib:0.163.0 validate --config=/etc/otelcol/config.yaml

validate detecta componentes desconocidos, sintaxis incorrecta y pipelines que referencian algo que no definiste. No demuestra que un backend sea accesible.

Valor predeterminado de seguridad que conviene conocer

Los receivers se enlazan a localhost por defecto. Eso es seguro cuando todos los emisores se ejecutan en el mismo host, pero significa que un Collector en un contenedor es inaccesible desde fuera hasta que defines un endpoint como 0.0.0.0:4317. Cuando abras un endpoint a la red, añade TLS y autenticación (consulta la guía de backends), y restringe el acceso con una network policy o reglas de firewall.

Una estructura legible para proyectos reales

collector/
├── base.yaml            # receivers, processors, pipelines compartidos
├── env/
│   ├── dev.yaml         # exporters y endpoints para dev
│   └── prod.yaml
└── README.md

Ejecútalo con --config=file:base.yaml --config=file:env/prod.yaml. Los revisores pueden ver exactamente qué cambia por entorno.

Referencia rápida

• Define los componentes arriba, habilítalos en service.
• Usa type/name para repetir un tipo de componente.
• Ordena los processors de forma deliberada.
• Usa ${env:VAR} para todo lo específico de un entorno o secreto.
• Fusiona varios archivos --config y ejecuta validate en CI.