مراقبة مقاييس Temporal Cloud باستخدام ClickStack

تحذيريتوفر دعم OpenMetrics في منصة Temporal ضمن المعاينة العامة. راجع وثائقهم لمزيد من المعلومات.

توفّر Temporal طبقة تجريد لبناء تطبيقات بسيطة ومتقدمة وقادرة على التحمّل.

الخلاصة السريعةراقب مقاييس Temporal Cloud في ClickStack باستخدام Prometheus receiver في OTel. يتضمن ذلك لوحة معلومات مُعدّة مسبقًا.

التكامل مع Temporal Cloud القائم

يتناول هذا القسم كيفية تهيئة ClickStack عبر إعداد ClickStack OTel collector باستخدام Prometheus receiver.

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

مثيل ClickStack قيد التشغيل
حساب Temporal Cloud حالي
إمكانية وصول عبر شبكة HTTP من ClickStack إلى Temporal Cloud الخاص بك

إنشاء مفتاح Temporal Cloud

تأكد من أن لديك مفتاح واجهة برمجة تطبيقات لـ Temporal Cloud. يمكنك إنشاؤه باتباع دليل المصادقة في وثائق Temporal.

ملف المفتاحتأكد من تخزين بيانات الاعتماد هذه في ملف temporal.key داخل الدليل نفسه الذي يوجد فيه ملف الإعدادات الذي ستنشئه أدناه. يجب تخزين هذا المفتاح كنص فقط، من دون أي مسافات قبله أو بعده.

أنشئ تهيئة مخصصة لـ OTel collector

يتيح لك ClickStack توسيع تهيئة OpenTelemetry collector الأساسية من خلال إرفاق ملف تهيئة مخصص وضبط متغير بيئة. وتُدمج التهيئة المخصصة مع التهيئة الأساسية التي يديرها HyperDX عبر OpAMP.أنشئ ملفًا باسم temporal-metrics.yaml بالتكوين التالي:

temporal-metrics.yaml

receivers:
  prometheus/temporal:
    config:
      scrape_configs:
      - job_name: 'temporal-cloud'
        scrape_interval: 60s
        scrape_timeout: 30s
        honor_timestamps: true
        scheme: https
        authorization:
          type: Bearer
          credentials_file: /etc/otelcol-contrib/temporal.key
        static_configs:
          - targets: ['metrics.temporal.io']
        metrics_path: '/v1/metrics'

processors:
  resource:
    attributes:
      - key: service.name
        value: "temporal"
        action: upsert

service:
  pipelines:
    metrics/temporal:
      receivers: [prometheus/temporal]
      processors:
        - resource
        - memory_limiter
        - batch
      exporters:
        - clickhouse

هذا الإعداد:

يتصل بـ Temporal Cloud عند metrics.temporal.io
يجمع المقاييس كل 60 ثانية
يجمع مقاييس الأداء الرئيسية
يعيّن سمة المورد service.name المطلوبة وفقًا لـ الاتفاقيات الدلالية في OpenTelemetry
يوجّه المقاييس إلى مُصدِّر ClickHouse عبر مسار معالجة مخصص

لا تُعرِّف في التهيئة المخصصة سوى المستقبلات والمعالجات ومسارات المعالجة الجديدة
المعالجان memory_limiter وbatch ومُصدِّر clickhouse معرّفة بالفعل في تهيئة ClickStack الأساسية — ما عليك سوى الإشارة إليها بالاسم
يعيّن المعالج resource سمة service.name المطلوبة وفقًا للاتفاقيات الدلالية في OpenTelemetry
إذا كانت لديك عدة حسابات Temporal Cloud، فخصِّص service.name للتمييز بينها (مثل: "temporal-prod" و"temporal-dev")

تهيئة ClickStack لتحميل إعدادات مخصصة

لتمكين إعدادات مخصصة للمجمّع في عملية نشر ClickStack الحالية، يجب عليك:

تركيب ملف الإعدادات المخصص على المسار /etc/otelcol-contrib/custom.config.yaml
تعيين متغير البيئة CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
تركيب ملف temporal.key على المسار /etc/otelcol-contrib/temporal.key
التأكد من وجود اتصال شبكي بين ClickStack وTemporal

تفترض جميع الأوامر أنها تُنفَّذ من دليل العينة نفسه الذي يُخزَّن فيه كل من temporal-metrics.yaml وtemporal.key.

الخيار 1: Docker Compose

حدّث إعدادات نشر ClickStack لديك:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
    volumes:
      - ./temporal-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - ./temporal.key:/etc/otelcol-contrib/temporal.key:ro
      # ... other volumes ...

الخيار 2: تشغيل Docker (`docker run`) (الصورة المتكاملة)

إذا كنت تستخدم الصورة المتكاملة مع docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/temporal-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/temporal.key:/etc/otelcol-contrib/temporal.key:ro" \
  clickhouse/clickstack-all-in-one:latest

تحقّق من المقاييس في HyperDX

بعد إكمال الإعداد، سجّل الدخول إلى HyperDX وتحقّق من تدفّق المقاييس:

انتقل إلى مستكشف المقاييس
ابحث عن المقاييس التي تبدأ بـ temporal (مثل: temporal_cloud_v1_workflow_success_count، temporal_cloud_v1_poll_timeout_count)
يُفترض أن ترى نقاط بيانات المقاييس تظهر وفق فاصل التجميع الزمني الذي أعددته

لوحات المعلومات والتصورات المرئية

لمساعدتك على بدء مراقبة Temporal Cloud باستخدام ClickStack، نوفر بعض التصورات المرئية النموذجية لـ Temporal Metrics.

ملف إعداد لوحة المعلومات

استيراد لوحة المعلومات المُعدّة مسبقًا

افتح HyperDX وانتقل إلى قسم Dashboards
انقر على Import Dashboard في الزاوية العلوية اليمنى من قائمة النقاط الثلاث

ارفع ملف temporal-metrics-dashboard.json ثم انقر على Finish Import

عرض لوحة المعلومات

سيتم إنشاء لوحة المعلومات مع إعداد جميع التصورات المرئية مسبقًا:

استكشاف الأخطاء وإصلاحها

عدم تحميل ملف الإعدادات المخصّص

تحقّق من ضبط متغير البيئة CUSTOM_OTELCOL_CONFIG_FILE بشكل صحيح:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

تحقّق من أن ملف الإعدادات المخصّص مُحمَّل على المسار /etc/otelcol-contrib/custom.config.yaml:

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
# usually, docker exec clickstack ls -lh /etc/otelcol-contrib/custom.config.yaml

اعرض محتوى الإعداد المخصص للتحقق من إمكانية قراءته:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
# usually, docker exec clickstack cat /etc/otelcol-contrib/custom.config.yaml

تأكد من أن temporal.key مركّب داخل الحاوية:

docker exec <container-name> cat /etc/otelcol-contrib/temporal.key
# usually, docker exec clickstack cat /etc/otelcol-contrib/temporal.key
# This should output your temporal.key

عدم ظهور أي مقاييس في HyperDX

تحقق من إمكانية وصول الـ collector إلى Temporal Cloud:

# From the ClickStack container
docker exec <container-name> curl -H "Authorization: Bearer <API_KEY>" https://metrics.temporal.io/v1/metrics

من المفترض أن ترى مجموعة من مقاييس Prometheus مطبوعة، مثلًا.

temporal_cloud_v1_workflow_success_count{operation="CompletionStats",region="aws-us-east-2",temporal_account="l2c4n",temporal_namespace="clickpipes-aws-prd-apps-us-east-2.l2c4n",temporal_task_queue="clickpipes-svc-dc118d12-b397-4975-a33e-c2888ac12ac4-peer-flow-task-queue",temporal_workflow_type="QRepPartitionWorkflow"} 0.067 1765894320

تحقّق من أن الإعداد الفعّال يتضمّن Prometheus receiver الخاص بك:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "Prometheus:"
## usually, docker exec clickstack cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "prometheus:"

تحقّق من وجود أخطاء في سجلات وكيل collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus
# Look for connection errors or authentication failures
# docker exec clickstack cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus

تحقّق من سجلات الـ collector:

docker exec <container> cat /var/log/otel-collector.log | grep -i error
# Look for config parsing errors - early supervisor.opamp-client can be ignored 
# docker exec clickstack cat /var/log/otel-collector.log | grep -i error

أخطاء المصادقة

إذا ظهرت أخطاء مصادقة في السجلات، فتحقق من مفتاح API الخاص بك.

مشكلات الاتصال بالشبكة

إذا تعذّر على ClickStack الوصول إلى Temporal Cloud، فتأكّد من أن ملف Docker Compose أو أوامر docker run تسمح بالاتصال الخارجي عبر الشبكة.

الخطوات التالية

أعدّ التنبيهات للمقاييس المهمة (معدلات فشل سير العمل، تزايد تراكم المهام، زمن الانتقال من الجدولة إلى البدء)
أنشئ لوحات معلومات إضافية لحالات استخدام محددة (المراقبة على مستوى مساحة الاسم، وأداء أنواع سير العمل)
راقب عدة حسابات Temporal Cloud من خلال تكرار تهيئة المستقبِل باستخدام نقاط نهاية وأسماء خدمات مختلفة

الانتقال إلى بيئة الإنتاج

يستفيد هذا الدليل من OpenTelemetry Collector المضمّن في ClickStack لتوفير إعداد سريع. بالنسبة إلى عمليات النشر في بيئة الإنتاج، نوصي بتشغيل OTel Collector الخاص بك وإرسال البيانات إلى نقطة نهاية OTLP الخاصة بـ ClickStack. راجع إرسال بيانات OpenTelemetry للاطلاع على إعدادات الإنتاج.

​التكامل مع Temporal Cloud القائم

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

​إنشاء مفتاح Temporal Cloud

​أنشئ تهيئة مخصصة لـ OTel collector

​تهيئة ClickStack لتحميل إعدادات مخصصة

الخيار 1: Docker Compose

الخيار 2: تشغيل Docker (docker run) (الصورة المتكاملة)

​تحقّق من المقاييس في HyperDX

​لوحات المعلومات والتصورات المرئية

​ ملف إعداد لوحة المعلومات

​استيراد لوحة المعلومات المُعدّة مسبقًا

​عرض لوحة المعلومات

​استكشاف الأخطاء وإصلاحها

​عدم تحميل ملف الإعدادات المخصّص

​عدم ظهور أي مقاييس في HyperDX

​أخطاء المصادقة

​مشكلات الاتصال بالشبكة

​الخطوات التالية

​الانتقال إلى بيئة الإنتاج

التكامل مع Temporal Cloud القائم

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

إنشاء مفتاح Temporal Cloud

أنشئ تهيئة مخصصة لـ OTel collector

تهيئة ClickStack لتحميل إعدادات مخصصة

الخيار 2: تشغيل Docker (`docker run`) (الصورة المتكاملة)

تحقّق من المقاييس في HyperDX

لوحات المعلومات والتصورات المرئية

ملف إعداد لوحة المعلومات

استيراد لوحة المعلومات المُعدّة مسبقًا

عرض لوحة المعلومات

استكشاف الأخطاء وإصلاحها

عدم تحميل ملف الإعدادات المخصّص

عدم ظهور أي مقاييس في HyperDX

أخطاء المصادقة

مشكلات الاتصال بالشبكة

الخطوات التالية

الانتقال إلى بيئة الإنتاج