RousselTMLEARNING

Article · ClickStack : de la découverte à l'expertise

Envoyer la télémétrie à ClickStack

1. Les points d'entrée et la clé d'ingestion #

Tout passe par OTLP.

Principe #

Disponible dans : ✓ Open source ✓ Managed ClickStack

ClickStack reçoit toute la télémétrie par son collecteur OpenTelemetry : OTLP HTTP sur 4318 ou gRPC sur 4317. Chaque envoi doit porter la clé d'ingestion, visible dans l'interface (Team Settings › API Keys), dans l'en-tête authorization.

Attention : La clé d'ingestion permet d'écrire dans votre base : stockez-la comme un secret, et n'exposez pas les ports OTLP sur Internet sans TLS ni filtrage (sauf pour le SDK navigateur, derrière un point d'entrée dédié).

2. Instrumenter les applications #

Les SDK et agents OpenTelemetry.

Variables standard #

export OTEL_EXPORTER_OTLP_ENDPOINT=http://clickstack:4318
export OTEL_EXPORTER_OTLP_HEADERS="authorization=$CLICKSTACK_INGESTION_KEY"   # Team Settings › API Keys
export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=2.4.1
# Exemple Java : agent OpenTelemetry, aucune modification du code
java -javaagent:opentelemetry-javaagent.jar -jar checkout.jar

Ces variables valent pour tous les langages (Java, .NET, Node.js, Python, Go…). ClickStack fournit aussi des SDK qui enveloppent OpenTelemetry et acceptent la clé dans leur fonction d'initialisation.

Attributs à soigner #

  • service.name : la colonne ServiceName, filtre principal de l'interface.
  • deployment.environment.name, service.version : séparer production et recette, repérer une régression.
  • Logs émis par le SDK OpenTelemetry (ou corrélés) : ils portent TraceId et SpanId, ce qui permet de passer d'une trace à ses logs.

3. Relayer par un collecteur #

Logs de fichiers, enrichissement, tampon.

Configuration #

Un collecteur placé près des applications (agent sur l'hôte ou DaemonSet Kubernetes) lit les fichiers de logs, enrichit les données et les relaie vers ClickStack avec la clé d'ingestion.

# Collecteur existant (contrib) qui relaie vers ClickStack : logs de fichiers et OTLP des applications
receivers:
  otlp:
    protocols: { grpc: { endpoint: 0.0.0.0:4317 }, http: { endpoint: 0.0.0.0:4318 } }
  filelog:
    include: [/var/log/nginx/*.log]
    operators:
      - type: regex_parser
        regex: '^(?P<client>\S+) \S+ \S+ \[(?P<time>[^\]]+)\] "(?P<method>\S+) (?P<path>\S+) \S+" (?P<status>\d{3})'
processors:
  batch: { send_batch_size: 10000, timeout: 5s }
  memory_limiter: { check_interval: 1s, limit_percentage: 80, spike_limit_percentage: 20 }
  resourcedetection: { detectors: [env, system] }
exporters:
  otlphttp/clickstack:
    endpoint: http://clickstack:4318
    headers: { authorization: ${env:CLICKSTACK_INGESTION_KEY} }
    compression: gzip
service:
  pipelines:
    logs:   { receivers: [otlp, filelog], processors: [memory_limiter, resourcedetection, batch], exporters: [otlphttp/clickstack] }
    traces: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlphttp/clickstack] }
    metrics: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlphttp/clickstack] }
  telemetry:
    metrics: { address: 0.0.0.0:9888 }    # deux collecteurs sur un même hôte : changer le port des métriques internes

Kubernetes #

  • Un collecteur en DaemonSet lit les logs des pods (/var/log/pods) et collecte les métriques des nœuds (kubeletstats) ; le processeur k8sattributes ajoute espace de noms, pod et déploiement.
  • Un collecteur en Deployment collecte les métriques du cluster (k8s_cluster) et les événements, une seule fois pour tout le cluster.
  • Le chart Helm officiel du Collector OpenTelemetry fournit ces deux modes (préréglages kubernetesAttributes, logsCollection, kubeletMetrics).

4. Sessions navigateur #

Le rejeu relié aux traces.

Le SDK navigateur #

// npm install @hyperdx/browser : sessions, erreurs et traces côté navigateur
import HyperDX from '@hyperdx/browser';

HyperDX.init({
  url: 'https://otel.exemple.fr',                 // point d'entrée OTLP HTTP du collecteur (exposé en HTTPS)
  apiKey: '<clé-d-ingestion>',
  service: 'boutique-web',
  tracePropagationTargets: [/api\.exemple\.fr/i],  // propage traceparent vers le back-end
  consoleCapture: true,
  advancedNetworkCapture: false,                 // n'activez la capture des corps de requêtes qu'en connaissance de cause
});
HyperDX.setGlobalAttributes({ userId: 'u-1842' }); // identifiant opaque, jamais d'e-mail

Les sessions sont stockées dans la table hyperdx_sessions. Dans l'interface, une erreur de back-end mène à la trace, puis à la session navigateur qui l'a déclenchée, avec son rejeu.

Bonne Pratique : Le rejeu masque les champs de saisie par défaut ; vérifiez qu'aucune donnée personnelle n'apparaît dans les pages rejouées et recueillez le consentement si nécessaire.

5. Schéma, débit et sécurité #

Les réglages qui comptent.

Map ou JSON ? #

Par défaut, les attributs sont stockés dans des colonnes Map(LowCardinality(String), String) (LogAttributes, SpanAttributes, ResourceAttributes) : c'est le choix recommandé. Un schéma utilisant le type JSON de ClickHouse existe en bêta (activation par un drapeau du collecteur, clickhouse.json) : à réserver à des essais avec un ensemble d'attributs réduit et stable.

Débit #

  • ClickHouse préfère peu d'insertions de gros lots : gardez le processeur batch (des milliers d'événements, quelques secondes).
  • Ajoutez memory_limiter et, en cas de pics, une file persistante (extension file_storage) pour ne rien perdre pendant une indisponibilité.
  • Filtrez à la source ce qui n'a pas de valeur (sondes de santé, logs de debug) : chaque ligne stockée coûte du disque.

Commandes à connaître #

Commandes à connaître
  • OTEL_EXPORTER_OTLP_ENDPOINT=http://clickstack:4318 : adresse du collecteur
  • OTEL_EXPORTER_OTLP_HEADERS=authorization=<clé> : clé d'ingestion
  • curl -s localhost:8888/metrics | grep otelcol_exporter_sent : événements envoyés par le collecteur
  • curl -s localhost:8888/metrics | grep send_failed : envois en échec
  • SELECT ServiceName, count() FROM otel_logs WHERE Timestamp > now() - INTERVAL 5 MINUTE GROUP BY ServiceName : vérifier l'arrivée des logs

Sources #

Vérifié en novembre 2026 : ClickStack évolue vite (Managed ClickStack est en bêta), consultez la documentation de ClickHouse avant de vous appuyer sur un détail.

📄 Envoyer la télémétrie à ClickStack : SDK OpenTelemetry, collecteurs, logs, Kubernetes et sessions navigateur →

Mon suivi

  • ⏱ Durée estimée : ≈ 11 min

Connectez-vous pour suivre votre progression et prendre des notes. Se connecter

💬 Questions sur cette leçon

Aucune question pour l'instant : soyez le premier à demander de l'aide ou à partager votre configuration.

Poser une question sur cette leçon →

Articles recommandés

Installer et déployer ClickStack : tout-en-un, Docker Compose, Helm et Managed ClickStack

Déployer ClickStack selon le besoin : conteneur tout-en-un avec persistance, Docker Compose et se...

Envoyer des traces vers Tempo : instrumentation OpenTelemetry et Alloy

Produire et acheminer des traces vers Tempo : auto-instrumentation Python/Java/Node, SDK manuel, ...

Grafana Alloy : Collecte et Transformation de Télémétrie

Apprenez à utiliser Grafana Alloy pour collecter, transformer et acheminer logs, métriques et tra...

Exploiter ClickHouse pour ClickStack : dimensionnement, réplication, surveillance, sécurité et sauvegarde

Faire tourner ClickHouse en production pour l'observabilité : estimer le volume et le disque, rép...

Ingérer des logs OpenTelemetry dans Elasticsearch

Collecter et structurer des logs avec le Collector OpenTelemetry (receiver filelog, opérateurs, p...

OpenTelemetry Collector, Grafana Alloy et Bindplane : comparer trois approches des pipelines de télémétrie

Comparatif détaillé de trois façons de gérer des pipelines de télémétrie : l'OpenTelemetry Collec...

Collecter des logs vers Loki : Alloy, Promtail, Docker et OpenTelemetry

Envoyer des logs vers Loki : Grafana Alloy, Promtail, driver Docker, OTLP, bons labels, parsing e...

OTLP expliqué : comprendre le protocole OpenTelemetry

Découvrez le protocole OTLP expliqué simplement. Comprendre les différences entre gRPC et HTTP po...

Instrumenter ses applications pour Jaeger avec OpenTelemetry

Envoyer des traces à Jaeger avec OpenTelemetry : auto-instrumentation (Java, Python, Node.js), SD...

Soutenir

♥ SOUTENIR

Soutenez RousselTM Learning

Les formations, articles, TP et attestations restent gratuits et sans publicité intrusive. Une contribution libre, du montant de votre choix, finance l’hébergement, les environnements de TP et l’écriture de nouveaux contenus.

Contribuer avec PayPal Montant libre · carte bancaire ou compte PayPalEn savoir plus
QR code PayPal
Ou scannez ce QR code avec votre téléphone

Merci, chaque contribution compte !