Diese Anleitung betreibt einen Collector lokal aus einer YAML-Datei, sendet ihm einen Trace und eine Metrik und gibt aus, was er empfangen hat. Nichts wird in einer UI konfiguriert: Der Collector hat keine, und alles lebt in einer Datei. Du brauchst Docker mit dem Compose-Plugin und curl.

Ein Image wählen

Das Projekt veröffentlicht mehrere Collector-Distributionen. Das Core-Image (otel/opentelemetry-collector) hat eine kleine Menge Komponenten. Das Contrib-Image (otel/opentelemetry-collector-contrib) enthält die große Community-Menge, und das Kubernetes-fokussierte Image (otel/opentelemetry-collector-k8s) enthält, was zur Überwachung von Clustern gebraucht wird. Viele Komponenten, die später in dieser Reihe genutzt werden, etwa filelog oder tail_sampling, sind nicht im Core-Image. Zum Lernen nutze Contrib. Pinne im echten Einsatz eine bestimmte Version, wie in diesen Beispielen, und ersetze die Version durch das gewünschte Release.

Projektaufbau

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

Die Collector-Konfiguration

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]

Lies es von oben nach unten:

• receivers definieren, wie Daten hereinkommen. otlp lauscht auf gRPC auf 4317 und HTTP auf 4318.
• processors ändern Daten im Flug. batch gruppiert Einträge, um Exporte effizient zu machen.
• exporters senden Daten hinaus. debug gibt sie im eigenen Log des Collectors aus, was du beim Lernen willst.
• extensions fügen Fähigkeiten neben den Pipelines hinzu. health_check stellt einen Health-Endpunkt bereit.
• service schaltet Dinge ein. Eine Komponente zu definieren bewirkt nichts, bis sie hier aufgeführt ist, und jedes Signal hat seine eigene Pipeline.

Die Endpunkte nutzen 0.0.0.0, damit der Container von außen erreichbar ist. Der Standard des Collectors ist localhost, was sicherer ist, wenn alle Sender lokal sind, binde also nur dort an 0.0.0.0, wo du es brauchst.

Die Compose-Datei

compose.yaml:

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.163.0   # pinne eine Version, die du getestet hast
    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"     # die eigenen Metriken des Collectors

Der Konfigurationspfad /etc/otelcol/config.yaml ist der, an dem die offiziellen Images standardmäßig suchen. Andere Ports, denen du begegnen kannst, sind 55679 für die Extension zpages und 8889 für einen Prometheus-Exporter.

Vor dem Start validieren

Der Collector kann eine Konfiguration prüfen, ohne sie auszuführen:

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

Ein sauberes Ende bedeutet, dass die Datei geparst wird und jede referenzierte Komponente in dieser Distribution existiert. Führe das auch in CI aus. Ein häufiger Fehler ist, eine Komponente zu nutzen, die nicht im gewählten Image ist.

Starten und Health prüfen

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

Der Health-Endpunkt gibt einen kleinen JSON-Status zurück, und das Log sollte zeigen, wie der Collector seine Pipelines startet und auf 4317 und 4318 lauscht.

Testtelemetrie senden

Nutze OTLP über HTTP mit einfachem curl. Sende einen 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"
        }]
      }]
    }]
  }'

Ein leeres JSON-Objekt in der Antwort bedeutet, dass er akzeptiert wurde. Sieh dir nun das Log des Collectors an:

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

Der debug-Exporter gibt den Span, seine Resource (service.name: demo) und sein Timing aus. Du hast eine funktionierende Pipeline.

Die Konfiguration ändern und neu laden

Der Collector liest seine Datei beim Start. Nach dem Bearbeiten:

docker compose restart otel-collector

Halte diesen Ordner in Git. Spätere Anleitungen ersetzen debug durch echte Exporter und fügen derselben Datei Prozessoren und Extensions hinzu.

Aufräumen

docker compose down