Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Monitoramento de Kubernetes

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

Implante 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.yaml

Ao 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          13m

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

Arquitetura

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 update

Implante 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-demo
Managed 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-demo

Para 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          14m

Acesse 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-demo

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

UI do HyperDX

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.

Copiar API key

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:4318

Reinicie 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-demo

Os traces e logs dos serviços de demonstração agora devem começar a chegar ao HyperDX.

Dados do Kubernetes no 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.yaml implanta 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.yaml implanta 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 como kubeletstats, hostmetrics e 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.yaml
k8s_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:
          - otlphttp

Em 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.yaml
k8s_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:
          - otlphttp

Explore 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-demo

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

ClickHouse no Kubernetes
Navigation