Chaque installation du Collector repose sur un unique document YAML qui suit les mêmes quelques règles. Les apprendre une fois vous permet de lire n’importe quelle configuration de Collector, y compris celles fournies avec les charts Helm et l’Operator. Ce guide couvre la structure, le schéma de nommage, la façon dont les composants sont activés, comment découper et fusionner des fichiers, et comment injecter des variables d’environnement.

Les cinq types de composants

Section	Rôle	Exemples
receivers	Recevoir les données	otlp, prometheus, filelog, hostmetrics
processors	Transformer, filtrer, enrichir, regrouper en lots	batch, memory_limiter, k8s_attributes, tail_sampling
exporters	Envoyer les données vers l’extérieur	otlp, otlphttp, debug, prometheus
connectors	Relier deux pipelines, en agissant comme un exporter dans l’un et un receiver dans l’autre	spanmetrics, forward, routing
extensions	Ajouter des capacités en dehors des pipelines	health_check, zpages, file_storage, extensions d’authentification

Une sixième section, service, les relie entre eux.

Les composants sont désactivés tant que service ne les active pas

C’est la source de confusion la plus fréquente. Configurer un receiver ne l’active pas. Un composant ne prend effet que lorsqu’un pipeline dans service le référence :

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]

Un composant défini mais jamais référencé est ignoré, ce qui est utile pour conserver des variantes dans un fichier, mais facile à oublier lorsque rien n’arrive. Les pipelines se nomment traces, metrics et logs, et un receiver, un processor ou un exporter doit prendre en charge le signal du pipeline qu’il rejoint.

Nommage : type et type/name

L’identifiant d’un composant est son type, éventuellement suivi de /name. Utilisez des noms pour configurer plusieurs fois le même type de composant :

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]   # diffusion vers deux backends

Chaque identifiant doit être unique. La diffusion ci-dessus envoie chaque span aux deux destinations.

Les pipelines en détail

• L’ordre des processors compte. Les données traversent les processors dans l’ordre où ils sont listés. Placez memory_limiter en premier et batch en dernier (voir le guide sur la résilience).
• Un composant peut apparaître dans plusieurs pipelines. Chaque pipeline qui utilise un processor obtient sa propre instance.
• Les connectors font le pont entre pipelines. Un connector est listé comme exporter d’un pipeline et comme receiver d’un autre. Par exemple, spanmetrics transforme des spans en métriques :

connectors:
  spanmetrics:

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

Variables d’environnement

Utilisez ${env:NAME} partout où une valeur est attendue, et des valeurs par défaut de style bash avec :- :

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

Pour écrire un signe dollar littéral, utilisez $$. Comme les secrets arrivent par variable d’environnement, le fichier lui-même en reste exempt et peut être commité.

Sources de configuration et fusion de fichiers

--config accepte un chemin, ou une URI de la forme scheme:value avec les schémas file, env, yaml, http et 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"

Lorsque vous passez plusieurs options --config, le Collector les fusionne en une seule configuration. Chaque fichier peut être partiel, mais le résultat fusionné doit être complet, car le Collector n’ajoute pas de composants à votre place. Utilisez cela pour conserver un fichier de base partagé et un petit fichier de surcharge par environnement.

Vous pouvez aussi intégrer un autre fichier dans une valeur :

exporters: ${file:exporters.yaml}

Les providers http et https chargent la configuration depuis une URL, ce qui est pratique mais signifie que le comportement du Collector dépend de ce serveur ; utilisez-les donc de manière délibérée.

Valider

otelcol validate --config=config.yaml
# ou avec l'image contrib
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 détecte les composants inconnus, les erreurs de syntaxe et les pipelines qui référencent quelque chose que vous n’avez pas défini. Cela ne prouve pas qu’un backend est joignable.

Un comportement par défaut de sécurité à connaître

Les receivers se lient par défaut à localhost. C’est sûr lorsque tous les émetteurs s’exécutent sur le même hôte, mais cela signifie qu’un Collector dans un conteneur est inaccessible de l’extérieur tant que vous n’avez pas défini un endpoint tel que 0.0.0.0:4317. Lorsque vous ouvrez un endpoint au réseau, ajoutez TLS et une authentification (voir le guide sur les backends), et restreignez l’accès par des network policies ou des règles de pare-feu.

Une organisation lisible pour les vrais projets

collector/
├── base.yaml            # receivers, processors, pipelines partagés
├── env/
│   ├── dev.yaml         # exporters et endpoints pour dev
│   └── prod.yaml
└── README.md

Lancez-le avec --config=file:base.yaml --config=file:env/prod.yaml. Les relecteurs voient exactement ce qui change selon l’environnement.

Référence rapide

• Définissez les composants en haut, activez-les dans service.
• Utilisez type/name pour répéter un type de composant.
• Ordonnez les processors délibérément.
• Utilisez ${env:VAR} pour tout ce qui est spécifique à un environnement ou secret.
• Fusionnez plusieurs fichiers --config, et exécutez validate en CI.