يتيح لك هذا الدليل جمع السجلات والمقاييس من نظام Kubernetes لديك وإرسالها إلى ClickStack لعرضها وتحليلها. وبالنسبة إلى البيانات التجريبية، يمكنك اختياريًا استخدام النسخة المتفرعة الخاصة بـ ClickStack من OpenTelemetry demo الرسمي.
المتطلبات الأساسية
يتطلب هذا الدليل توفّر ما يلي لديك:
- عنقود Kubernetes (يُوصى بالإصدار v1.20+) مع توفر ما لا يقل عن 32 GiB من RAM و100GB من مساحة القرص على إحدى العقد من أجل ClickHouse.
- Helm v3+
kubectl، مُعدّ للتفاعل مع عنقودك
خيارات النشر
يمكنك اتباع هذا الدليل باستخدام أحد خياري النشر التاليين:
-
Open Source ClickStack: انشر ClickStack بالكامل داخل عنقود Kubernetes لديك، بما في ذلك:
- ClickHouse
- HyperDX
- MongoDB (يُستخدم لحالة لوحة المعلومات وإعداداتها)
-
Managed ClickStack، مع إدارة ClickHouse وواجهة ClickStack (HyperDX) في ClickHouse Cloud. وهذا يلغي الحاجة إلى تشغيل ClickHouse أو HyperDX داخل عنقودك.
لمحاكاة حركة مرور التطبيق، يمكنك اختياريًا نشر النسخة المتفرعة الخاصة بـ ClickStack من OpenTelemetry Demo Application. ويؤدي ذلك إلى إنشاء بيانات القياس عن بُعد، بما في ذلك السجلات والمقاييس والتتبعات. وإذا كانت لديك بالفعل أحمال عمل قيد التشغيل في عنقودك، فيمكنك تخطي هذه الخطوة ومراقبة الكبسولات والعُقد والحاويات الحالية.
تثبيت 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 (اختياري)
هذه الخطوة اختيارية ومخصّصة للحالات التي لا توجد فيها أي وحدات pod حالية لمراقبتها. ورغم أن المستخدمين الذين لديهم خدمات منشورة بالفعل في بيئة Kubernetes الخاصة بهم يمكنهم تخطيها، فإن هذا العرض التجريبي يتضمن خدمات مصغّرة مزوّدة بـinstrumentation تولّد بيانات trace وsession replay، مما يتيح للمستخدمين استكشاف جميع ميزات ClickStack.
يقوم ما يلي بنشر نسخة ClickStack fork من حزمة تطبيق OpenTelemetry Demo داخل عنقود Kubernetes، والمخصّصة لاختبار observability واستعراض instrumentation. وهي تتضمن خدمات مصغّرة backend، ومولّدات حمل، وpipelines للـ telemetry، وبنية تحتية داعمة (مثل Kafka وRedis)، وعمليات تكامل SDK مع ClickStack.
تُنشر جميع الخدمات في مساحة الأسماء otel-demo. ويتضمن كل Deployment ما يلي:
- automatic instrumentation باستخدام OTel وClickStack SDKS لكل من traces وmetrics وlogs.
- ترسل جميع الخدمات بيانات instrumentation الخاصة بها إلى OpenTelemetry Collector باسم
my-hyperdx-hdx-oss-v2-otel-collector(غير منشور). - تمرير وسوم resource لربط logs وmetrics وtraces عبر متغير البيئة
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 chart الخاص بـ ClickStack
لنشر ClickStack، نستخدم Helm chart الرسمي.
ويتطلب ذلك إضافة مستودع Helm الخاص بـ HyperDX:
helm repo add hyperdx https://hyperdxio.github.io/helm-charts
helm repo updateنشر ClickStack
بعد تثبيت مخطط Helm، يمكنك نشر ClickStack في عنقودك. يمكنك إما تشغيل جميع المكوّنات، بما في ذلك ClickHouse وHyperDX، داخل بيئة Kubernetes لديك، أو الاكتفاء بنشر OTel collector والاعتماد على Managed ClickStack لكلٍّ من ClickHouse وواجهة HyperDX.
ClickStack Open Source (مُدار ذاتيًا)
يثبّت الأمر التالي ClickStack في مساحة الأسماء otel-demo. ويقوم مخطط Helm بنشر ما يلي:
- مثيل ClickHouse
- HyperDX
- توزيعة ClickStack من OTel collector
- MongoDB لتخزين حالة تطبيق HyperDX
يمكن للمستخدمين الذين لا ينشرون العرض التوضيحي لـ OTel تعديل ذلك واختيار مساحة أسماء مناسبة.
helm install my-hyperdx hyperdx/hdx-oss-v2 --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demoManaged ClickStack
إذا كنت تفضّل استخدام Managed 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. لاحظ أن ClickHouse لن يظهر إذا كنت تستخدم 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الوصول إلى واجهة 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 collector مؤمّنة باستخدام مفتاح إدخال.
انتقل إلى Team Settings وانسخ Ingestion API Key من قسم API Keys. يضمن مفتاح API هذا أمان إدخال البيانات عبر OpenTelemetry collector.

إنشاء سر Kubernetes لمفتاح API
أنشئ سر Kubernetes جديدًا يتضمن مفتاح API للإدخال وconfig map تحتوي على موقع 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أعد تشغيل وحدات pod الخاصة بتطبيق OpenTelemetry Demo لتطبيق مفتاح API للإدخال.
kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demoيُفترض أن تبدأ الآن بيانات التتبّع والسجلات من الخدمات التجريبية بالتدفّق إلى HyperDX.

أضف مستودع Helm الخاص بـ OpenTelemetry
لجمع مقاييس Kubernetes، سنقوم بنشر OTel collector قياسي وتهيئته لإرسال البيانات بأمان إلى ClickStack collector الخاص بنا باستخدام مفتاح API الخاص بالاستيعاب المذكور أعلاه.
يتطلب ذلك تثبيت مستودع Helm الخاص بـ OpenTelemetry:
# Add Otel Helm repo
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts نشر مكوّنات الـ collector في Kubernetes
لجمع السجلات والمقاييس من كلٍّ من المجموعة نفسها وكل عقدة على حدة، سنحتاج إلى نشر مُجمِّعَي بيانات OpenTelemetry منفصلَين، لكلٍّ منهما ملف manifest خاص به. يعمل الملفان المُرفقان - k8s_deployment.yaml وk8s_daemonset.yaml - معًا لجمع بيانات القياس الشاملة من مجموعة Kubernetes الخاصة بك.
-
k8s_deployment.yamlينشر مثيلًا واحدًا من OpenTelemetry Collector مسؤولًا عن جمع الأحداث والبيانات الوصفية على مستوى العُنقود بأكمله. ويجمع أحداث Kubernetes ومقاييس العُنقود، ويُثري بيانات الرصد بملصقات البودات وتعليقاتها التوضيحية. ويعمل هذا المجمِّع كعملية نشر مستقلة مع نسخة متماثلة واحدة لتجنّب تكرار البيانات. -
k8s_daemonset.yamlينشر مجمِّعًا قائمًا على DaemonSet يعمل على كل عقدة في العُنقود. ويجمع المقاييس على مستوى العقدة وعلى مستوى البود، بالإضافة إلى سجلات الحاويات، باستخدام مكوّنات مثلkubeletstatsوhostmetricsوKubernetes Attribute Processor. وتُثري هذه المجمِّعات السجلات بالبيانات الوصفية وترسلها إلى HyperDX باستخدام مُصدِّر OTLP.
تُتيح هذه الملفات التعريفية مجتمعةً رصدًا شاملًا للمكدس الكامل عبر الكلستر، من البنية التحتية وصولًا إلى بيانات القياس عن بُعد على مستوى التطبيق، وترسل البيانات المُثراة إلى ClickStack للتحليل المركزي.
أولاً، قم بتثبيت المُجمِّع كـ Deployment:
# 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بعد ذلك، انشر المُجمِّع بوصفه DaemonSet لجمع المقاييس والسجلات على مستوى العقدة والبود:
# 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 أو من خلال Managed ClickStack.
Managed ClickStack
إذا كنت تستخدم Managed ClickStack، فما عليك سوى تسجيل الدخول إلى خدمة ClickHouse Cloud الخاصة بك واختيار "ClickStack" من القائمة اليمنى. ستتم مصادقتك تلقائيًا، ولن تحتاج إلى إنشاء مستخدم.
سيتم إنشاء مصادر البيانات للسجلات والمقاييس والتتبعات مسبقًا لك.
ClickStack Open Source
للوصول إلى 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 جميعها معبأة بالبيانات.
