مراقبة Kubernetes - ClickHouse Documentation

يتيح لك هذا الدليل جمع السجلات والمقاييس من نظام 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

قد تحتاج إلى تعديل 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

الوصول إلى واجهة 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.أنشئ مستخدمًا، ووفّر اسم مستخدم وكلمة مرور يستوفيان متطلبات التعقيد.

استرداد مفتاح 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 application لأخذ مفتاح 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.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

استكشف بيانات 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 جميعها معبأة بالبيانات.

​المتطلبات الأساسية

​خيارات النشر

​تثبيت cert-manager (اختياري)

​نشر OpenTelemetry Demo (اختياري)

​بنية العرض التوضيحي

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

​نشر ClickStack

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

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

​إنشاء سر Kubernetes لمفتاح API للإدخال

​أضف مستودع Helm الخاص بـ OpenTelemetry

​نشر مكوّنات الـ collector في Kubernetes

​استكشف بيانات Kubernetes في HyperDX

المتطلبات الأساسية

خيارات النشر

تثبيت cert-manager (اختياري)

نشر OpenTelemetry Demo (اختياري)

بنية العرض التوضيحي

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

نشر ClickStack

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

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

إنشاء سر Kubernetes لمفتاح API للإدخال

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

نشر مكوّنات الـ collector في Kubernetes

استكشف بيانات Kubernetes في HyperDX