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.jarCes 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 colonneServiceName, 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
TraceIdetSpanId, 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 internesKubernetes #
- Un collecteur en DaemonSet lit les logs des pods (
/var/log/pods) et collecte les métriques des nœuds (kubeletstats) ; le processeurk8sattributesajoute 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-mailLes 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_limiteret, en cas de pics, une file persistante (extensionfile_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 collecteurOTEL_EXPORTER_OTLP_HEADERS=authorization=<clé>: clé d'ingestioncurl -s localhost:8888/metrics | grep otelcol_exporter_sent: événements envoyés par le collecteurcurl -s localhost:8888/metrics | grep send_failed: envois en échecSELECT 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.
Mon suivi
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.
Articles recommandés
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...
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...
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...
OpenTelemetry Collector : les Exporters (envoyer la télémétrie vers les backends)
Configurer les exporters du Collector OpenTelemetry : OTLP gRPC/HTTP, Prometheus, prometheusremot...
Envoyer ses logs, métriques et traces vers OpenObserve
Les points de réception d'OpenObserve : JSON, bulk, OTLP avec le Collector OpenTelemetry, Prometh...
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...