Jedes Collector-Setup ist ein YAML-Dokument, das denselben wenigen Regeln folgt. Diese Regeln einmal zu lernen lässt dich jede Collector-Konfiguration lesen, einschließlich der, die mit Helm-Charts und dem Operator ausgeliefert werden. Diese Anleitung behandelt die Struktur, das Benennungsschema, wie Komponenten eingeschaltet werden, wie du Dateien aufteilst und zusammenführst und wie du Umgebungsvariablen einspeist.

Die fünf Komponententypen

Abschnitt	Aufgabe	Beispiele
receivers	Daten entgegennehmen	otlp, prometheus, filelog, hostmetrics
processors	Transformieren, filtern, anreichern, bündeln	batch, memory_limiter, k8s_attributes, tail_sampling
exporters	Daten ausgeben	otlp, otlphttp, debug, prometheus
connectors	Zwei Pipelines verbinden, in einer als Exporter, in der anderen als Receiver	spanmetrics, forward, routing
extensions	Fähigkeiten neben den Pipelines hinzufügen	health_check, zpages, file_storage, Auth-Extensions

Ein sechster Abschnitt, service, verdrahtet sie miteinander.

Komponenten sind aus, bis service sie aktiviert

Das ist die häufigste Quelle von Verwirrung. Einen Receiver zu konfigurieren schaltet ihn nicht ein. Eine Komponente wirkt erst, wenn eine Pipeline in service sie referenziert:

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]

Eine Komponente, die definiert, aber nie referenziert wird, wird ignoriert, was nützlich ist, um Varianten in einer Datei zu halten, aber leicht zu vergessen, wenn nichts ankommt. Die Pipelines heißen traces, metrics und logs, und ein Receiver, Prozessor oder Exporter muss das Signal der Pipeline unterstützen, der er beitritt.

Benennung: type und type/name

Ein Komponenten-Bezeichner ist sein Typ, optional gefolgt von /name. Nutze Namen, um denselben Komponententyp mehrfach zu konfigurieren:

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]   # Fan-out an zwei Backends

Jeder Bezeichner muss eindeutig sein. Der obige Fan-out sendet jeden Span an beide Ziele.

Pipelines im Detail

• Die Reihenfolge der Prozessoren zählt. Daten durchlaufen Prozessoren in der aufgelisteten Reihenfolge. Setze memory_limiter zuerst und batch zuletzt (siehe die Resilienz-Anleitung).
• Eine Komponente kann in mehreren Pipelines auftauchen. Jede Pipeline, die einen Prozessor nutzt, bekommt ihre eigene Instanz.
• Connectors überbrücken Pipelines. Ein Connector wird als Exporter einer Pipeline und Receiver einer anderen aufgeführt. Zum Beispiel macht spanmetrics aus Spans Metriken:

connectors:
  spanmetrics:

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

Umgebungsvariablen

Nutze ${env:NAME} überall dort, wo ein Wert erwartet wird, und Bash-artige Standardwerte mit :-:

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

Um ein literales Dollarzeichen zu schreiben, nutze $$. Weil Secrets per Umgebungsvariable ankommen, bleibt die Datei selbst frei davon und kann committet werden.

Konfigurationsquellen und Zusammenführen von Dateien

--config akzeptiert einen Pfad oder eine URI scheme:value mit den Schemata file, env, yaml, http und 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"

Wenn du mehrere --config-Optionen übergibst, führt der Collector sie zu einer Konfiguration zusammen. Jede Datei darf unvollständig sein, aber das zusammengeführte Ergebnis muss vollständig sein, weil der Collector keine Komponenten für dich ergänzt. Nutze das, um eine gemeinsame Basisdatei und einen kleinen Override pro Umgebung zu halten.

Du kannst auch eine andere Datei in einen Wert einbetten:

exporters: ${file:exporters.yaml}

Die Provider http und https laden Konfiguration von einer URL, was bequem ist, aber bedeutet, dass das Verhalten des Collectors von diesem Server abhängt, nutze sie also bewusst.

Validieren

otelcol validate --config=config.yaml
# oder mit dem Contrib-Image
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 fängt unbekannte Komponenten, falsche Syntax und Pipelines ab, die etwas referenzieren, das du nicht definiert hast. Es beweist nicht, dass ein Backend erreichbar ist.

Sicherheits-Standard, den du kennen solltest

Receiver binden standardmäßig an localhost. Das ist sicher, wenn alle Sender auf demselben Host laufen, bedeutet aber, dass ein Collector in einem Container von außen unerreichbar ist, bis du einen Endpunkt wie 0.0.0.0:4317 setzt. Wenn du einen Endpunkt zum Netzwerk öffnest, füge TLS und Authentifizierung hinzu (siehe die Backends-Anleitung) und beschränke den Zugriff mit Network Policy oder Firewall-Regeln.

Ein lesbares Layout für echte Projekte

collector/
├── base.yaml            # Receiver, Prozessoren, gemeinsame Pipelines
├── env/
│   ├── dev.yaml         # Exporter und Endpunkte für Dev
│   └── prod.yaml
└── README.md

Betreibe es mit --config=file:base.yaml --config=file:env/prod.yaml. Reviewer sehen genau, was sich pro Umgebung ändert.

Kurzreferenz

• Definiere Komponenten oben, aktiviere sie in service.
• Nutze type/name, um einen Komponententyp zu wiederholen.
• Ordne Prozessoren bewusst.
• Nutze ${env:VAR} für alles Umgebungsspezifische oder Geheime.
• Führe mehrere --config-Dateien zusammen und führe validate in CI aus.