Este guia permite coletar logs e métricas do seu sistema Kubernetes, enviando-os ao ClickStack para visualização e análise. Para dados de demonstração, também é possível usar o fork do ClickStack da demo oficial do OpenTelemetry.
Pré-requisitos
Este guia requer que você tenha:
- Um cluster Kubernetes (v1.20+ recomendado) com pelo menos 32 GiB de RAM e 100 GB de espaço em disco disponíveis em um nó para o ClickHouse.
- Helm v3+
kubectl, configurado para interagir com seu cluster
Opções de implantação
Você pode seguir este guia usando qualquer uma das seguintes opções de implantação:
-
Open Source ClickStack: implante o ClickStack inteiramente no seu cluster Kubernetes, incluindo:
- ClickHouse
- HyperDX
- MongoDB (usado para o estado e a configuração do dashboard)
-
Managed ClickStack, com o ClickHouse e a UI do ClickStack (HyperDX) gerenciados no ClickHouse Cloud. Isso elimina a necessidade de executar o ClickHouse ou o HyperDX dentro do seu cluster.
Para simular o tráfego da aplicação, você também pode implantar o fork da ClickStack da OpenTelemetry Demo Application. Isso gera dados de telemetria, incluindo logs, métricas e traces. Se você já tiver workloads em execução no seu cluster, pode pular esta etapa e monitorar os pods, nós e contêineres existentes.
Instale o cert-manager (opcional)
Se a sua configuração exigir certificados TLS, instale o cert-manager usando o 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-managerImplante o OpenTelemetry Demo (Opcional)
Este passo é opcional e foi pensado para quem não tem pods existentes para monitorar. Embora usuários com serviços já implantados em seu ambiente Kubernetes possam pular esta etapa, esta demonstração inclui microsserviços instrumentados que geram dados de traces e session replay, permitindo explorar todos os recursos do ClickStack.
O conteúdo a seguir implanta o fork do ClickStack da pilha da aplicação OpenTelemetry Demo em um cluster Kubernetes, adaptado para testes de observabilidade e demonstração de instrumentação. Ele inclui microsserviços de back-end, geradores de carga, pipelines de telemetria, infraestrutura de suporte (por exemplo, Kafka e Redis) e integrações de SDK com o ClickStack.
Todos os serviços são implantados no espaço de nomes otel-demo. Cada implantação inclui:
- Instrumentação automática com OTel e ClickStack SDKS para traces, métricas e logs.
- Todos os serviços enviam sua instrumentação para um collector OpenTelemetry
my-hyperdx-hdx-oss-v2-otel-collector(não implantado) - Encaminhamento de tags de recurso para correlacionar logs, métricas e traces por meio da variável de ambiente
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.yamlAo implantar a demo, confirme que todos os pods foram criados com sucesso e estão no 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 13mArquitetura da demo
A demo é composta por microsserviços escritos em diferentes linguagens de programação, que se comunicam entre si por gRPC e HTTP, e por um gerador de carga que usa o Locust para simular tráfego de usuários. O código-fonte original desta demo foi modificado para usar a instrumentação do ClickStack.

Crédito: https://opentelemetry.io/docs/demo/architecture/
Mais detalhes sobre a demo podem ser encontrados em:
Adicione o repositório do Chart do Helm do ClickStack
Para implantar o ClickStack, usamos o Chart do Helm oficial.
Para isso, é necessário adicionar o repositório Helm do HyperDX:
helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo updateImplante o ClickStack
Com o chart do Helm instalado, você pode implantar o ClickStack no seu cluster. Você pode executar todos os componentes, incluindo ClickHouse e HyperDX, no seu ambiente Kubernetes, ou implantar apenas o collector e usar o Managed ClickStack para o ClickHouse e a interface do HyperDX.
ClickStack Open Source (autogerenciado)
O comando a seguir instala o ClickStack no espaço de nomes otel-demo. O chart do Helm implanta:
- Uma instância do ClickHouse
- HyperDX
- A distribuição do OTel collector do ClickStack
- MongoDB para armazenar o estado da aplicação HyperDX
Quem não estiver implantando a demo do OTel pode alterar isso e selecionar um espaço de nomes apropriado.
helm install my-hyperdx hyperdx/hdx-oss-v2 --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demoManaged ClickStack
Se você preferir usar o Managed ClickStack, poderá implantar o ClickStack e desabilitar o ClickHouse incluído.
# especifique as credenciais do 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 o status da implantação, execute o comando a seguir e confirme que todos os componentes estão no estado Running. Observe que o ClickHouse não aparecerá se você estiver 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 14mAcesse a interface do HyperDX
Por segurança, o serviço usa IP de cluster e não é exposto externamente por padrão.
Para acessar a UI do HyperDX, faça o encaminhamento da porta 3000 para a porta 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-demoAcesse http://localhost:8080 para acessar a UI do HyperDX.
Crie um usuário, fornecendo um nome de usuário e uma senha que atendam aos requisitos de complexidade.

Obter API key de ingestão
A ingestão no OTel collector implantado pelo ClickStack collector é protegida por uma API key de ingestão.
Acesse Team Settings e copie a Ingestion API Key na seção API Keys. Essa API key garante que a ingestão de dados pelo OpenTelemetry collector seja segura.

Criar Secret do Kubernetes com API key
Crie um novo Secret do Kubernetes com a API key de ingestão e um ConfigMap contendo a localização do OTel collector implantado com o Chart do Helm do ClickStack. Os componentes das próximas etapas usarão isso para permitir a ingestão no collector implantado com o Chart do Helm do 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 os pods do OpenTelemetry Demo Application para aplicar a API key de ingestão.
kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demoOs traces e logs dos serviços de demonstração agora devem começar a chegar ao HyperDX.

Adicione o repositório Helm do OpenTelemetry
Para coletar métricas do Kubernetes, vamos implantar um OTel collector padrão, configurando-o para enviar dados com segurança ao nosso ClickStack collector usando a API key de ingestão acima.
Isso exige a instalação do repositório Helm do OpenTelemetry:
# Add Otel Helm repo
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts Implantar componentes do collector no Kubernetes
Para coletar logs e métricas tanto do próprio cluster quanto de cada nó, será necessário implantar dois OpenTelemetry Collectors separados, cada um com seu próprio manifesto. Os dois manifestos fornecidos — k8s_deployment.yaml e k8s_daemonset.yaml — trabalham em conjunto para coletar dados de telemetria completos do seu cluster Kubernetes.
-
k8s_deployment.yamlimplanta uma única instância do OpenTelemetry Collector responsável por coletar eventos e metadados de todo o cluster. Ele coleta eventos do Kubernetes, métricas do cluster e enriquece os dados de telemetria com labels e anotações dos pods. Esse coletor é executado como uma implantação independente com uma única réplica para evitar dados duplicados. -
k8s_daemonset.yamlimplanta um coletor baseado em um Conjunto de Daemon que é executado em cada nó do seu cluster. Ele coleta métricas em nível de nó e de pod do Kubernetes, bem como logs de contêineres, usando componentes comokubeletstats,hostmetricse Kubernetes Attribute Processors. Esses coletores enriquecem os logs com metadados e os enviam para o HyperDX usando o exportador OTLP.
Juntos, esses manifestos habilitam a observabilidade full-stack em todo o cluster, da infraestrutura à telemetria em nível de aplicação, e enviam os dados enriquecidos ao ClickStack para análise centralizada.
Primeiro, instale o collector como uma Implantação:
# 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:
- otlphttpEm seguida, implante o collector como um Conjunto de Daemon para métricas e logs em nível de nó e 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:
- otlphttpExplore os dados do Kubernetes no HyperDX
Navegue até a interface do HyperDX — usando a instância implantada no Kubernetes ou via Managed ClickStack.
Managed ClickStack
Se estiver usando Managed ClickStack, basta fazer login no seu serviço ClickHouse Cloud e selecionar "ClickStack" no menu à esquerda. Você será autenticado automaticamente e não precisará criar um usuário.
As fontes de dados de logs, métricas e traces serão pré-criadas para você.
ClickStack Open Source
Para acessar o HyperDX implantado localmente, você pode fazer um redirecionamento de porta usando o comando local e acessar o HyperDX em 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 os dados do Kubernetes, navegue até o dashboard dedicado em /kubernetes, por exemplo http://localhost:8080/kubernetes.
Cada uma das abas — Pods, Nodes e Namespaces — deve estar preenchida com dados.
