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.
