Ce guide vous permet de collecter les logs et les métriques de votre système Kubernetes, puis de les envoyer vers ClickStack pour les visualiser et les analyser. Pour les données de démonstration, nous pouvons également utiliser le fork ClickStack de l’OpenTelemetry demo officielle.
Prérequis
Pour suivre ce guide, vous devez disposer de :
- D’un cluster Kubernetes (v1.20+ recommandée) avec au moins 32 Gio de RAM et 100 Go d’espace disque disponibles sur un nœud pour ClickHouse.
- Helm v3+
- De
kubectl, configuré pour interagir avec votre cluster
Options de déploiement
Vous pouvez suivre ce guide en utilisant l'une des options de déploiement suivantes :
-
Open Source ClickStack : déployez ClickStack entièrement dans votre cluster Kubernetes, y compris :
- ClickHouse
- HyperDX
- MongoDB (utilisé pour l'état et la configuration des tableaux de bord)
-
Managed ClickStack, avec ClickHouse et la ClickStack UI (HyperDX) gérés dans ClickHouse Cloud. Vous n'avez ainsi pas besoin d'exécuter ClickHouse ou HyperDX dans votre cluster.
Pour simuler le trafic applicatif, vous pouvez, si vous le souhaitez, déployer le fork ClickStack de l'OpenTelemetry Demo Application. Cela génère des données de télémétrie, notamment des logs, des métriques et des traces. Si vous avez déjà des charges de travail en cours d'exécution dans votre cluster, vous pouvez ignorer cette étape et surveiller les pods, nœuds et conteneurs existants.
Installer cert-manager (facultatif)
Si votre installation nécessite des certificats TLS, installez cert-manager à l’aide de Helm :
# Add Cert manager repo
helm repo add jetstack https://charts.jetstack.io
helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set startupapicheck.timeout=5m --set installCRDs=true --set global.leaderElection.namespace=cert-managerDéployer l’OpenTelemetry Demo (facultatif)
Cette étape est facultative et s’adresse aux cas où vous n’avez aucun pod existant à surveiller. Les utilisateurs qui ont déjà des services déployés dans leur environnement Kubernetes peuvent l’ignorer, mais cette démo inclut des microservices instrumentés qui génèrent des données de traces et de session replay, ce qui permet d’explorer toutes les fonctionnalités de ClickStack.
La suite déploie le fork ClickStack de la stack applicative OpenTelemetry Demo dans un cluster Kubernetes, conçu pour les tests d’observabilité et la démonstration de l’instrumentation. Il inclut des microservices backend, des générateurs de charge, des pipelines de télémétrie, l’infrastructure de support (par ex. Kafka, Redis) ainsi que des intégrations SDK avec ClickStack.
Tous les services sont déployés dans l’espace de noms otel-demo. Chaque déploiement inclut :
- Une instrumentation automatique avec OTel et les SDKs ClickStack pour les traces, les métriques et les logs.
- Tous les services envoient leur instrumentation à un collecteur OpenTelemetry
my-hyperdx-hdx-oss-v2-otel-collector(non déployé) - Le transfert des tags de ressource afin de corréler les logs, les métriques et les traces via la variable d’environnement
OTEL_RESOURCE_ATTRIBUTES.
## download demo Kubernetes manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
# wget alternative
# wget https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
kubectl apply --namespace otel-demo -f opentelemetry-demo.yamlLors du déploiement de la démo, vérifiez que tous les pods ont bien été créés et sont à l’état Running :
kubectl get pods -n=otel-demo
NAME READY STATUS RESTARTS AGE
accounting-fd44f4996-fcl4k 1/1 Running 0 13m
ad-769f968468-qq8mw 1/1 Running 0 13m
artillery-loadgen-7bc4bdf47d-5sb96 1/1 Running 0 13m
cart-5b4c98bd8-xm7m2 1/1 Running 0 13m
checkout-784f69b785-cnlpp 1/1 Running 0 13m
currency-fd7775b9c-rf6cr 1/1 Running 0 13m
email-5c54598f99-2td8s 1/1 Running 0 13m
flagd-5466775df7-zjb4x 2/2 Running 0 13m
fraud-detection-5769fdf75f-cjvgh 1/1 Running 0 13m
frontend-6dcb696646-fmcdz 1/1 Running 0 13m
frontend-proxy-7b8f6cd957-s25qj 1/1 Running 0 13m
image-provider-5fdb455756-fs4xv 1/1 Running 0 13m
kafka-7b6666866d-xfzn6 1/1 Running 0 13m
load-generator-57cbb7dfc9-ncxcf 1/1 Running 0 13m
payment-6d96f9bcbd-j8tj6 1/1 Running 0 13m
product-catalog-7fb77f9c78-49bhj 1/1 Running 0 13m
quote-576c557cdf-qn6pr 1/1 Running 0 13m
recommendation-546cc68fdf-8x5mm 1/1 Running 0 13m
shipping-7fc69f7fd7-zxrx6 1/1 Running 0 13m
valkey-cart-5f7b667bb7-gl5v4 1/1 Running 0 13mArchitecture de la démo
La démo se compose de microservices écrits dans différents langages de programmation, qui communiquent entre eux via gRPC et HTTP, ainsi que d’un générateur de charge utilisant Locust pour simuler le trafic des utilisateurs. Le code source original de cette démo a été modifié pour utiliser l’instrumentation ClickStack.

Crédit : https://opentelemetry.io/docs/demo/architecture/
Vous trouverez plus de détails sur cette démonstration dans :
Ajouter le dépôt du chart Helm ClickStack
Pour déployer ClickStack, nous utilisons le chart Helm officiel.
Pour cela, il faut ajouter le dépôt Helm HyperDX :
helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo updateDéployer ClickStack
Une fois le chart Helm installé, vous pouvez déployer ClickStack sur votre cluster. Vous pouvez soit exécuter tous les composants, y compris ClickHouse et HyperDX, dans votre environnement Kubernetes, soit déployer uniquement le collector et vous appuyer sur Managed ClickStack pour ClickHouse et l’interface HyperDX.
ClickStack Open Source (autogéré)
La commande suivante installe ClickStack dans le namespace otel-demo. Le chart Helm déploie :
- Une instance ClickHouse
- HyperDX
- La distribution ClickStack de l’OTel collector
- MongoDB pour stocker l’état de l’application HyperDX
Les utilisateurs qui ne déploient pas la démo OTel peuvent modifier ce paramètre en choisissant un namespace approprié.
helm install my-hyperdx hyperdx/hdx-oss-v2 --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demoManaged ClickStack
Si vous préférez utiliser Managed ClickStack, vous pouvez déployer ClickStack et désactiver le ClickHouse inclus.
# spécifier les identifiants ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # URL https complète
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>
helm install my-hyperdx hyperdx/hdx-oss-v2 --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} --set clickhouse.config.users.otelUserName=${CLICKHOUSE_USER} --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD} --set global.storageClassName="standard-rwo" -n otel-demoPour vérifier l’état du déploiement, exécutez la commande suivante et assurez-vous que tous les composants sont à l’état Running. Notez que ClickHouse sera absent si vous utilisez Managed ClickStack :
kubectl get pods -l "app.kubernetes.io/name=hdx-oss-v2" -n otel-demo
NAME READY STATUS RESTARTS AGE
my-hyperdx-hdx-oss-v2-app-78876d79bb-565tb 1/1 Running 0 14m
my-hyperdx-hdx-oss-v2-clickhouse-57975fcd6-ggnz2 1/1 Running 0 14m
my-hyperdx-hdx-oss-v2-mongodb-984845f96-czb6m 1/1 Running 0 14m
my-hyperdx-hdx-oss-v2-otel-collector-64cf698f5c-8s7qj 1/1 Running 0 14mAccéder à l’interface HyperDX
Pour des raisons de sécurité, le service utilise ClusterIP et n’est pas exposé à l’extérieur par défaut.
Pour accéder à l’interface HyperDX, effectuez une redirection de port de 3000 vers le port local 8080.
kubectl port-forward \
pod/$(kubectl get pod -l app.kubernetes.io/name=hdx-oss-v2 -o jsonpath='{.items[0].metadata.name}' -n otel-demo) \
8080:3000 \
-n otel-demoRendez-vous sur http://localhost:8080 pour accéder à HyperDX UI.
Créez un utilisateur en indiquant un nom d’utilisateur et un mot de passe conformes aux exigences de complexité.

Récupérer la clé API d’ingestion
L’ingestion vers l’OTel collector déployé par le ClickStack collector est sécurisée par une clé d’ingestion.
Accédez à Team Settings et copiez l’Ingestion API Key depuis la section API Keys. Cette clé API garantit la sécurité de l’ingestion des données via l’OpenTelemetry collector.

Créer un secret Kubernetes pour l’API key
Créez un nouveau secret Kubernetes avec l’API key d’ingestion, ainsi qu’une ConfigMap contenant l’adresse de l’OTel collector déployé avec le chart Helm ClickStack. Les composants suivants l’utiliseront pour autoriser l’ingestion vers le collector déployé avec le chart Helm ClickStack :
# create secret with the ingestion API key
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \
-n otel-demo
# create a ConfigMap pointing to the ClickStack OTel collector deployed above
kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=http://my-hyperdx-hdx-oss-v2-otel-collector:4318Redémarrez les pods de l’OpenTelemetry Demo Application afin de prendre en compte la clé API d’ingestion.
kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demoLes données de traces et de logs provenant des services de démonstration devraient désormais commencer à affluer vers HyperDX.

Ajouter le dépôt Helm OpenTelemetry
Pour collecter les métriques Kubernetes, nous allons déployer un OTel collector standard et le configurer pour envoyer les données de manière sécurisée à notre ClickStack collector à l’aide de la clé API d’ingestion ci-dessus.
Cela nécessite d’installer le dépôt Helm OpenTelemetry :
# Add Otel Helm repo
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts Déployer les composants du collector Kubernetes
Pour collecter les logs et les métriques du cluster lui-même et de chaque nœud, nous devrons déployer deux collecteurs OpenTelemetry distincts, chacun avec son propre manifeste. Les deux manifestes fournis — k8s_deployment.yaml et k8s_daemonset.yaml — fonctionnent conjointement pour collecter des données de télémétrie complètes depuis votre cluster Kubernetes.
-
k8s_deployment.yamldéploie une instance unique d’OpenTelemetry Collector chargée de collecter les événements et les métadonnées à l’échelle du cluster. Elle recueille les événements Kubernetes, les métriques du cluster et enrichit les données de télémétrie avec les labels et annotations des pods. Ce collecteur s’exécute comme un déploiement autonome avec une seule réplique pour éviter les doublons de données. -
k8s_daemonset.yamldéploie un collecteur basé sur un DaemonSet qui s’exécute sur chaque nœud de votre cluster. Il collecte les métriques des nœuds et des pods, ainsi que les logs des conteneurs, à l’aide de composants commekubeletstats,hostmetricset les Kubernetes attribute processors. Ces collecteurs enrichissent les logs avec des métadonnées et les envoient à HyperDX via l’exporteur OTLP.
Ensemble, ces manifestes permettent une observabilité full-stack à l'échelle du cluster, de l'infrastructure jusqu'à la télémétrie applicative, et transmettent les données enrichies à ClickStack pour une analyse centralisée.
Commencez par installer le collecteur en tant que déploiement :
# download manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml
# install the helm chart
helm install --namespace otel-demo k8s-otel-deployment open-telemetry/opentelemetry-collector -f k8s_deployment.yamlk8s_deployment.yaml
# k8s_deployment.yaml
mode: deployment
image:
repository: otel/opentelemetry-collector-contrib
tag: 0.123.0
# We only want one of these collectors - any more and we'd produce duplicate data
replicaCount: 1
presets:
kubernetesAttributes:
enabled: true
# When enabled, the processor will extract all labels for an associated pod and add them as resource attributes.
# The label's exact name will be the key.
extractAllPodLabels: true
# When enabled, the processor will extract all annotations for an associated pod and add them as resource attributes.
# The annotation's exact name will be the key.
extractAllPodAnnotations: true
# Configures the collector to collect Kubernetes events.
# Adds the k8sobject receiver to the logs pipeline and collects Kubernetes events by default.
# More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
kubernetesEvents:
enabled: true
# Configures the Kubernetes Cluster Receiver to collect cluster-level metrics.
# Adds the k8s_cluster receiver to the metrics pipeline and adds the necessary rules to ClusteRole.
# More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-cluster-receiver
clusterMetrics:
enabled: true
extraEnvs:
- name: HYPERDX_API_KEY
valueFrom:
secretKeyRef:
name: hyperdx-secret
key: HYPERDX_API_KEY
optional: true
- name: YOUR_OTEL_COLLECTOR_ENDPOINT
valueFrom:
configMapKeyRef:
name: otel-config-vars
key: YOUR_OTEL_COLLECTOR_ENDPOINT
config:
exporters:
otlphttp:
endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
compression: gzip
headers:
authorization: "${env:HYPERDX_API_KEY}"
service:
pipelines:
logs:
exporters:
- otlphttp
metrics:
exporters:
- otlphttpEnsuite, déployez le collecteur en tant que DaemonSet pour les métriques et les logs au niveau des nœuds et des pods :
# download manifest file
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml
# install the helm chart
helm install --namespace otel-demo k8s-otel-daemonset open-telemetry/opentelemetry-collector -f k8s_daemonset.yamlk8s_daemonset.yaml
# k8s_daemonset.yaml
mode: daemonset
image:
repository: otel/opentelemetry-collector-contrib
tag: 0.123.0
# Required to use the kubeletstats cpu/memory utilization metrics
clusterRole:
create: true
rules:
- apiGroups:
- ''
resources:
- nodes/proxy
verbs:
- get
presets:
logsCollection:
enabled: true
hostMetrics:
enabled: true
# Configures the Kubernetes Processor to add Kubernetes metadata.
# Adds the k8sattributes processor to all the pipelines and adds the necessary rules to ClusterRole.
# More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
kubernetesAttributes:
enabled: true
# When enabled, the processor will extract all labels for an associated pod and add them as resource attributes.
# The label's exact name will be the key.
extractAllPodLabels: true
# When enabled, the processor will extract all annotations for an associated pod and add them as resource attributes.
# The annotation's exact name will be the key.
extractAllPodAnnotations: true
# Configures the collector to collect node, pod, and container metrics from the API server on a kubelet..
# Adds the kubeletstats receiver to the metrics pipeline and adds the necessary rules to ClusterRole.
# More Info: https://opentelemetry.io/docs/kubernetes/collector/components/#kubeletstats-receiver
kubeletMetrics:
enabled: true
extraEnvs:
- name: HYPERDX_API_KEY
valueFrom:
secretKeyRef:
name: hyperdx-secret
key: HYPERDX_API_KEY
optional: true
- name: YOUR_OTEL_COLLECTOR_ENDPOINT
valueFrom:
configMapKeyRef:
name: otel-config-vars
key: YOUR_OTEL_COLLECTOR_ENDPOINT
config:
receivers:
# Configures additional kubelet metrics
kubeletstats:
collection_interval: 20s
auth_type: 'serviceAccount'
endpoint: '${env:K8S_NODE_NAME}:10250'
insecure_skip_verify: true
metrics:
k8s.pod.cpu_limit_utilization:
enabled: true
k8s.pod.cpu_request_utilization:
enabled: true
k8s.pod.memory_limit_utilization:
enabled: true
k8s.pod.memory_request_utilization:
enabled: true
k8s.pod.uptime:
enabled: true
k8s.node.uptime:
enabled: true
k8s.container.cpu_limit_utilization:
enabled: true
k8s.container.cpu_request_utilization:
enabled: true
k8s.container.memory_limit_utilization:
enabled: true
k8s.container.memory_request_utilization:
enabled: true
container.uptime:
enabled: true
exporters:
otlphttp:
endpoint: "${env:YOUR_OTEL_COLLECTOR_ENDPOINT}"
compression: gzip
headers:
authorization: "${env:HYPERDX_API_KEY}"
service:
pipelines:
logs:
exporters:
- otlphttp
metrics:
exporters:
- otlphttpExplorer les données Kubernetes dans HyperDX
Accédez à votre interface HyperDX, soit en utilisant votre instance déployée dans Kubernetes, soit via Managed ClickStack.
Managed ClickStack
Si vous utilisez Managed ClickStack, connectez-vous simplement à votre service ClickHouse Cloud et sélectionnez "ClickStack" dans le menu de gauche. Vous serez automatiquement authentifié et n'aurez pas besoin de créer d'utilisateur.
Les sources de données pour les logs, les métriques et les traces seront créées à l'avance pour vous.
ClickStack Open Source
Pour accéder à l'instance HyperDX déployée localement, vous pouvez effectuer une redirection de port à l'aide de la commande suivante, puis accéder à HyperDX à l'adresse http://localhost:8080.
kubectl port-forward \
pod/$(kubectl get pod -l app.kubernetes.io/name=hdx-oss-v2 -o jsonpath='{.items[0].metadata.name}' -n otel-demo) \
8080:3000 \
-n otel-demoPour explorer les données Kubernetes, accédez au tableau de bord dédié disponible à l'adresse /kubernetes, par exemple http://localhost:8080/kubernetes.
Chacun des onglets — Pods, Nodes et Namespaces — doit contenir des données.
