Это руководство позволит вам собирать журналы и метрики из вашей системы Kubernetes и отправлять их в ClickStack для визуализации и анализа. В качестве демонстрационных данных при желании можно использовать форк официального демо OpenTelemetry от ClickStack.
Предварительные требования
Для работы с этим руководством вам потребуется:
- Кластер Kubernetes (рекомендуется v1.20+) с как минимум 32 GiB оперативной памяти и 100 GB дискового пространства, доступными на одном узле для ClickHouse.
- Helm v3+
kubectl, настроенный для взаимодействия с вашим кластером
Варианты развертывания
Вы можете воспользоваться этим руководством, выбрав один из следующих вариантов развертывания:
-
ClickStack с открытым исходным кодом: разверните ClickStack целиком в своем кластере Kubernetes, включая:
- ClickHouse
- HyperDX
- MongoDB (используется для хранения состояния и конфигурации панели мониторинга)
-
Управляемый ClickStack, где ClickHouse и интерфейс ClickStack (HyperDX) управляются в ClickHouse Cloud. Это избавляет от необходимости запускать ClickHouse или HyperDX внутри вашего кластера.
Чтобы имитировать трафик приложения, при желании можно развернуть форк приложения OpenTelemetry Demo Application, подготовленный ClickStack. Это позволяет генерировать телеметрические данные, включая журналы, метрики и трассировки. Если в вашем кластере уже запущены рабочие нагрузки, этот шаг можно пропустить и отслеживать существующие поды, узлы и контейнеры.
Установите cert-manager (необязательно)
Если в вашей конфигурации нужны TLS-сертификаты, установите cert-manager с помощью 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Разверните OpenTelemetry Demo (необязательно)
Этот шаг необязателен и предназначен для случаев, когда у вас нет существующих подов для мониторинга. Пользователи, у которых в среде Kubernetes уже развернуты сервисы, могут пропустить его, однако это демо включает инструментированные микросервисы, которые генерируют данные трассировок и воспроизведения сеанса, что позволяет изучить все возможности ClickStack.
Ниже разворачивается форк ClickStack стека приложений OpenTelemetry Demo в кластере Kubernetes, адаптированный для тестирования обсервабилити и демонстрации инструментирования. Он включает бэкенд-микросервисы, генераторы нагрузки, конвейеры телеметрии, вспомогательную инфраструктуру (например, Kafka и Redis), а также интеграции SDK с ClickStack.
Все сервисы развертываются в пространстве имен otel-demo. Каждое развертывание включает:
- Автоматическое инструментирование с OTel и ClickStack SDKS для трассировок, метрик и журналов.
- Все сервисы отправляют данные своего инструментирования в коллектор OpenTelemetry
my-hyperdx-hdx-oss-v2-otel-collector(не развернут) - Пересылка тегов ресурсов для корреляции журналов, метрик и трассировок через переменную среды
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После развертывания демо убедитесь, что все поды успешно созданы и находятся в состоянии 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Архитектура демо
Демо состоит из микросервисов, написанных на разных языках программирования, которые взаимодействуют друг с другом по gRPC и HTTP, а также генератора нагрузки, использующего Locust для имитации пользовательского трафика. Оригинальный исходный код этого демо был изменён, чтобы использовать инструментирование ClickStack.

Источник: https://opentelemetry.io/docs/demo/architecture/
Дополнительные сведения о демо можно найти здесь:
Добавьте репозиторий Helm-чарта ClickStack
Для развертывания ClickStack мы используем официальный Helm-чарт.
Для этого необходимо добавить Helm-репозиторий HyperDX:
helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo updateРазвертывание ClickStack
После установки Helm-чарта вы можете развернуть ClickStack в своем кластере. Можно либо запустить все компоненты, включая ClickHouse и HyperDX, в своей среде Kubernetes, либо развернуть только collector и использовать Управляемый ClickStack для ClickHouse и интерфейса HyperDX.
ClickStack с открытым исходным кодом (самоуправляемый)
Следующая команда устанавливает ClickStack в пространстве имен otel-demo. Helm-чарт развертывает:
- Экземпляр ClickHouse
- HyperDX
- Дистрибутив OTel collector от ClickStack
- MongoDB для хранения состояния приложения HyperDX
Если вы не развертываете OTel demo, можете изменить этот параметр, указав подходящее пространство имен.
helm install my-hyperdx hyperdx/hdx-oss-v2 --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demoУправляемый ClickStack
Если вы предпочитаете использовать Управляемый ClickStack, можно развернуть ClickStack и отключить входящий в комплект ClickHouse.
# укажите учетные данные ClickHouse Cloud
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # полный URL https
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Чтобы проверить статус развертывания, выполните следующую команду и убедитесь, что все компоненты находятся в состоянии Running. Обратите внимание: если вы используете Управляемый ClickStack, ClickHouse будет отсутствовать:
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Откройте интерфейс HyperDX
В целях безопасности сервис использует ClusterIP и по умолчанию недоступен извне.
Чтобы открыть интерфейс HyperDX, настройте проброс порта с 3000 на локальный порт 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Откройте http://localhost:8080, чтобы перейти в интерфейс HyperDX.
Создайте пользователя, указав имя пользователя и пароль, которые соответствуют требованиям сложности.

Получение ключа API для приёма данных
Приём данных в OTel collector, развёрнутом коллектором ClickStack, защищён ключом API для приёма данных.
Перейдите в Team Settings и скопируйте Ingestion API Key из раздела API Keys. Этот ключ API обеспечивает безопасную ингестию данных через OpenTelemetry Collector.

Создание секрета Kubernetes с ключом API
Создайте новый секрет Kubernetes с ключом API для приёма данных и ConfigMap, содержащий адрес OTel collector, развернутого с помощью Helm-чарта ClickStack. Позднее другие компоненты будут использовать эти ресурсы, чтобы отправлять данные в OTel collector, развернутый с помощью 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:4318Перезапустите поды демо-приложения OpenTelemetry, чтобы изменения ключа API для приёма данных вступили в силу.
kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demoДанные трассировок и логов из демо-сервисов теперь должны начать поступать в HyperDX.

Добавьте Helm-репозиторий OpenTelemetry
Чтобы собирать метрики Kubernetes, мы развернём стандартный OTel collector и настроим его на безопасную отправку данных в наш коллектор ClickStack с помощью указанного выше ключа API для приёма данных.
Для этого нужно установить Helm-репозиторий OpenTelemetry:
# Add Otel Helm repo
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts Развёртывание компонентов коллектора Kubernetes
Для сбора журналов и метрик как с самого кластера, так и с каждого узла потребуется развернуть два отдельных коллектора OpenTelemetry, каждый со своим манифестом. Два предоставленных манифеста — k8s_deployment.yaml и k8s_daemonset.yaml — работают совместно и обеспечивают полный сбор телеметрических данных из вашего кластера Kubernetes.
-
k8s_deployment.yamlразворачивает единственный экземпляр OpenTelemetry Collector, отвечающий за сбор событий и метаданных всего кластера. Он собирает события Kubernetes, метрики кластера и обогащает телеметрические данные метками и аннотациями подов. Этот коллектор работает как автономное Развертывание с одной репликой, чтобы избежать дублирования данных. -
k8s_daemonset.yamlразворачивает коллектор в виде ДемонСет, который запускается на каждом узле кластера. Он собирает метрики на уровне узла и пода, а также журналы контейнеров, используя такие компоненты, какkubeletstats,hostmetricsи процессоры Kubernetes Attribute Processor. Эти коллекторы обогащают журналы метаданными и отправляют их в HyperDX с помощью экспортера OTLP.
В совокупности эти манифесты обеспечивают полноценную обсервабилити всего стека в рамках кластера — от инфраструктуры до телеметрии на уровне приложений — и отправляют обогащённые данные в ClickStack для централизованного анализа.
Сначала установите коллектор в виде развертывания:
# 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:
- otlphttpЗатем разверните collector в виде ДемонСета для сбора метрик и журналов на уровне узлов и подов:
# 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:
- otlphttpПросмотр данных Kubernetes в HyperDX
Перейдите в интерфейс HyperDX — либо в экземпляр, развернутый в Kubernetes, либо через Управляемый ClickStack.
Управляемый ClickStack
Если вы используете Управляемый ClickStack, просто войдите в свой сервис ClickHouse Cloud и выберите "ClickStack" в меню слева. Вы будете автоматически аутентифицированы, и создавать пользователя не потребуется.
Источники данных для журналов, метрик и трассировок будут созданы заранее.
ClickStack с открытым исходным кодом
Чтобы получить доступ к локально развернутому HyperDX, выполните локально команду проброса порта и откройте HyperDX по адресу 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Чтобы просматривать данные Kubernetes, перейдите на специальную панель мониторинга по адресу /kubernetes, например: http://localhost:8080/kubernetes.
Каждая из вкладок — Pods, Nodes и Namespaces — должна быть заполнена данными.
