Esta guía ejecuta un Collector en local desde un archivo YAML, le envía una traza y una métrica e imprime lo que recibió. Nada se configura en una interfaz: el Collector no tiene ninguna, y todo vive en un solo archivo. Necesitas Docker con el plugin Compose y curl.

Elige una imagen

El proyecto publica varias distribuciones del Collector. La imagen core (otel/opentelemetry-collector) tiene un conjunto pequeño de componentes. La imagen contrib (otel/opentelemetry-collector-contrib) incluye el gran conjunto de la comunidad, y la imagen orientada a Kubernetes (otel/opentelemetry-collector-k8s) incluye lo necesario para monitorizar clústeres. Muchos componentes usados más adelante en esta serie, como filelog o tail_sampling, no están en la imagen core. Para aprender, usa contrib. Fija una versión concreta en el uso real, como en estos ejemplos, y reemplaza la versión por la release que quieras.

Estructura del proyecto

otel-demo/
├── compose.yaml
└── otel-collector-config.yaml

La configuración del Collector

otel-collector-config.yaml:

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

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

Léelo de arriba abajo:

• receivers define cómo entran los datos. otlp escucha gRPC en el 4317 y HTTP en el 4318.
• processors cambian los datos en tránsito. batch agrupa elementos para que las exportaciones sean eficientes.
• exporters envían los datos hacia fuera. debug los imprime en el propio log del Collector, que es lo que quieres mientras aprendes.
• extensions añaden capacidades junto a los pipelines. health_check sirve un endpoint de salud.
• service lo activa todo. Definir un componente no hace nada hasta que se lista aquí, y cada señal tiene su propio pipeline.

Los endpoints usan 0.0.0.0 para que el contenedor sea accesible desde fuera. El valor predeterminado del Collector es localhost, que es más seguro cuando todos los emisores son locales, así que enlaza a 0.0.0.0 solo donde lo necesites.

El archivo compose

compose.yaml:

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.163.0   # fija una versión que hayas probado
    command: ["--config=/etc/otelcol/config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol/config.yaml:ro
    ports:
      - "4317:4317"     # OTLP gRPC
      - "4318:4318"     # OTLP HTTP
      - "13133:13133"   # health_check
      - "8888:8888"     # las propias métricas del Collector

La ruta de configuración /etc/otelcol/config.yaml es donde las imágenes oficiales buscan por defecto. Otros puertos que puedes encontrar son el 55679 para la extensión zpages y el 8889 para un exporter de Prometheus.

Valida antes de iniciar

El Collector puede comprobar una configuración sin ejecutarla:

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

Una salida limpia significa que el archivo se analiza y que cada componente referenciado existe en esta distribución. Ejecuta esto también en CI. Un fallo común es usar un componente que no está en la imagen que elegiste.

Arráncalo y comprueba la salud

docker compose up -d
curl -s http://localhost:13133
docker compose logs otel-collector | tail -n 20

El endpoint de salud devuelve un pequeño estado JSON, y el log debería mostrar al Collector iniciando sus pipelines y escuchando en el 4317 y el 4318.

Envía telemetría de prueba

Usa OTLP sobre HTTP con curl simple. Envía un span:

curl -s -X POST http://localhost:4318/v1/traces \
  -H 'Content-Type: application/json' \
  -d '{
    "resourceSpans": [{
      "resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "demo" } }] },
      "scopeSpans": [{
        "spans": [{
          "traceId": "5b8efff798038103d269b633813fc60c",
          "spanId": "eee19b7ec3c1b174",
          "name": "hello",
          "kind": 1,
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000001000000000"
        }]
      }]
    }]
  }'

Un objeto JSON vacío en la respuesta significa que se aceptó. Ahora mira el log del Collector:

docker compose logs otel-collector | grep -A8 'hello'

El exporter debug imprime el span, su resource (service.name: demo) y su duración. Ya tienes un pipeline funcionando.

Cambia la configuración y recárgala

El Collector lee su archivo al arrancar. Tras editarlo:

docker compose restart otel-collector

Mantén esta carpeta en Git. Las guías posteriores reemplazan debug por exporters reales, y añaden processors y extensions al mismo archivo.

Limpia

docker compose down