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

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

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

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

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

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

أضف إعدادات 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 لديك.

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

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

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

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

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

nginx -t

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

# لـ Docker
docker-compose restart nginx

# لـ systemd
sudo systemctl reload nginx

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

إذا لم يكن 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 (تُستخدم للتتبعات التجريبية)

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

# نزّل التتبعات
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
• الحفاظ على أنماط حركة المرور الأصلية مع ترحيلها إلى الوقت الحالي

اضبط مفتاح 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

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

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

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

تنزيل ملف إعداد لوحة المعلومات.

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

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