Saltar al contenido principal
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.
1

​
Instalar cert-manager (opcional)

Si su implementación requiere certificados TLS, instale cert-manager con Helm:
# Agregar repositorio de Cert Manager 

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-manager
2

​
Despliega 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.
## descargar el archivo de manifiesto de Kubernetes del demo
curl -O https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
# alternativa con wget
# wget https://raw.githubusercontent.com/ClickHouse/opentelemetry-demo/refs/heads/main/kubernetes/opentelemetry-demo.yaml
kubectl apply --namespace otel-demo -f opentelemetry-demo.yaml
Tras 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          13m

​
Arquitectura 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:
3

​
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 update
4

​
Implementar 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.
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
Puede que necesites ajustar storageClassName según la configuración de tu clúster de Kubernetes.
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-demo
ClickStack en producciónEste gráfico también instala ClickHouse y el OTel collector. Para producción, se recomienda usar los operadores de ClickHouse y del OTel collector, y/o usar Managed ClickStack.Para deshabilitar ClickHouse y el OTel collector, establece los siguientes valores:
helm install myrelease <chart-name-or-path> --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false
Si prefieres usar Managed ClickStack, puedes implementar ClickStack y deshabilitar el ClickHouse incluido.
Actualmente, el gráfico siempre implementa tanto HyperDX como MongoDB. Aunque estos componentes ofrecen una vía de acceso alternativa, no están integrados con la autenticación de ClickHouse Cloud. En este modelo de implementación, estos componentes están pensados para administradores, ya que proporcionan acceso a la clave segura de ingestión necesaria para ingestar a través del OTel collector implementado, pero no deberían exponerse a los usuarios finales.
# 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-demo
Para 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          14m
5

​
Acceder a la UI de HyperDX

Incluso si usas Managed ClickStack, la instancia local de HyperDX desplegada en el clúster de Kubernetes sigue siendo necesaria. Proporciona una clave de ingestión gestionada por el servidor OpAMP incluido con HyperDX, lo que protege la ingestión a través del OTel collector desplegado, una capacidad que actualmente no está disponible en Managed ClickStack.
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-demo
Acceda 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.
6

​
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.
7

​
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:
# crear el secret con la API key de ingesta
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_API_KEY=<ingestion_api_key> \
-n otel-demo

# crear un ConfigMap que apunte al ClickStack OTel collector desplegado anteriormente
kubectl create configmap -n=otel-demo otel-config-vars --from-literal=YOUR_OTEL_COLLECTOR_ENDPOINT=http://my-hyperdx-hdx-oss-v2-otel-collector:4318
Reinicie 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-demo
Las trazas y los logs de los servicios de demostración deberían empezar a llegar a HyperDX.
8

​
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:
# Agregar el repositorio Helm de OTel
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
9

​
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.yaml implementa 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.yaml despliega 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 como kubeletstats, hostmetrics y 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:
# descargar el archivo de manifiesto
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_deployment.yaml
# instalar el gráfico de Helm
helm install --namespace otel-demo k8s-otel-deployment open-telemetry/opentelemetry-collector -f k8s_deployment.yaml

# k8s_deployment.yaml
mode: deployment

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
 
# Solo queremos uno de estos collectors; con más, se generarían datos duplicados
replicaCount: 1
 
presets:
  kubernetesAttributes:
    enabled: true
    # Cuando está habilitado, el procesador extraerá todas las labels de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la label será la clave.
    extractAllPodLabels: true
    # Cuando está habilitado, el procesador extraerá todas las annotations de un pod de Kubernetes asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la annotation será la clave.
    extractAllPodAnnotations: true
  # Configura el collector para recopilar eventos de Kubernetes.
  # Añade el k8sobject receiver a la canalización de logs y recopila eventos de Kubernetes de forma predeterminada.
  # Más información: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-objects-receiver
  kubernetesEvents:
    enabled: true
  # Configura el Kubernetes Cluster Receiver para recopilar métricas a nivel de clúster.
  # Añade el k8s_cluster receiver a la canalización de métricas e incorpora las reglas necesarias a ClusteRole.
  # Más información: 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:
          - otlphttp
A continuación, despliega el collector como un conjunto de daemon para métricas y logs a nivel de nodo y pod:
# descargar el archivo de manifiesto
curl -O https://raw.githubusercontent.com/ClickHouse/clickhouse-docs/refs/heads/main/docs/use-cases/observability/clickstack/example-datasets/_snippets/k8s_daemonset.yaml
# instalar el gráfico de Helm
helm install --namespace otel-demo k8s-otel-daemonset open-telemetry/opentelemetry-collector -f k8s_daemonset.yaml

# k8s_daemonset.yaml
mode: daemonset

image:
  repository: otel/opentelemetry-collector-contrib
  tag: 0.123.0
   
# Necesario para usar las métricas de utilización de cpu/memoria de kubeletstats
clusterRole:
  create: true
  rules:
    - apiGroups:
        - ''
      resources:
        - nodes/proxy
      verbs:
        - get
 
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  # Configura el procesador de Kubernetes para agregar metadatos de Kubernetes.
  # Agrega el procesador k8sattributes a todas las canalizaciones y añade las reglas necesarias al Rol de clúster.
  # Más información: https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor
  kubernetesAttributes:
    enabled: true
    # Cuando está habilitado, el procesador extraerá todas las etiquetas del pod asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la etiqueta será la clave.
    extractAllPodLabels: true
    # Cuando está habilitado, el procesador extraerá todas las anotaciones del pod asociado y las añadirá como atributos de recurso.
    # El nombre exacto de la anotación será la clave.
    extractAllPodAnnotations: true
  # Configura el recopilador para obtener métricas de nodo, pod y contenedor desde el servidor de API en un agente kubelet.
  # Agrega el receiver kubeletstats a la canalización de métricas y añade las reglas necesarias al Rol de clúster.
  # Más información: 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:
    # Configura métricas adicionales del agente kubelet
    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:
          - otlphttp
10

​
Explora 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.

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.
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-demo
ClickStack en producciónEn producción, recomendamos usar un Ingreso con TLS si no estás usando Managed ClickStack. Por ejemplo:
helm upgrade my-hyperdx hyperdx/hdx-oss-v2 \
--set hyperdx.ingress.enabled=true \
--set hyperdx.ingress.host=your-domain.com \
--set hyperdx.ingress.tls.enabled=true
Para 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.
Última modificación el 10 de junio de 2026