> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **باختصار**

  اجمع سجلات وصول Nginx (بتنسيق JSON) واعرضها بصريًا في ClickStack باستخدام مستقبل `filelog` من OTel. يتضمن مجموعة بيانات تجريبية ولوحة معلومات مُعدّة مسبقًا.
</Info>

<div id="existing-nginx">
  ## التكامل مع Nginx الحالي
</div>

يتناول هذا القسم كيفية تهيئة تثبيت Nginx الحالي لديك لإرسال السجلات إلى ClickStack من خلال تعديل إعدادات ClickStack OTel مجمّع.
إذا كنت ترغب في اختبار التكامل قبل تهيئة إعدادك الحالي، فيمكنك الاختبار باستخدام الإعداد المهيأ مسبقًا لدينا والبيانات النموذجية في [القسم التالي](/ar/clickstack/integration-examples/nginx-logs#demo-dataset).

<div id="prerequisites">
  ##### المتطلبات الأساسية
</div>

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

<Steps>
  <Step>
    #### إعداد تنسيق سجلات 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`:

    ```nginx theme={null}
    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.
  </Step>

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

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

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

    ```yaml theme={null}
    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 عبر مسار معالجة مخصّص

    <Note>
      - ما عليك سوى تعريف المستقبِلات ومسارات المعالجة الجديدة في التكوين المخصّص
      - المعالِجات (memory\_limiter وtransform وbatch) والمُصدِّرات (clickhouse) معرّفة بالفعل في تكوين ClickStack الأساسي — ما عليك إلا الإشارة إليها بالاسم
      - يستخرج العامل time\_parser الطوابع الزمنية من الحقل time\_local في Nginx للحفاظ على التوقيت الأصلي للسجل
      - توجّه مسارات المعالجة البيانات من المستقبِلات لديك إلى مُصدِّر ClickHouse عبر المعالِجات الحالية
    </Note>
  </Step>

  <Step>
    #### هيّئ ClickStack لتحميل تهيئة مخصصة

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

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

    ##### الخيار 1: Docker Compose

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

    ```yaml theme={null}
    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:

    ```bash theme={null}
    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
    ```

    <Note>
      تأكد من أن مجمّع ClickStack لديه الأذونات المناسبة لقراءة ملفات سجلات nginx. في بيئة الإنتاج، استخدم نقاط ربط للقراءة فقط (:ro) واتبع مبدأ الحد الأدنى من الامتيازات.
    </Note>
  </Step>

  <Step>
    #### التحقق من السجلات في HyperDX

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

    1. انتقل إلى Search view
    2. عيّن source إلى Logs، وتحقق من ظهور إدخالات السجل مع حقول مثل request وrequest\_time وupstream\_response\_time وما إلى ذلك.

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/nginx-logs-search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=46a5c2073fe905518ead24c78cbf704e" alt="عرض السجل" width="3838" height="1938" data-path="images/clickstack/nginx-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=ff95d3429beae00493bc595ad1fe7d72" alt="عرض السجل" width="3838" height="1934" data-path="images/clickstack/log-view.png" />
  </Step>
</Steps>

<div id="demo-dataset">
  ## مجموعة البيانات التجريبية
</div>

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

<Steps>
  <Step>
    #### نزّل مجموعة البيانات التجريبية

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

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

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

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

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

    ```yaml theme={null}
    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
    ```
  </Step>

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

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

    ```bash theme={null}
    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
    ```
  </Step>

  <Step>
    #### تحقّق من السجلات في HyperDX

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

    1. افتح [HyperDX](http://localhost:8080/) وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
    2. انتقل إلى عرض Search واضبط المصدر على `Logs`
    3. اضبط النطاق الزمني على **2025-10-19 11:00:00 - 2025-10-22 11:00:00**

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

    <Info>
      **عرض المنطقة الزمنية**

      يعرض HyperDX الطوابع الزمنية وفقًا للمنطقة الزمنية المحلية في متصفحك. تمتد البيانات التجريبية عبر الفترة 2025-10-20 11:00:00 - 2025-10-21 11:00:00 UTC. يضمن النطاق الزمني الواسع ظهور سجلات العرض التجريبي بغض النظر عن موقعك. وبعد ظهور السجلات، يمكنك تضييق النطاق إلى فترة 24 ساعة للحصول على تصورات أوضح.
    </Info>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/nginx-logs-search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=46a5c2073fe905518ead24c78cbf704e" alt="عرض السجلات" width="3838" height="1938" data-path="images/clickstack/nginx-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=ff95d3429beae00493bc595ad1fe7d72" alt="عرض السجلات" width="3838" height="1934" data-path="images/clickstack/log-view.png" />
  </Step>
</Steps>

<div id="dashboards">
  ## لوحات المعلومات والتصورات
</div>

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

<Steps>
  <Step>
    #### <TrackedLink href={'/ar/examples/nginx-logs-dashboard.json'} download="nginx-logs-dashboard.json" eventName="docs.nginx_logs_monitoring.dashboard_download">تنزيل</TrackedLink> إعداد لوحة المعلومات
  </Step>

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/import-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=21af53f2ddc48534745ebc3f01de39ef" alt="استيراد لوحة المعلومات" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. ارفع ملف nginx-logs-dashboard.json ثم انقر على Finish Import.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/finish-nginx-logs-import.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=1c22eb77b620b40fbc79d7cd1cb2390b" alt="إنهاء الاستيراد" width="3812" height="1906" data-path="images/clickstack/finish-nginx-logs-import.png" />
  </Step>

  <Step>
    #### ستُنشأ لوحة المعلومات مع تهيئة جميع المرئيات مسبقًا

    <Note>
      بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على **2025-10-20 11:00:00 - 2025-10-21 11:00:00 (UTC)** (مع تعديله وفقًا لمنطقتك الزمنية المحلية). لن تتضمن لوحة المعلومات المستوردة نطاقًا زمنيًا محددًا بشكل افتراضي.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/nginx-logs-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=fbed0bec6842853ffaaf13e65a062741" alt="لوحة معلومات نموذجية" width="3812" height="1906" data-path="images/clickstack/nginx-logs-dashboard.png" />
  </Step>
</Steps>

<div id="troubleshooting">
  ## استكشاف الأخطاء وإصلاحها
</div>

<div id="troubleshooting-not-loading">
  ### عدم تحميل الإعدادات المخصّصة
</div>

* تحقّق من ضبط متغير البيئة CUSTOM\_OTELCOL\_CONFIG\_FILE بشكل صحيح

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

* تحقّق من أن ملف الإعدادات المخصّص مُثبّت في /etc/otelcol-contrib/custom.config.yaml

```bash theme={null}
docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
```

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

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
```

<div id="no-logs">
  ### عدم ظهور السجلات في HyperDX
</div>

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

```bash theme={null}
tail -f /var/log/nginx/access.log
```

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

```bash theme={null}
docker exec `<container>` cat /var/log/nginx/access.log
```

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

```bash theme={null}
docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog
```

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

```bash theme={null}
docker exec `<container>` cat /etc/otel/supervisor-data/agent.log
```

<div id="next-steps">
  ## الخطوات التالية
</div>

* أعدّ [التنبيهات](/ar/clickstack/features/alerts) للمقاييس الحرجة (معدلات الخطأ، عتبات زمن الاستجابة)
* أنشئ [لوحات معلومات](/ar/clickstack/features/dashboards/overview) إضافية لحالات استخدام محددة (مراقبة واجهات برمجة التطبيقات، أحداث الأمان)

<div id="going-to-production">
  ## الانتقال إلى بيئة الإنتاج
</div>

يبني هذا الدليل على OpenTelemetry Collector المضمّن في ClickStack لتوفير إعداد سريع. أما لعمليات النشر في بيئة الإنتاج، فنوصي بتشغيل OTel Collector الخاص بك وإرسال البيانات إلى نقطة نهاية OTLP الخاصة بـ ClickStack. راجع [إرسال بيانات OpenTelemetry](/ar/clickstack/ingesting-data/opentelemetry) للاطّلاع على إعدادات بيئة الإنتاج.