Die vorgefertigten Collector-Images sind bequem, aber breit. Die Contrib-Distribution enthält Hunderte von Komponenten, von denen du die meisten nie nutzen wirst, und die Core-Distribution hat zu wenige. Wenn du ein kleineres Binary, eine reduzierte Angriffsfläche oder eine eigene, private Komponente willst, kannst du genau den Collector bauen, den du brauchst, mit dem OpenTelemetry Collector Builder (ocb). Die Eingabe ist ein einzelnes YAML-Manifest, sodass der gesamte Prozess konfigurationsgesteuert bleibt.

Wann du einen eigenen baust

• Du willst nur die Komponenten, die du nutzt, für ein kleineres Image und weniger zu patchende Abhängigkeiten.
• Die Sicherheitsrichtlinie verlangt, dass du aus dem Quellcode baust und die Lieferkette kontrollierst.
• Du brauchst eine Komponente, die in keiner offiziellen Distribution enthalten ist, etwa eine selbst geschriebene.

Trifft nichts davon zu, nutze die offiziellen Distributionen. Einen eigenen zu bauen bedeutet, dass du für das erneute Bauen verantwortlich bist, wenn Komponenten Sicherheitskorrekturen erhalten.

Den Builder installieren

ocb ist ein Go-Programm, das mit jeder Collector-Version veröffentlicht wird. Lade das Binary für deine Plattform von der GitHub-Releases-Seite des Collectors herunter oder installiere es mit Go:

go install go.opentelemetry.io/collector/cmd/builder@v0.163.0

Nutze dieselbe Version für den Builder und die Komponenten. (Die gezeigte Version ist ein Beispiel; nutze ein aktuelles Release.) Die Go-Toolchain muss installiert sein, um einen Build auszuführen. Prüfe die Installationsanleitung in der OpenTelemetry-Dokumentation auf den genauen Binary-Namen und die Download-Links, da sie sich je nach Release unterscheiden.

Das Manifest schreiben

# builder-config.yaml
dist:
  name: otelcol-custom
  description: Custom OpenTelemetry Collector
  output_path: ./otelcol-custom
  # Optional: die Version des Core-Collectors, gegen die gebaut wird
  # otelcol_version: 0.163.0

receivers:
  - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.163.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/filelogreceiver v0.163.0

processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.163.0
  - gomod: go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.163.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/k8sattributesprocessor v0.163.0

exporters:
  - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.163.0
  - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.163.0
  - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.163.0

extensions:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.163.0

providers:
  - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.0.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.0.0

Kernpunkte:

• Jeder Eintrag benennt ein Go-Modul und eine Version (gomod). Contrib-Komponenten liegen unter github.com/open-telemetry/opentelemetry-collector-contrib/... und Core-Komponenten unter go.opentelemetry.io/collector/....
• Komponenten-Versionen müssen kompatibel sein. Core-Komponenten, Contrib-Komponenten und der Builder werden gemeinsam veröffentlicht; halte alle auf demselben Release. Gemischte Versionen verursachen Compile-Fehler.
• Provider bestimmen, welche Konfigurationsquellen verfügbar sind. Willst du, dass ${env:VAR} und ${file:/path} funktionieren, nimm envprovider und fileprovider auf. Ein Binary ohne sie kann diese Referenzen nicht auflösen. Provider-Module haben eigene Versionsnummern (oft v1.x), schlage sie also für das Release nach, gegen das du baust.
• Modulpfade und -namen von Komponenten können sich ändern, kopiere sie also aus der README der jeweiligen Komponente oder dem eigenen Manifest der Contrib-Distribution statt aus dem Gedächtnis.

Du kannst replaces: nutzen, um ein Modul durch einen lokalen Fork zu ersetzen, und gomod-Einträge können auf deine privaten Repositories zeigen.

Bauen

ocb --config builder-config.yaml
# oder, wenn mit go install installiert:
builder --config builder-config.yaml

Das Ausgabeverzeichnis enthält generierten Go-Quellcode und ein kompiliertes Binary, ./otelcol-custom/otelcol-custom. Führe es mit einer gewöhnlichen Konfigurationsdatei aus und prüfe, was enthalten ist:

./otelcol-custom/otelcol-custom components      # auflisten, was einkompiliert wurde
./otelcol-custom/otelcol-custom validate --config=config.yaml
./otelcol-custom/otelcol-custom --config=config.yaml

Referenziert deine Konfiguration eine Komponente, die nicht eingebaut wurde, schlägt der Collector beim Start fehl und nennt sie. Füge sie dem Manifest hinzu und baue neu.

Als Container-Image paketieren

Ein mehrstufiges Dockerfile baut in einem Go-Image und kopiert das Ergebnis in eine minimale Basis:

FROM golang:1.24 AS build
WORKDIR /src
RUN go install go.opentelemetry.io/collector/cmd/builder@v0.163.0
COPY builder-config.yaml .
RUN CGO_ENABLED=0 builder --config builder-config.yaml

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /src/otelcol-custom/otelcol-custom /otelcol-custom
USER nonroot
ENTRYPOINT ["/otelcol-custom"]
CMD ["--config=/etc/otelcol/config.yaml"]

Nutze eine Go-Version, die der Anforderung des Collector-Releases entspricht (prüfe die Release Notes), und erwäge, Images per Digest zu pinnen. Baue und veröffentliche das Image in CI und deploye es genauso wie jedes offizielle Image: über das Helm-Chart (image.repository und image.tag) oder den Operator (spec.image).

Beachte, dass die Presets des Helm-Charts voraussetzen, dass bestimmte Komponenten existieren. Konfiguriere bei einem eigenen Image die Receiver und Prozessoren selbst oder bestätige, dass jeder, den ein Preset braucht, enthalten war.

Wartbar halten

• Halte builder-config.yaml in Git und baue in CI, nicht auf Laptops.
• Baue neu, wenn ein neues Collector-Release erscheint oder ein Sicherheitshinweis eine von dir genutzte Komponente betrifft. Renovate oder Dependabot können die Versionsstrings beobachten.
• Führe in CI components und einen Smoke-Test mit einer repräsentativen Konfiguration aus, damit eine fehlende Komponente vor dem Deployment auffällt.
• Beginne mit dem Contrib-Manifest und entferne, was du nicht nutzt, statt von null aufzubauen.