مراقبة Kubernetes

بدء استخدام ClickStack ومراقبة Kubernetes

يتيح لك هذا الدليل جمع السجلات والمقاييس من نظام 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. ويؤدي ذلك إلى إنشاء بيانات القياس عن بُعد، بما في ذلك السجلات والمقاييس والتتبعات. وإذا كانت لديك بالفعل أحمال عمل قيد التشغيل في عنقودك، فيمكنك تخطي هذه الخطوة ومراقبة الكبسولات والعُقد والحاويات الحالية.

1. ​

   تثبيت 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
   
2. ​

   نشر 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/

   يمكن العثور على مزيد من التفاصيل حول العرض التوضيحي في:

   • وثائق OpenTelemetry
   • نسخة fork التي تحتفظ بها ClickStack
3. ​

   أضِف مستودع Helm chart الخاص بـ ClickStack

   لنشر ClickStack، نستخدم Helm chart الرسمي.

   ويتطلب ذلك إضافة مستودع Helm الخاص بـ HyperDX:

   helm repo add hyperdx https://hyperdxio.github.io/helm-charts
   helm repo update
   
4. ​

   نشر 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

   قد تحتاج إلى تعديل storageClassName وفقًا لإعدادات عنقود Kubernetes لديك.

   يمكن للمستخدمين الذين لا ينشرون العرض التوضيحي لـ OTel تعديل ذلك واختيار مساحة أسماء مناسبة.

   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، عيّن القيم التالية:

   helm install myrelease <chart-name-or-path> --set clickhouse.enabled=false --set clickhouse.persistence.enabled=false --set otel.enabled=false
   

   Managed ClickStack

   إذا كنت تفضّل استخدام Managed ClickStack، فيمكنك نشر ClickStack وتعطيل ClickHouse المضمَّن.

   ينشر المخطط حاليًا كلًا من HyperDX وMongoDB دائمًا. ومع أن هذه المكوّنات توفّر مسار وصول بديلًا، فإنها غير مدمجة مع آليات المصادقة في ClickHouse Cloud. وهذه المكوّنات مخصّصة للمسؤولين في نموذج النشر هذا، إذ توفّر الوصول إلى مفتاح API الآمن للإدخال اللازم لإدخال البيانات عبر OTel collector المنشور، ولكن لا ينبغي إتاحتها للمستخدمين النهائيين.

   # حدّد بيانات اعتماد 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
   
5. ​

   الوصول إلى واجهة HyperDX

   حتى عند استخدام Managed ClickStack، يظل مثيل HyperDX المحلي المنشور في Kubernetes cluster مطلوبًا. فهو يوفّر مفتاح استيعاب يديره OpAMP server المضمَّن مع HyperDX، ما يؤمّن استيعاب البيانات عبر OTel collector المنشور — وهي ميزة غير متاحة حاليًا في Managed ClickStack.

   لأسباب أمنية، تستخدم الخدمة 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.

   أنشئ مستخدمًا، ووفّر اسم مستخدم وكلمة مرور يستوفيان متطلبات التعقيد.

6. ​

   استرداد مفتاح API للإدخال

   تكون عملية إدخال البيانات إلى OTel collector الذي ينشره ClickStack collector مؤمّنة باستخدام مفتاح إدخال.

   انتقل إلى Team Settings وانسخ Ingestion API Key من قسم API Keys. يضمن مفتاح API هذا أمان إدخال البيانات عبر OpenTelemetry collector.

7. ​

   إنشاء سر 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 application لأخذ مفتاح API للإدخال في الاعتبار.

   kubectl rollout restart deployment -n otel-demo -l app.kubernetes.io/part-of=opentelemetry-demo
   

   يُفترض أن تبدأ الآن بيانات التتبّع والسجلات من الخدمات التجريبية بالتدفّق إلى HyperDX.

8. ​

   أضف مستودع 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 
   
9. ​

   نشر مكوّنات الـ 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.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
   

   بعد ذلك، انشر المُجمِّع بوصفه مجموعة خدمات (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.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
   
10. ​

    استكشف بيانات 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
    

    ClickStack في بيئة الإنتاج

    في بيئة الإنتاج، نوصي باستخدام مورد Ingress مع TLS إذا لم تكن تستخدم Managed ClickStack. على سبيل المثال:

    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.

    يُفترض أن تكون علامات التبويب Pods وNodes وNamespaces جميعها معبأة بالبيانات.