1. Choisir un mode de déploiement #
Du poste de développement à la production.
Les options #
Disponible dans : ✓ Open source ✓ ClickHouse Cloud ClickHouse Observability et option self-managed
| Mode | Pour | Limite |
|---|---|---|
| Tout-en-un | découvrir, démontrer, développer | un seul conteneur : ni mise à l'échelle, ni isolation ; données perdues sans volumes |
| Docker Compose | petite équipe, recette, mono-serveur | pas de haute disponibilité |
| Helm | production sur Kubernetes | ClickHouse à exploiter (ou externe) |
| ClickHouse Observability | ne rien exploiter : endpoint OTLP, base et interface managés | bêta publique (novembre 2026) ; données dans ClickHouse Cloud |
2. Le conteneur tout-en-un #
ClickHouse, interface, collecteur et MongoDB ensemble.
Avec persistance #
mkdir -p .volumes/db .volumes/ch_data .volumes/ch_logs
docker run -d --name clickstack --restart unless-stopped \
-p 8080:8080 -p 4317:4317 -p 4318:4318 \
-v "$(pwd)/.volumes/db:/data/db" \
-v "$(pwd)/.volumes/ch_data:/var/lib/clickhouse" \
-v "$(pwd)/.volumes/ch_logs:/var/log/clickhouse-server" \
clickhouse/clickstack-all-in-one:latest
# http://localhost:8080 : créer le premier compte (les sources de la base intégrée sont créées à ce moment)| Volume | Contenu |
|---|---|
/data/db | MongoDB : comptes, dashboards, alertes |
/var/lib/clickhouse | données ClickHouse (la télémétrie) |
/var/log/clickhouse-server | journaux de ClickHouse |
Attention : Sans volumes, tout est perdu à la suppression du conteneur. Même avec, ce mode ne convient pas à la production : tous les processus partagent les mêmes ressources et ne peuvent être ni dimensionnés ni surveillés séparément.
Changer les ports #
Seul le côté hôte change : -p 4999:4318 publie l'OTLP HTTP sur le port 4999. Changer les ports de l'interface (8080) ou de l'API (8000) demande aussi d'ajuster les variables correspondantes.
3. Docker Compose #
Un conteneur par composant.
Démarrer #
git clone https://github.com/ClickHouse/ClickStack.git && cd ClickStack
cat .env | grep -E 'IMAGE|PORT|VERSION' # versions des images, ports de l'interface, de l'API et d'OpAMP
docker compose up -d
docker compose ps # app (interface + API), otel-collector, clickhouse, db (MongoDB)Variables utiles (.env) #
| Variable | Rôle |
|---|---|
IMAGE_VERSION, CODE_VERSION | version des images (fixez-la plutôt que latest) |
HYPERDX_APP_PORT | port de l'interface (8080) |
HYPERDX_API_PORT | port de l'API (8000) |
HYPERDX_OPAMP_PORT | port OpAMP de pilotage du collecteur (4320) |
HYPERDX_APP_URL | adresse publique de l'interface (liens dans les alertes) |
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE | base ClickHouse des tables de télémétrie |
Utiliser ClickHouse Cloud #
Retirez le service ClickHouse du Compose (et ses depends_on), puis donnez au collecteur l'adresse HTTPS (port 8443) et les identifiants du service. Créez ensuite la connexion dans l'interface (Team Settings) et les sources.
# Collecteur ClickStack vers un service ClickHouse Cloud (au lieu de la base locale)
otel-collector:
image: clickhouse/clickstack-otel-collector:2
environment:
CLICKHOUSE_ENDPOINT: 'https://<service>.<région>.aws.clickhouse.cloud:8443'
CLICKHOUSE_USER: 'otel_writer'
CLICKHOUSE_PASSWORD: '${CH_PASSWORD}'
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: 'default'
OPAMP_SERVER_URL: 'http://app:4320'
ports: ['4317:4317', '4318:4318', '13133:13133']4. Kubernetes avec Helm #
Le chart clickstack (v2).
Scénarios #
| Scénario | Réglages |
|---|---|
| Pile complète | valeurs par défaut : ClickHouse (géré par opérateur), collecteur, interface |
| ClickHouse externe | clickhouse.enabled: false et connexion par hyperdx.defaultConnections ou un Secret existant |
| Collecteur externe | otel-collector.enabled: false et hyperdx.otelExporterEndpoint |
| Interface seule | ClickHouse et collecteur désactivés, connexion vers l'existant |
# Ajouter le dépôt Helm de ClickStack (URL indiquée dans la documentation « Helm »), puis :
helm install my-clickstack clickstack/clickstack -n observability --create-namespace -f values.yaml
# values.yaml : ClickHouse externe (par exemple ClickHouse Cloud), collecteur fourni par le chart
clickhouse:
enabled: false # ne pas déployer la base intégrée (gérée par opérateur)
hyperdx:
defaultConnections: | # connexion de l'interface à votre ClickHouse (ou un Secret existant)
[{ "name": "prod", "host": "https://<service>:8443", "username": "hyperdx", "password": "…" }]
otel-collector:
enabled: trueÀ savoir : Le chart v1 (modèles intégrés) est en maintenance : la documentation fournit un guide de passage à la v2. Placez les mots de passe dans un Secret (hyperdx.useExistingConfigSecret) plutôt que dansvalues.yaml.
5. ClickHouse Cloud et production #
Choisir et vérifier.
ClickHouse Observability #
Dans ClickHouse Cloud, deux possibilités. ClickHouse Observability (tout managé, bêta publique) fournit un endpoint OTLP managé : vos SDK et agents pointent dessus, et ClickHouse gère schémas, mise à l'échelle et interface. L'option self-managed (l'ancien Managed ClickStack) active l'interface sur votre service : vous déployez votre collecteur OpenTelemetry et réglez vous-même base et schémas. BYOC (la base dans votre compte cloud, opérée par ClickHouse) et ClickHouse Private (votre infrastructure, jusqu'aux environnements isolés) complètent l'offre.
Liste de contrôle de production #
- ClickHouse répliqué (au moins deux répliques et ClickHouse Keeper) ou ClickHouse Cloud ; disques rapides, stockage objet pour les données froides.
- Collecteurs dimensionnés pour l'ingestion, plusieurs instances derrière un répartiteur, et une file tampon si nécessaire.
- MongoDB sauvegardée (dashboards et alertes) ; TLS sur l'interface et sur les points d'entrée OTLP exposés.
- Rétention (TTL) définie par table et surveillance de ClickHouse lui-même (voir la leçon d'exploitation).
- Versions d'images fixées et montées de version testées en recette.
Commandes à connaître #
Commandes à connaître
docker run … clickhouse/clickstack-all-in-one:latest: tout-en-undocker compose up -d: pile séparéehelm install my-clickstack clickstack/clickstack -f values.yaml: déploiement Kubernetescurl -s http://localhost:13133: santé du collecteurdocker logs clickstack | tail: journaux du conteneur tout-en-un
Sources #
Vérifié en novembre 2026 : ClickStack évolue vite (ClickHouse Observability est en bêta publique), consultez la documentation de ClickHouse avant de vous appuyer sur un détail.
6. Démarrer avec ClickHouse Observability #
Le mode tout managé.
Les étapes #
- Créez un service ClickHouse Cloud (l'essai gratuit fournit des crédits) et ouvrez ClickHouse Observability depuis le menu du service.
- Récupérez l'adresse de l'endpoint OTLP managé et sa clé, puis pointez-y vos SDK et agents (variables
OTEL_EXPORTER_OTLP_ENDPOINTetOTEL_EXPORTER_OTLP_HEADERS). - Pour des logs déjà présents dans Kafka ou S3, créez un ClickPipe plutôt qu'un collecteur supplémentaire.
- Réglez l'interface : heures en UTC (préférences utilisateur), sources reliées entre elles (logs, traces, métriques, sessions) pour activer la corrélation.
- Pour migrer depuis Datadog, un récepteur Datadog permet de garder les agents existants le temps de la transition.
Bonne Pratique : Pour s'entraîner sans rien instrumenter, le workshop public de ClickHouse (TP de ce chapitre « Explorer ») génère en SQL un mois de télémétrie réaliste dans votre propre service.
