GUIDE TECHNIQUE · OPENTELEMETRY
Comment installer et configurer OpenTelemetry Collector avec Docker ?
Créer un pipeline OpenTelemetry Collector local avec un receiver OTLP, un processor batch et un exporter debug. Générer ensuite de vraies traces de test et confirmer leur réception sans exposer de données client.
01 · CADRAGE
Ce que vous allez mettre en place
Créer un pipeline OpenTelemetry Collector local avec un receiver OTLP, un processor batch et un exporter debug. Générer ensuite de vraies traces de test et confirmer leur réception sans exposer de données client.
Pour qui : Équipes d’exploitation, administrateurs systèmes et ingénieurs observabilité
Collector Core ; utiliser une image officielle avec un tag de version validé et les composants de cette distribution.
Vérifiez la compatibilité avec votre environnement réel. Les versions ne sont jamais présumées identiques d’un tenant à l’autre.
02 · AVANT DE COMMENCER
Prérequis et points de contrôle
- Disposer d’un environnement de laboratoire ou de recette autorisé.
- Identifier la version du produit et les droits nécessaires.
- Vérifier les accès réseau, les secrets et la politique de sécurité.
- Connaître la procédure de retour arrière avant toute opération.
03 · VUE D’ENSEMBLE
Comprendre l’architecture et les flux
Illustration du Collector publiée par le projet OpenTelemetry, complétée par notre architecture de laboratoire.
Source : OpenTelemetry04 · TUTORIEL
Procédure complète, étape par étape
Chaque étape explique l’action, sa raison, le contrôle attendu et les erreurs habituelles. Adaptez les exemples aux paramètres de votre propre environnement.
ÉTAPE 1 / 6
Préparer le laboratoire Docker
Il faut une machine de test isolée pour éviter d’exposer un port OTLP sans authentification.
- Créer un dossier otel-lab.
- Vérifier que Docker fonctionne et que les ports 4317/4318 sont libres.
- Prévoir une version épinglée de l’image plutôt que latest.
mkdir -p otel-lab && cd otel-lab
docker --versionÀ vérifier : L’environnement Docker est disponible et prêt.
Point de vigilance ADN : Vérifiez les autorisations avant toute modification de configuration.
ÉTAPE 2 / 6
Écrire collector.yaml
Un receiver ou un exporter déclaré sans pipeline n’est jamais exécuté.
- Créer collector.yaml dans le dossier de travail.
- Définir receiver otlp en gRPC et HTTP.
- Déclarer le processor batch et exporter debug puis les relier dans service.pipelines.traces.
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
batch: {}
exporters:
debug:
verbosity: detailed
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [debug]À vérifier : Les composants du pipeline traces sont tous déclarés et reliés.
Point de vigilance ADN : Une configuration sauvegardée ne signifie pas qu’elle est activée sur le collecteur.
ÉTAPE 3 / 6
Démarrer le Collector
On publie les ports du conteneur uniquement en loopback pour éviter une exposition sur le réseau local.
- Copier la commande Docker ci-dessous dans le terminal.
- Remplacer <VERSION_VALIDEE> par un tag de Collector Core testé, sans chevrons.
- Vérifier les messages de démarrage des receivers.
docker run --rm --name otelcol-lab \
-p 127.0.0.1:4317:4317 -p 127.0.0.1:4318:4318 \
-v "${PWD}/collector.yaml:/etc/otelcol/config.yaml:ro" \
otel/opentelemetry-collector:<VERSION_VALIDEE> \
--config=/etc/otelcol/config.yamlÀ vérifier : Le Collector reste démarré et écoute les ports de laboratoire.
Point de vigilance ADN : Conservez les preuves techniques, mais anonymisez identifiants et secrets.
ÉTAPE 4 / 6
Envoyer cinq traces OTLP
Démarrer un collecteur ne garantit pas que les signaux arrivent.
- Installer un générateur telemetrygen compatible avec la version utilisée.
- Depuis un second terminal, envoyer cinq traces vers localhost:4317 en mode local non chiffré.
- Surveiller les journaux du Collector.
telemetrygen traces --otlp-endpoint localhost:4317 \
--otlp-insecure --traces 5À vérifier : Les spans produits par telemetrygen apparaissent dans la sortie de debug.
Point de vigilance ADN : Vérifiez les autorisations avant toute modification de configuration.
ÉTAPE 5 / 6
Identifier une rupture de pipeline
Les erreurs les plus fréquentes proviennent du protocole et des ports mal appariés.
- Vérifier que 4317 est utilisé pour OTLP gRPC, 4318 pour OTLP HTTP.
- Relire les noms des composants YAML et les options du générateur.
- Inspecter les logs et confirmer la réception de ResourceSpans.
docker logs otelcol-lab --tail 100
# À utiliser lorsque le conteneur fonctionne en mode détaché.À vérifier : Le maillon en erreur est identifié et corrigé.
Point de vigilance ADN : Une configuration sauvegardée ne signifie pas qu’elle est activée sur le collecteur.
ÉTAPE 6 / 6
Préparer une exploitation durable
La configuration de laboratoire n’est pas sécurisée ni dimensionnée pour un environnement d’entreprise.
- Choisir TLS et authentification sur les frontières exposées.
- Évaluer batch, limites mémoire, queues/retry et suppression des attributs sensibles.
- Remplacer debug par une destination d’observabilité réellement compatible et effectuer un test de charge.
À vérifier : Les adaptations nécessaires au passage en production sont documentées.
Point de vigilance ADN : Conservez les preuves techniques, mais anonymisez identifiants et secrets.
05 · RECETTE
Comment vérifier que tout fonctionne ?
La configuration YAML est acceptée par la version choisie.
Les ports ne sont exposés que sur 127.0.0.1.
Le générateur émet des traces et debug confirme la réception.
La configuration de test n’est pas considérée comme adaptée à la production.
06 · DIAGNOSTIC
Problèmes fréquents et résolution
Collector s’arrête
Cause probable : YAML invalide ou composant non disponible
Que faire : Vérifier les noms de composants propres à la distribution et aux versions.
Aucune trace
Cause probable : Endpoint OTLP ou protocole incohérent
Que faire : Comparer gRPC:4317, HTTP:4318 et l’adresse cible.
Port indisponible
Cause probable : Un processus écoute déjà sur le port
Que faire : Identifier le processus ou modifier la redirection Docker.
Erreur de connexion
Cause probable : Client TLS connecté à endpoint de labo non chiffré
Que faire : Réserver --otlp-insecure aux tests locaux ; utiliser TLS en environnement exposé.
Le conseil de l’expert ADN
Avant de généraliser cette configuration, validez-la sur un périmètre représentatif, documentez les critères de réussite et conservez une procédure de retour arrière. Une instrumentation utile se juge sur les données effectivement exploitables, pas sur la seule installation de l’outil.
07 · QUESTIONS PRATIQUES
Questions fréquentes
Le parcours dépend-il de la version ?
Oui : les noms des menus et les composants peuvent varier. Vérifiez la documentation correspondant à votre version.
Faut-il tester avant la production ?
Oui. La procédure doit être reproductible dans un environnement autorisé et représentatif.