> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# مراقبة Kubernetes
> بدء استخدام ClickStack ومراقبة Kubernetes
export const Image = ({img, alt, size}) => {
return
;
};
يتيح لك هذا الدليل جمع السجلات والمقاييس من نظام Kubernetes لديك وإرسالها إلى **ClickStack** لعرضها وتحليلها. وبالنسبة إلى البيانات التجريبية، يمكنك اختياريًا استخدام النسخة المتفرعة الخاصة بـ ClickStack من OpenTelemetry demo الرسمي.
## المتطلبات الأساسية
يتطلب هذا الدليل توفّر ما يلي لديك:
* **عنقود Kubernetes** (يُوصى بالإصدار v1.20+) مع توفر ما لا يقل عن 32 GiB من RAM و100GB من مساحة القرص على إحدى العقد من أجل ClickHouse.
* **[Helm](https://helm.sh/)** v3+
* **`kubectl`**، مُعدّ للتفاعل مع عنقودك
## خيارات النشر
يمكنك اتباع هذا الدليل باستخدام أحد خياري النشر التاليين:
* **Open Source ClickStack**: انشر ClickStack بالكامل داخل عنقود Kubernetes لديك، بما في ذلك:
* ClickHouse
* HyperDX
* MongoDB (يُستخدم لحالة لوحة المعلومات وإعداداتها)
* **Managed ClickStack**، مع إدارة ClickHouse وواجهة ClickStack (HyperDX) في ClickHouse Cloud. وهذا يلغي الحاجة إلى تشغيل ClickHouse أو HyperDX داخل عنقودك.
لمحاكاة حركة مرور التطبيق، يمكنك اختياريًا نشر النسخة المتفرعة الخاصة بـ ClickStack من [**OpenTelemetry Demo Application**](https://github.com/ClickHouse/opentelemetry-demo). ويؤدي ذلك إلى إنشاء بيانات القياس عن بُعد، بما في ذلك السجلات والمقاييس والتتبعات. وإذا كانت لديك بالفعل أحمال عمل قيد التشغيل في عنقودك، فيمكنك تخطي هذه الخطوة ومراقبة الكبسولات والعُقد والحاويات الحالية.
### تثبيت cert-manager (اختياري)
إذا كان إعدادك يتطلب شهادات TLS، فثبّت [cert-manager](https://cert-manager.io/) باستخدام Helm:
```shell theme={null}
# 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](/ar/clickstack/integration-examples/kubernetes#forwarding-resouce-tags-to-pods) لربط logs وmetrics وtraces عبر متغير البيئة `OTEL_RESOURCE_ATTRIBUTES`.
```shell theme={null}
## 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`:
```shell theme={null}
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 البرمجية](/ar/clickstack/ingesting-data/sdks/index).
*المصدر: [https://opentelemetry.io/docs/demo/architecture/](https://opentelemetry.io/docs/demo/architecture/)*
يمكن العثور على مزيد من التفاصيل حول العرض التوضيحي في:
* [وثائق OpenTelemetry](https://opentelemetry.io/docs/demo/)
* [نسخة fork التي تحتفظ بها ClickStack](https://github.com/ClickHouse/opentelemetry-demo)
### أضِف مستودع Helm chart الخاص بـ ClickStack
لنشر ClickStack، نستخدم [Helm chart الرسمي](/ar/clickstack/deployment/helm).
ويتطلب ذلك إضافة مستودع Helm الخاص بـ HyperDX:
```shell theme={null}
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 في مساحة الأسماء `otel-demo`. ويقوم مخطط Helm بنشر ما يلي:
* مثيل ClickHouse
* HyperDX
* توزيعة ClickStack من OTel collector
* MongoDB لتخزين حالة تطبيق HyperDX
قد تحتاج إلى تعديل `storageClassName` وفقًا لإعدادات عنقود Kubernetes لديك.
يمكن للمستخدمين الذين لا ينشرون العرض التوضيحي لـ OTel تعديل ذلك واختيار مساحة أسماء مناسبة.
```shell theme={null}
helm install my-hyperdx hyperdx/hdx-oss-v2 --set clickhouse.persistence.dataSize=100Gi --set global.storageClassName="standard-rwo" -n otel-demo
```
**ClickStack في بيئة الإنتاج**
يثبّت هذا المخطط أيضًا ClickHouse وOTel collector. وبالنسبة إلى بيئة الإنتاج، يُوصى باستخدام مشغِّلَي ClickHouse وOTel collector و/أو استخدام Managed ClickStack.
لتعطيل clickhouse وOTel collector، عيّن القيم التالية:
```shell theme={null}
helm install myrelease --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false
```
إذا كنت تفضّل استخدام Managed ClickStack، فيمكنك نشر ClickStack و[تعطيل ClickHouse المضمَّن](/ar/clickstack/deployment/helm#using-clickhouse-cloud).
ينشر المخطط حاليًا كلًا من HyperDX وMongoDB دائمًا. ومع أن هذه المكوّنات توفّر مسار وصول بديلًا، فإنها غير مدمجة مع آليات المصادقة في ClickHouse Cloud. وهذه المكوّنات مخصّصة للمسؤولين في نموذج النشر هذا، [إذ توفّر الوصول إلى مفتاح API الآمن للإدخال](#retrieve-ingestion-api-key) اللازم لإدخال البيانات عبر OTel collector المنشور، ولكن لا ينبغي إتاحتها للمستخدمين النهائيين.
```shell theme={null}
# حدّد بيانات اعتماد ClickHouse Cloud
export CLICKHOUSE_URL= # عنوان URL الكامل لـ https
export CLICKHOUSE_USER=
export 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:
```shell theme={null}
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
حتى عند استخدام Managed ClickStack، يظل مثيل HyperDX المحلي المنشور في Kubernetes cluster مطلوبًا. فهو يوفّر مفتاح استيعاب يديره OpAMP server المضمَّن مع HyperDX، ما يؤمّن استيعاب البيانات عبر OTel collector المنشور — وهي ميزة غير متاحة حاليًا في Managed ClickStack.
لأسباب أمنية، تستخدم الخدمة `ClusterIP` ولا تكون مكشوفة خارجيًا افتراضيًا.
للوصول إلى واجهة HyperDX، نفّذ توجيه المنفذ من 3000 إلى المنفذ المحلي 8080.
```shell theme={null}
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](http://localhost:8080) للوصول إلى واجهة HyperDX.
أنشئ مستخدمًا، ووفّر اسم مستخدم وكلمة مرور يستوفيان متطلبات التعقيد.
### استرداد مفتاح API للإدخال
تكون عملية إدخال البيانات إلى OTel collector الذي ينشره ClickStack collector مؤمّنة باستخدام مفتاح إدخال.
انتقل إلى [`Team Settings`](http://localhost:8080/team) وانسخ `Ingestion API Key` من قسم `API Keys`. يضمن مفتاح API هذا أمان إدخال البيانات عبر OpenTelemetry collector.
### إنشاء سر Kubernetes لمفتاح API للإدخال
أنشئ سر Kubernetes جديدًا يتضمن مفتاح API للإدخال وconfig map تحتوي على موقع OTel collector المنشور باستخدام مخطط Helm الخاص بـ ClickStack. ستستخدم المكونات اللاحقة ذلك للسماح بإدخال البيانات إلى الـ OTel collector المنشور باستخدام مخطط Helm الخاص بـ ClickStack:
```shell theme={null}
# create secret with the ingestion API key
kubectl create secret generic hyperdx-secret \
--from-literal=HYPERDX_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 application لأخذ مفتاح API للإدخال في الاعتبار.
```shell theme={null}
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:
```shell theme={null}
# 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:
```shell theme={null}
# 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
```
```yaml theme={null}
# 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) لجمع المقاييس والسجلات على مستوى العقدة والحاوية:
```shell theme={null}
# 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
```
```yaml theme={null}
# 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، فما عليك سوى تسجيل الدخول إلى خدمة ClickHouse Cloud الخاصة بك واختيار "ClickStack" من القائمة اليمنى. ستتم مصادقتك تلقائيًا، ولن تحتاج إلى إنشاء مستخدم.
سيتم إنشاء مصادر البيانات للسجلات والمقاييس والتتبعات مسبقًا لك.
للوصول إلى HyperDX المنشور محليًا، يمكنك إجراء إعادة توجيه للمنفذ باستخدام الأمر التالي، ثم الوصول إلى HyperDX على [http://localhost:8080](http://localhost:8080).
```shell theme={null}
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 في بيئة الإنتاج**
في بيئة الإنتاج، نوصي باستخدام مورد Ingress مع TLS إذا لم تكن تستخدم Managed ClickStack. على سبيل المثال:
```shell theme={null}
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
```
لاستكشاف بيانات Kubernetes، انتقل إلى لوحة المعلومات المخصّصة على `/kubernetes`، مثل [http://localhost:8080/kubernetes](http://localhost:8080/kubernetes).
يُفترض أن تكون علامات التبويب Pods وNodes وNamespaces جميعها معبأة بالبيانات.