RousselTMLEARNING

Artículo · ClickStack: del descubrimiento a la maestría

Enviar la telemetría a ClickStack

Este artículo está disponible en francés.

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 →

Mi seguimiento

  • ⏱ Duración estimada : ≈ 11 min

Inicia sesión para seguir tu progreso y tomar notas. Iniciar sesión

💬 Preguntas sobre esta lección

Todavía no hay preguntas: sé el primero en pedir ayuda o compartir tu configuración.

Hacer una pregunta sobre esta lección →

Artículos recomendados

Envoyer ses logs, métriques et traces vers OpenObserve

Les points de réception d'OpenObserve : JSON, bulk, OTLP avec le Collector OpenTelemetry, Prometh...

Envoyer des traces vers Tempo : instrumentation OpenTelemetry et Alloy

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

Les logs avec OpenTelemetry : modèle de données, appenders, corrélation et collecte

Maîtriser le signal log : modèle de données LogRecord, Logs Bridge API et appenders (Logback, Log...

OpenTelemetry Collector : les Exporters (envoyer la télémétrie vers les backends)

Configurer les exporters du Collector OpenTelemetry : OTLP gRPC/HTTP, Prometheus, prometheusremot...

Ingerir logs OpenTelemetry en Elasticsearch

Recoger y estructurar logs con el Collector OpenTelemetry (receiver filelog, operadores, procesad...

Trazas OpenTelemetry en Elasticsearch y Kibana APM

Instrumentar aplicaciones con los SDK de OpenTelemetry o EDOT, enviar las trazas a Elasticsearch,...

Instrumenter ses applications pour Jaeger avec OpenTelemetry

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

OpenTelemetry et Dynatrace : OTLP, collecteur et instrumentation

Intégrer OpenTelemetry à Dynatrace : endpoint OTLP et jetons, Dynatrace OTel Collector, traces, m...

OTLP expliqué : comprendre le protocole OpenTelemetry

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

Apoyar

♥ APOYAR

Apoya RousselTM Learning

Los cursos, artículos, prácticas y certificados siguen siendo gratuitos y sin publicidad intrusiva. Una contribución libre, por el importe que elijas, financia el alojamiento, los entornos de prácticas y nuevos contenidos.

Contribuir con PayPal Importe libre · tarjeta o cuenta PayPalMás información
QR code PayPal
O escanea este código QR con tu teléfono

¡Gracias, cada contribución cuenta!