مراقبة تتبعات Nginx عبر ClickStack

مراقبة تتبعات Nginx عبر ClickStack

باختصار

التقط التتبعات الموزعة من Nginx في ClickStack باستخدام وحدة OpenTelemetry لـ Nginx. يتضمن مجموعة بيانات تجريبية ولوحة معلومات جاهزة.

​

التكامل مع Nginx الحالي

يتناول هذا القسم كيفية إضافة التتبّع الموزّع إلى تثبيت Nginx الحالي لديك، وذلك عبر تثبيت وحدة OpenTelemetry وتهيئتها لإرسال التتبعات إلى ClickStack. إذا كنت ترغب في اختبار هذا التكامل قبل تهيئة إعدادك الحالي، فيمكنك استخدام إعدادنا المهيّأ مسبقًا والبيانات النموذجية في القسم التالي.

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

• مثيل ClickStack قيد التشغيل مع إمكانية الوصول إلى نقاط نهاية OTLP (المنافذ 4317/4318)
• تثبيت Nginx مسبقًا (الإصدار 1.18 أو أحدث)
• صلاحيات root أو sudo لتعديل إعدادات Nginx
• اسم المضيف أو عنوان IP الخاص بـ ClickStack

1. ​

   تثبيت وحدة OpenTelemetry لـ Nginx

   أسهل طريقة لإضافة التتبّع إلى Nginx هي استخدام صورة Nginx الرسمية التي تتضمن دعم OpenTelemetry بشكل مدمج.

   استخدام الصورة nginx:otel

   استبدل صورة Nginx الحالية بالإصدار المفعّل لـ OpenTelemetry:

   # في ملف docker-compose.yml أو Dockerfile
   image: nginx:1.27-otel
   

   تتضمن هذه الصورة ngx_otel_module.so مثبتًا مسبقًا وجاهزًا للاستخدام.

   إذا كنت تشغّل Nginx خارج Docker، فارجع إلى توثيق OpenTelemetry Nginx للحصول على تعليمات التثبيت اليدوي.

2. ​

   إعداد Nginx لإرسال التتبعات إلى ClickStack

   أضف إعدادات OpenTelemetry إلى ملف nginx.conf. تُحمّل هذه الإعدادات الوحدة وتوجّه التتبعات إلى نقطة نهاية OTLP الخاصة بـ ClickStack.

   أولًا، احصل على مفتاح API الخاص بك:

   1. افتح HyperDX على عنوان URL الخاص بـ ClickStack
   2. انتقل إلى Settings → API Keys
   3. انسخ Ingestion API Key الخاصة بك
   4. عيّنها كمتغير بيئة: export CLICKSTACK_API_KEY=your-api-key-here

   أضف ما يلي إلى nginx.conf:

   load_module modules/ngx_otel_module.so;
   
   events {
       worker_connections 1024;
   }
   
   http {
       # إعداد exporter الخاص بـ OpenTelemetry
       otel_exporter {
           endpoint <clickstack-host>:4317;
           header authorization ${CLICKSTACK_API_KEY};
       }
       
       # اسم الخدمة للتعرّف على مثيل Nginx هذا
       otel_service_name "nginx-proxy";
       
       # تمكين التتبّع
       otel_trace on;
       
       server {
           listen 80;
           
           location / {
               # تمكين التتبّع لهذا المسار
               otel_trace_context propagate;
               otel_span_name "$request_method $uri";
               
               # إضافة تفاصيل الطلب إلى التتبعات
               otel_span_attr http.status_code $status;
               otel_span_attr http.request.method $request_method;
               otel_span_attr http.route $uri;
               
               # إعداد الوكيل أو التطبيق الحالي لديك
               proxy_pass http://your-backend;
           }
       }
   }
   

   إذا كنت تشغّل Nginx داخل Docker، فمرّر متغير البيئة إلى الحاوية:

   services:
     nginx:
       image: nginx:1.27-otel
       environment:
         - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
       volumes:
         - ./nginx.conf:/etc/nginx/nginx.conf:ro
   

   استبدل <clickstack-host> باسم المضيف أو عنوان IP الخاص بمثيل ClickStack لديك.

   • المنفذ 4317 هو نقطة نهاية gRPC التي تستخدمها وحدة Nginx
   • يجب أن يكون otel_service_name اسمًا وصفيًا لمثيل Nginx لديك (مثل “api-gateway” أو “frontend-proxy”)
   • غيّر otel_service_name ليتوافق مع بيئتك لتسهيل التعرف عليه داخل HyperDX

   فهم الإعدادات

   ما الذي يتم تتبّعه: ينشئ كل طلب إلى Nginx trace span يوضّح:

   • طريقة الطلب والمسار
   • رمز حالة HTTP
   • مدة الطلب
   • الطابع الزمني

   سمات span: تضيف توجيهات otel_span_attr بيانات وصفية إلى كل trace، ما يتيح لك تصفية الطلبات وتحليلها في HyperDX حسب رمز الحالة والطريقة والمسار وغير ذلك.

   بعد إجراء هذه التغييرات، اختبر إعداد Nginx:

   nginx -t
   

   إذا نجح الاختبار، فأعد تحميل Nginx:

   # لـ Docker
   docker-compose restart nginx
   
   # لـ systemd
   sudo systemctl reload nginx
   
3. ​

   التحقق من التتبعات في HyperDX

   بعد إتمام الإعداد، سجّل الدخول إلى HyperDX وتحقق من تدفّق التتبعات. من المفترض أن ترى شيئًا مشابهًا لما يلي. وإذا لم تظهر أي تتبعات، فجرّب تعديل النطاق الزمني:

​

مجموعة بيانات تجريبية

للمستخدمين الذين يريدون اختبار تكامل تتبعات nginx قبل تهيئة أنظمتهم الإنتاجية، نوفر مجموعة بيانات نموذجية لتتبعات Nginx مُولَّدة مسبقًا بأنماط حركة مرور واقعية.

1. ​

   ابدأ ClickStack

   إذا لم يكن ClickStack قيد التشغيل لديك بعد، فابدأه باستخدام:

   docker run --name clickstack-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   

   انتظر حوالي 30 ثانية حتى يكتمل تشغيل ClickStack وتهيئته قبل المتابعة.

   • المنفذ 8080: واجهة HyperDX على الويب
   • المنفذ 4317: نقطة نهاية OTLP gRPC (تستخدمها وحدة nginx)
   • المنفذ 4318: نقطة نهاية OTLP HTTP (تُستخدم للتتبعات التجريبية)
2. ​

   نزّل مجموعة البيانات النموذجية

   نزّل ملف التتبعات النموذجي وحدّث الطوابع الزمنية إلى الوقت الحالي:

   # نزّل التتبعات
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nginx-traces-sample.json
   

   تتضمن مجموعة البيانات:

   • 1,000 span تتبع بتوقيتات واقعية
   • 9 نقاط نهاية مختلفة مع أنماط حركة مرور متنوعة
   • معدل نجاح ~93%‏ (200)، وأخطاء عميل ~3%‏ (404)، وأخطاء خادم ~4%‏ (500)
   • أزمنة استجابة تتراوح من 10ms إلى 800ms
   • الحفاظ على أنماط حركة المرور الأصلية مع ترحيلها إلى الوقت الحالي
3. ​

   أرسل التتبعات إلى ClickStack

   اضبط مفتاح API الخاص بك كمتغير بيئة (إذا لم يكن مضبوطًا بالفعل):

   export CLICKSTACK_API_KEY=your-api-key-here
   

   احصل على مفتاح API الخاص بك:

   1. افتح HyperDX على عنوان URL الخاص بـ ClickStack
   2. انتقل إلى Settings → API Keys
   3. انسخ Ingestion API Key الخاص بك

   ثم أرسل التتبعات إلى ClickStack:

   curl -X POST http://localhost:4318/v1/traces \
     -H "Content-Type: application/json" \
     -H "Authorization: $CLICKSTACK_API_KEY" \
     -d @nginx-traces-sample.json
   

   التشغيل على localhost

   يفترض هذا العرض التجريبي أن ClickStack يعمل محليًا على localhost:4318. بالنسبة إلى المثيلات البعيدة، استبدل localhost باسم المضيف الخاص بـ ClickStack.

   يجب أن ترى استجابة مثل {"partialSuccess":{}}، ما يشير إلى أنه تم إرسال التتبعات بنجاح. وسيتم إدخال جميع التتبعات البالغ عددها 1,000 إلى ClickStack.

4. ​

   تحقّق من التتبعات في HyperDX

   1. افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
   2. انتقل إلى عرض Search واضبط المصدر على Traces
   3. اضبط النطاق الزمني على 2025-10-25 13:00:00 - 2025-10-28 13:00:00

   إليك ما ينبغي أن تراه في عرض Search لديك:

   عرض المنطقة الزمنية

   يعرض HyperDX الطوابع الزمنية وفقًا للمنطقة الزمنية المحلية في متصفحك. تمتد البيانات التجريبية عبر 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC). ويضمن النطاق الزمني الواسع ظهور التتبعات التجريبية لك بغض النظر عن موقعك. وبعد ظهور التتبعات، يمكنك تضييق النطاق إلى فترة 24 ساعة للحصول على تصورات أوضح.

​

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

لمساعدتك على بدء مراقبة التتبعات باستخدام ClickStack، نوفر مرئيات أساسية لبيانات التتبّع.

1. ​

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

2. ​

   استيراد لوحة المعلومات الجاهزة مسبقًا

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

   3. ارفع ملف nginx-trace-dashboard.json ثم انقر على إتمام الاستيراد.
3. ​

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

   بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) (عدّله وفقًا لمنطقتك الزمنية المحلية). لن تتضمن لوحة المعلومات المستوردة نطاقًا زمنيًا محددًا افتراضيًا.

​

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

​

عدم ظهور أي تتبعات في HyperDX

تحقّق من أن وحدة nginx مُحمّلة:

nginx -V 2>&1 | grep otel

يجب أن ترى إشارات إلى وحدة OpenTelemetry.

تحقّق من الاتصال بالشبكة:

telnet <clickstack-host> 4317

يُفترض أن يتصل هذا بنجاح بنقطة نهاية OTLP gRPC.

تأكّد من ضبط مفتاح API:

echo $CLICKSTACK_API_KEY

يجب أن يظهر مفتاح API الخاص بك (وألا يكون فارغًا).

تحقّق من سجلات أخطاء nginx:

# For Docker
docker logs <nginx-container> 2>&1 | grep -i otel

# For systemd
sudo tail -f /var/log/nginx/error.log | grep -i otel

ابحث عن الأخطاء المتعلقة بـOpenTelemetry.

تحقّق من أن nginx يستقبل الطلبات:

# Check access logs to confirm traffic
tail -f /var/log/nginx/access.log

​

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

• قم بإعداد التنبيهات للمقاييس المهمة (معدلات الخطأ، عتبات زمن الاستجابة)
• أنشئ لوحات معلومات إضافية لحالات استخدام محددة (مراقبة واجهات API، أحداث الأمان)

​

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

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