OpenTelemetry OpenTelemetry

Exécuter un OpenTelemetry Collector avec Docker Compose

Démarrez un Collector à partir d'un fichier de configuration monté, envoyez-lui des données de test et observez-les dans l'exporter debug.

10 min Débutant

Ce guide exécute un Collector en local à partir d’un fichier YAML, lui envoie une trace et une métrique, et affiche ce qu’il a reçu. Rien n’est configuré dans une interface : le Collector n’en a pas, et tout vit dans un seul fichier. Vous avez besoin de Docker avec le plugin Compose et de curl.

Choisir une image

Le projet publie plusieurs distributions du Collector. L’image core (otel/opentelemetry-collector) contient un petit ensemble de composants. L’image contrib (otel/opentelemetry-collector-contrib) inclut le vaste ensemble communautaire, et l’image orientée Kubernetes (otel/opentelemetry-collector-k8s) inclut ce qui est nécessaire pour surveiller des clusters. De nombreux composants utilisés plus loin dans cette série, comme filelog ou tail_sampling, ne sont pas dans l’image core. Pour apprendre, utilisez contrib. Épinglez une version précise en usage réel, comme dans ces exemples, et remplacez la version par la release de votre choix.

Organisation du projet

otel-demo/
├── compose.yaml
└── otel-collector-config.yaml

La configuration du Collector

otel-collector-config.yaml :

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

Lisez-le de haut en bas :

  • receivers définit comment les données arrivent. otlp écoute gRPC sur 4317 et HTTP sur 4318.
  • processors modifie les données en transit. batch regroupe les éléments pour rendre les exports efficaces.
  • exporters envoie les données vers l’extérieur. debug les affiche dans le log du Collector lui-même, ce qui est ce que vous voulez pendant l’apprentissage.
  • extensions ajoute des capacités en dehors des pipelines. health_check sert un endpoint de santé.
  • service active les éléments. Définir un composant ne fait rien tant qu’il n’est pas listé ici, et chaque signal a son propre pipeline.

Les endpoints utilisent 0.0.0.0 afin que le conteneur soit accessible de l’extérieur. La valeur par défaut du Collector est localhost, plus sûre lorsque tous les émetteurs sont locaux ; ne vous liez donc à 0.0.0.0 que là où c’est nécessaire.

Le fichier compose

compose.yaml :

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.163.0   # épinglez une version que vous avez testée
    command: ["--config=/etc/otelcol/config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol/config.yaml:ro
    ports:
      - "4317:4317"     # OTLP gRPC
      - "4318:4318"     # OTLP HTTP
      - "13133:13133"   # health_check
      - "8888:8888"     # les métriques propres du Collector

Le chemin de configuration /etc/otelcol/config.yaml est l’endroit où les images officielles regardent par défaut. D’autres ports que vous pourriez rencontrer sont 55679 pour l’extension zpages et 8889 pour un exporter Prometheus.

Valider avant de démarrer

Le Collector peut vérifier une configuration sans l’exécuter :

docker run --rm -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml:ro \
  otel/opentelemetry-collector-contrib:0.163.0 validate --config=/etc/otelcol/config.yaml

Une sortie propre signifie que le fichier est analysable et que chaque composant référencé existe dans cette distribution. Exécutez-le aussi en CI. Un échec courant consiste à utiliser un composant qui n’est pas dans l’image choisie.

Le démarrer et vérifier sa santé

docker compose up -d
curl -s http://localhost:13133
docker compose logs otel-collector | tail -n 20

L’endpoint de santé renvoie un petit statut JSON, et le log devrait montrer le Collector démarrant ses pipelines et écoutant sur 4317 et 4318.

Envoyer de la télémétrie de test

Utilisez OTLP via HTTP avec un simple curl. Envoyez un span :

curl -s -X POST http://localhost:4318/v1/traces \
  -H 'Content-Type: application/json' \
  -d '{
    "resourceSpans": [{
      "resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "demo" } }] },
      "scopeSpans": [{
        "spans": [{
          "traceId": "5b8efff798038103d269b633813fc60c",
          "spanId": "eee19b7ec3c1b174",
          "name": "hello",
          "kind": 1,
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000001000000000"
        }]
      }]
    }]
  }'

Un objet JSON vide dans la réponse signifie qu’elle a été acceptée. Regardez maintenant le log du Collector :

docker compose logs otel-collector | grep -A8 'hello'

L’exporter debug affiche le span, sa resource (service.name: demo) et sa durée. Vous avez un pipeline fonctionnel.

Modifier la configuration et recharger

Le Collector lit son fichier au démarrage. Après l’avoir modifié :

docker compose restart otel-collector

Gardez ce dossier dans Git. Les guides suivants remplacent debug par de vrais exporters, et ajoutent des processors et des extensions au même fichier.

Nettoyer

docker compose down

Guides populaires