Esta guía le permite recopilar logs y métricas de su sistema Kubernetes y enviarlos a ClickStack para su visualización y análisis. Para los datos de demostración, usamos opcionalmente el fork de ClickStack de la demo oficial de OpenTelemetry.
Requisitos previos
Para seguir esta guía, necesitas tener:
- Un clúster de Kubernetes (se recomienda v1.20+) con al menos 32 GiB de RAM y 100 GB de espacio en disco disponibles en un nodo para ClickHouse.
- Helm v3+
kubectl, configurado para interactuar con tu clúster
Opciones de implementación
Puedes seguir esta guía con cualquiera de las siguientes opciones de implementación:
-
Open Source ClickStack: implementa ClickStack por completo dentro de tu clúster de Kubernetes, lo que incluye:
- ClickHouse
- HyperDX
- MongoDB (utilizado para el estado y la configuración del dashboard)
-
Managed ClickStack, con ClickHouse y la UI de ClickStack (HyperDX) gestionados en ClickHouse Cloud. Esto elimina la necesidad de ejecutar ClickHouse o HyperDX dentro de tu clúster.
Para simular tráfico de la aplicación, opcionalmente puedes implementar el fork de ClickStack de la OpenTelemetry Demo Application. Esto genera datos de telemetría, incluidos logs, métricas y trazas. Si ya tienes workloads en ejecución en tu clúster, puedes omitir este paso y supervisar los pods, nodos y contenedores existentes.
Instalar cert-manager (opcional)
Si su implementación requiere certificados TLS, instale cert-manager con 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-managerDespliega OpenTelemetry Demo (opcional)
Este paso es opcional y está pensado para cuando no tienes pods que supervisar. Aunque los usuarios que ya tienen servicios desplegados en su entorno de Kubernetes pueden omitirlo, esta demo sí incluye microservicios instrumentados que generan datos de trazas y session replay, lo que permite explorar todas las funcionalidades de ClickStack.
A continuación se despliega el fork de ClickStack de la pila de aplicaciones OpenTelemetry Demo en un clúster de Kubernetes, adaptado para pruebas de observabilidad y para mostrar la instrumentación. Incluye microservicios de backend, generadores de carga, pipelines de telemetría, infraestructura de soporte (p. ej., Kafka, Redis) e integraciones de SDK con ClickStack.
Todos los servicios se despliegan en el espacio de nombres otel-demo. Cada implementación incluye:
- Instrumentación automática con OTel y ClickStack SDKS para trazas, métricas y logs.
- Todos los servicios envían su instrumentación a un colector de OpenTelemetry
my-hyperdx-hdx-oss-v2-otel-collector(no desplegado) - Reenvío de etiquetas de recurso para correlacionar logs, métricas y trazas mediante la variable de entorno
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.yamlTras desplegar la demo, confirme que todos los pods se hayan creado correctamente y estén en estado 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 13mArquitectura de la demo
La demo se compone de microservicios escritos en distintos lenguajes de programación que se comunican entre sí mediante gRPC y HTTP, además de un generador de carga que usa Locust para simular tráfico de usuarios. El código fuente original de esta demo se ha modificado para usar la instrumentación de ClickStack.

Crédito: https://opentelemetry.io/docs/demo/architecture/
Puedes encontrar más detalles sobre la demo en:
Añade el repositorio del gráfico de Helm de ClickStack
Para implementar ClickStack, usamos el gráfico de Helm oficial.
Para ello, debemos añadir el repositorio de Helm de HyperDX:
helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo updateImplementar ClickStack
Con el gráfico de Helm instalado, puedes implementar ClickStack en tu clúster. Puedes ejecutar todos los componentes, incluidos ClickHouse y HyperDX, dentro de tu entorno de Kubernetes, o bien implementar solo el collector y usar Managed ClickStack para ClickHouse y la interfaz de HyperDX.
ClickStack Open Source (autogestionado)
El siguiente comando instala ClickStack en el espacio de nombres otel-demo. El gráfico de Helm implementa:
- Una instancia de ClickHouse
- HyperDX
- La distribución de ClickStack del OTel collector
- MongoDB para almacenar el estado de la aplicación HyperDX
Si no vas a implementar la demo de OTel, puedes modificar esto y seleccionar un espacio de nombres adecuado.
helm install my-hyperdx hyperdx/hdx-oss-v2 --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demoManaged ClickStack
Si prefieres usar Managed ClickStack, puedes implementar ClickStack y deshabilitar el ClickHouse incluido.
# especifica las credenciales de ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # URL https completa
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-demoPara verificar el estado de la implementación, ejecuta el siguiente comando y confirma que todos los componentes estén en estado Running. Ten en cuenta que ClickHouse no aparecerá si estás usando 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 14mAcceder a la UI de HyperDX
Por seguridad, el servicio usa ClusterIP y no se expone externamente de forma predeterminada.
Para acceder a la UI de HyperDX, redirige el puerto 3000 al puerto 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-demoAcceda a http://localhost:8080 para abrir la UI de HyperDX.
Cree un usuario e indique un nombre de usuario y una contraseña que cumplan los requisitos de complejidad.

Obtener la API key de ingesta
La ingestión en el OTel collector desplegado por el ClickStack collector está protegida con una API key de ingesta.
Ve a Configuración del equipo y copia la API key de ingesta de la sección API Keys. Esta API key garantiza una ingestión de datos segura a través del OpenTelemetry collector.

Crear un Secret de Kubernetes para la API key
Cree un nuevo Secret de Kubernetes con la API key de ingesta y un ConfigMap que contenga la ubicación del OTel collector desplegado con el gráfico de Helm de ClickStack. Los componentes posteriores lo usarán para permitir la ingesta en el collector desplegado con el gráfico de Helm de 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:4318Reinicie los pods de OpenTelemetry Demo Application para que apliquen la API key de ingesta.
kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demoLas trazas y los logs de los servicios de demostración deberían empezar a llegar a HyperDX.

Añade el repositorio de Helm de OpenTelemetry
Para recopilar métricas de Kubernetes, implementaremos un OTel collector estándar y lo configuraremos para enviar datos de forma segura a nuestro ClickStack collector mediante la API key de ingesta anterior.
Para ello, debemos instalar el repositorio de Helm de OpenTelemetry:
# Add Otel Helm repo
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts Desplegar los componentes del collector de Kubernetes
Para recopilar logs y métricas tanto del clúster en sí como de cada nodo, es necesario implementar dos OpenTelemetry collectors independientes, cada uno con su propio manifiesto. Los dos manifiestos proporcionados — k8s_deployment.yaml y k8s_daemonset.yaml — trabajan en conjunto para recopilar datos de telemetría exhaustivos de su clúster de Kubernetes.
-
k8s_deployment.yamlimplementa una sola instancia de OpenTelemetry Collector responsable de recopilar eventos y metadatos de todo el clúster. Recopila eventos de Kubernetes, métricas del clúster y enriquece los datos de telemetría con etiquetas y anotaciones de los pods de Kubernetes. Este collector se ejecuta como una implementación independiente con una sola réplica para evitar la duplicación de datos. -
k8s_daemonset.yamldespliega un colector basado en conjunto de daemon que se ejecuta en cada nodo de su clúster. Recopila métricas a nivel de nodo y de pod de Kubernetes, así como logs de contenedores, mediante componentes comokubeletstats,hostmetricsy procesadores Kubernetes Attribute Processor. Estos colectores enriquecen los logs con metadatos y los envían a HyperDX mediante el exportador OTLP.
En conjunto, estos manifiestos habilitan la observabilidad de pila completa en todo el clúster, desde la infraestructura hasta la telemetría a nivel de aplicación, y envían los datos enriquecidos a ClickStack para su análisis centralizado.
Primero, instale el colector como una implementación:
# 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:
- otlphttpA continuación, despliega el collector como un conjunto de daemon para métricas y logs a nivel de nodo y pod:
# 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:
- otlphttpExplora los datos de Kubernetes en HyperDX
Ve a tu UI de HyperDX, ya sea usando tu instancia desplegada en Kubernetes o a través de Managed ClickStack.
Managed ClickStack
Si usas Managed ClickStack, simplemente inicia sesión en tu servicio de ClickHouse Cloud y selecciona "ClickStack" en el menú de la izquierda. La autenticación será automática y no necesitarás crear un usuario.
Las fuentes de datos para logs, métricas y trazas se crearán previamente para ti.
ClickStack Open Source
Para acceder a HyperDX desplegado localmente, puedes usar el reenvío de puertos con el siguiente comando y acceder a HyperDX en 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-demoPara explorar los datos de Kubernetes, ve al dashboard predefinido específico en /kubernetes, por ejemplo http://localhost:8080/kubernetes.
Cada una de las pestañas, Pods, Nodos y Espacios de nombres, debería mostrar datos.
