Les images Collector préconstruites sont pratiques, mais généralistes. La distribution contrib contient des centaines de composants, dont la plupart ne vous serviront jamais, et la distribution core en contient trop peu. Si vous voulez un binaire plus petit, une surface d’attaque réduite ou un composant privé qui vous est propre, vous pouvez construire exactement le Collector dont vous avez besoin avec l’OpenTelemetry Collector Builder (ocb). L’entrée est un simple manifeste YAML, de sorte que tout le processus reste piloté par la configuration.

Quand construire votre propre Collector

• Vous voulez uniquement les composants que vous utilisez, pour une image plus petite et moins de dépendances à corriger.
• Votre politique de sécurité exige de construire à partir des sources et de maîtriser la chaîne d’approvisionnement.
• Vous avez besoin d’un composant absent de toute distribution officielle, par exemple un composant développé en interne.

Si aucun de ces cas ne s’applique, utilisez les distributions officielles. Construire votre propre Collector signifie que vous devrez le reconstruire chaque fois que des composants reçoivent des correctifs de sécurité.

Installer le builder

ocb est un programme Go publié avec chaque version du Collector. Téléchargez le binaire correspondant à votre plateforme depuis la page des releases GitHub du Collector, ou installez-le avec Go :

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

Utilisez la même version pour le builder et pour les composants. (La version indiquée est un exemple ; utilisez une version récente.) La chaîne d’outils Go doit être installée pour lancer une construction. Consultez le guide d’installation de la documentation OpenTelemetry pour connaître le nom exact du binaire et les liens de téléchargement, car ils diffèrent selon les versions.

Écrire le manifeste

# builder-config.yaml
dist:
  name: otelcol-custom
  description: Custom OpenTelemetry Collector
  output_path: ./otelcol-custom
  # Optionnel : la version du Collector core sur laquelle construire
  # 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

Points clés :

• Chaque entrée nomme un module Go et une version (gomod). Les composants contrib se trouvent sous github.com/open-telemetry/opentelemetry-collector-contrib/..., et ceux du core sous go.opentelemetry.io/collector/....
• Les versions des composants doivent être compatibles. Les composants core, les composants contrib et le builder sont publiés ensemble ; gardez-les tous sur la même release. Mélanger les versions provoque des erreurs de compilation.
• Les providers déterminent quelles sources de configuration sont disponibles. Si vous voulez que ${env:VAR} et ${file:/path} fonctionnent, incluez envprovider et fileprovider. Un binaire qui n’en dispose pas ne peut pas résoudre ces références. Les modules de providers ont leurs propres numéros de version (souvent v1.x) ; recherchez-les pour la release sur laquelle vous construisez.
• Les chemins et noms des modules de composants peuvent changer : copiez-les depuis le README de chaque composant ou depuis le manifeste de la distribution contrib plutôt que de mémoire.

Vous pouvez utiliser replaces: pour remplacer un module par un fork local, et les entrées gomod peuvent pointer vers vos dépôts privés.

Construire

ocb --config builder-config.yaml
# ou, si installé avec go install :
builder --config builder-config.yaml

Le répertoire de sortie contient le code source Go généré et un binaire compilé, ./otelcol-custom/otelcol-custom. Exécutez-le avec un fichier de configuration ordinaire et vérifiez ce qu’il inclut :

./otelcol-custom/otelcol-custom components      # liste ce qui a été compilé
./otelcol-custom/otelcol-custom validate --config=config.yaml
./otelcol-custom/otelcol-custom --config=config.yaml

Si votre configuration référence un composant qui n’a pas été intégré, le Collector échoue au démarrage et le nomme. Ajoutez-le au manifeste et reconstruisez.

Packager sous forme d’image de conteneur

Un Dockerfile multi-étapes construit dans une image Go et copie le résultat dans une image de base minimale :

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"]

Utilisez une version de Go qui correspond à l’exigence de la release du Collector (consultez les notes de version), et envisagez d’épingler les images par digest. Construisez et publiez l’image en CI, puis déployez-la comme n’importe quelle image officielle : via le chart Helm (image.repository et image.tag) ou l’Operator (spec.image).

Notez que les presets du chart Helm supposent l’existence de certains composants. Avec une image personnalisée, configurez vous-même les receivers et processors, ou vérifiez que chacun de ceux dont le preset a besoin a bien été inclus.

Rester maintenable

• Gardez builder-config.yaml dans Git et construisez en CI, pas sur des portables.
• Reconstruisez lorsqu’une nouvelle release du Collector sort ou qu’un avis de sécurité touche un composant que vous utilisez. Renovate ou Dependabot peuvent surveiller les chaînes de version.
• Exécutez components et un test de fumée avec une configuration représentative en CI, afin qu’un composant manquant soit détecté avant le déploiement.
• Partez du manifeste contrib et retirez ce que vous n’utilisez pas, plutôt que de construire à partir de zéro.