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

ClickStack : architecture, composants et offres (ClickHouse, HyperDX, OpenTelemetry)

ClickStack, la pile d'observabilité officielle de ClickHouse : rôle de ClickHouse, de l'interface...

Explorer avec l'interface ClickStack : sources, recherche, traces, sessions et SQL

Utiliser l'interface ClickStack (HyperDX) : sources de données, syntaxe de recherche par propriét...

La télémétrie dans ClickHouse : schéma, SQL, vues matérialisées et rétention

La télémétrie dans ClickHouse : tables otel_logs, otel_traces, otel_metrics_* et hyperdx_sessions...

Bonnes pratiques SigNoz, ClickStack et ClickHouse pour l'observabilité

Bonnes pratiques pour l'observabilité sur ClickHouse avec SigNoz ou ClickStack : instrumentation ...

L'observabilité sur ClickHouse : pourquoi une base colonne change la donne

Pourquoi de plus en plus de plateformes d'observabilité stockent logs, traces et métriques dans C...

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...

Alertes et dashboards dans ClickStack

Construire des graphiques et des dashboards dans ClickStack, créer des alertes sur une recherche ...

Exploiter une plateforme d'observabilité sur ClickHouse et choisir son outil

Exploiter ClickHouse pour la télémétrie (réplication, disques, fusions, stockage objet, supervisi...

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...

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!