مراقبة سجلات Nginx باستخدام ClickStack

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

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

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

مثيل ClickStack قيد التشغيل
تثبيت حالي لـ Nginx
صلاحية تعديل ملفات تهيئة Nginx

إعداد تنسيق سجلات Nginx

أولًا، اضبط Nginx لإخراج السجلات بتنسيق JSON لتسهيل تحليلها. أضف تعريف تنسيق السجلات هذا إلى ملف nginx.conf:

يوجد ملف nginx.conf عادةً في:

Linux (apt/yum): /etc/nginx/nginx.conf
macOS (Homebrew): /usr/local/etc/nginx/nginx.conf أو /opt/homebrew/etc/nginx/nginx.conf
Docker: عادةً ما يُركَّب ملف الإعدادات كـ volume

أضف تعريف تنسيق السجلات هذا إلى كتلة http:

http {
    log_format json_combined escape=json
    '{'
      '"time_local":"$time_local",'
      '"remote_addr":"$remote_addr",'
      '"request_method":"$request_method",'
      '"request_uri":"$request_uri",'
      '"status":$status,'
      '"body_bytes_sent":$body_bytes_sent,'
      '"request_time":$request_time,'
      '"upstream_response_time":"$upstream_response_time",'
      '"http_referer":"$http_referer",'
      '"http_user_agent":"$http_user_agent"'
    '}';

    access_log /var/log/nginx/access.log json_combined;
    error_log /var/log/nginx/error.log warn;
}

بعد إجراء هذا التغيير، أعد تحميل Nginx.

أنشئ إعدادًا مخصصًا لـ OTel collector

يتيح لك ClickStack توسيع الإعداد الأساسي لـ OpenTelemetry Collector من خلال إرفاق ملف إعداد مخصص وتعيين متغير بيئة. ويُدمج هذا الإعداد المخصص مع الإعداد الأساسي الذي يديره HyperDX عبر OpAMP.

أنشئ ملفًا باسم nginx-monitoring.yaml بالمحتوى التالي:

receivers:
  filelog:
    include:
      - /var/log/nginx/access.log
      - /var/log/nginx/error.log
    start_at: end 
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx"

service:
  pipelines:
    logs/nginx:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

هذا التكوين:

يقرأ سجلات Nginx من مواقعها القياسية
يحلّل إدخالات السجل بتنسيق JSON
يستخرج الطوابع الزمنية الأصلية للسجل ويحافظ عليها
يضيف السمة source: Nginx لتسهيل التصفية في HyperDX
يوجّه السجلات إلى مُصدِّر ClickHouse عبر مسار معالجة مخصّص

هيّئ ClickStack لتحميل تهيئة مخصصة

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

تركيب ملف التهيئة المخصص في ‎/etc/otelcol-contrib/custom.config.yaml
تعيين متغير البيئة CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
تركيب أدلة سجلات Nginx لكي يتمكن المجمّع من قراءتها

الخيار 1: Docker Compose

حدّث تهيئة نشر ClickStack لديك:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... other volumes ...

الخيار 2: 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)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/nginx:/var/log/nginx:ro \
  clickhouse/clickstack-all-in-one:latest

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

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

انتقل إلى Search view
عيّن source إلى Logs، وتحقق من ظهور إدخالات السجل مع حقول مثل request وrequest_time وupstream_response_time وما إلى ذلك.

هذا مثال لما ينبغي أن تراه:

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

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

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

# نزّل السجلات
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

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

إدخالات سجلات بأنماط حركة مرور واقعية
نقاط نهاية وطرائق HTTP متنوعة
مزيجًا من الطلبات الناجحة والأخطاء
أزمنة استجابة وأعداد بايتات واقعية

أنشئ تهيئة مجمّع الاختبار

أنشئ ملفًا باسم nginx-demo.yaml بالمحتوى التالي:

cat > nginx-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/nginx-demo/access.log
    start_at: beginning  # اقرأ من البداية لبيانات العرض التجريبي
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx-demo"

service:
  pipelines:
    logs/nginx-demo:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

شغّل ClickStack باستخدام تهيئة العرض التجريبي

شغّل ClickStack باستخدام سجلات العرض التجريبي وهذه التهيئة:

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

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

بمجرد تشغيل ClickStack:

افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
انتقل إلى عرض Search واضبط المصدر على Logs
اضبط النطاق الزمني على 2025-10-19 11:00:00 - 2025-10-22 11:00:00

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

لوحات المعلومات والتصورات

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

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

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

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

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

ارفع ملف nginx-logs-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

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

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

عدم ظهور السجلات في HyperDX

تأكد من أن nginx يكتب السجلات بصيغة JSON

tail -f /var/log/nginx/access.log

تحقّق من أن المُجمِّع يمكنه قراءة السجلات

docker exec `<container>` cat /var/log/nginx/access.log

تحقّق من أن التهيئة الفعلية تتضمن مستقبِل filelog

docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog

راجِع سجلات المجمِّع بحثًا عن أخطاء

docker exec `<container>` cat /etc/otel/supervisor-data/agent.log

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

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

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

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