إدخال البيانات باستخدام Vector

إدخال البيانات باستخدام Vector لـ ClickStack - حزمة observability من ClickHouse

يُعد Vector خط أنابيب عالي الأداء ومحايدًا تجاه المورّدين لبيانات observability. ويُستخدم على نطاق واسع لجمع السجلات والمقاييس وتحويلها وتوجيهها من مجموعة كبيرة من المصادر، ويتميّز بشعبية خاصة في استيعاب السجلات بفضل مرونته وانخفاض استهلاكه للموارد.

عند استخدام Vector مع ClickStack، يكون المستخدمون مسؤولين عن تحديد المخططات الخاصة بهم. وقد تتبع هذه المخططات اصطلاحات OpenTelemetry، لكنها قد تكون أيضًا مخصّصة بالكامل لتمثيل بُنى أحداث يحددها المستخدم. وعمليًا، يُستخدم استيعاب البيانات عبر Vector غالبًا مع السجلات، عندما يرغب المستخدمون في تحكم كامل في التحليل والإثراء قبل كتابة البيانات إلى ClickHouse.

يركّز هذا الدليل على إدخال البيانات إلى ClickStack باستخدام Vector لكلٍّ من ClickStack Open Source وManaged ClickStack. وللتبسيط، لا يتناول الدليل مصادر Vector أو إعدادات خط الأنابيب بالتفصيل. وبدلًا من ذلك، يركّز على تهيئة الوجهة التي تكتب البيانات إلى ClickHouse، والتأكد من أن المخطط الناتج متوافق مع ClickStack.

المتطلب الصارم الوحيد في ClickStack، سواء عند استخدام النشر مفتوح المصدر أو النشر المُدار، هو أن تتضمن البيانات عمود طابع زمني (أو حقل وقت مكافئ)، ويمكن تحديده عند تهيئة مصدر البيانات في واجهة مستخدم ClickStack.

​

إرسال البيانات عبر Vector

ClickStack المُدار

يفترض هذا الدليل أنك أنشأت بالفعل خدمة Managed ClickStack ودوّنت بيانات اعتماد الخدمة. إن لم تكن قد فعلت ذلك، اتّبع دليل البدء الخاص بـ Managed ClickStack حتى تصل إلى خطوة ضبط إعدادات Vector.

1. ​

   أنشئ قاعدة بيانات وجدولًا

   يتطلب Vector تعريف جدول ومخطط قبل بدء استيعاب البيانات.

   أنشئ أولًا قاعدة بيانات. ويمكن القيام بذلك عبر ClickHouse Cloud console.

   في المثال أدناه، نستخدم logs:

   CREATE DATABASE IF NOT EXISTS logs
   

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

   CREATE TABLE logs.nginx_logs
   (
       `time_local` DateTime,
       `remote_addr` IPv4,
       `remote_user` LowCardinality(String),
       `request` String,
       `status` UInt16,
       `body_bytes_sent` UInt64,
       `http_referer` String,
       `http_user_agent` String,
       `http_x_forwarded_for` LowCardinality(String),
       `request_time` Float32,
       `upstream_response_time` Float32,
       `http_host` String
   )
   ENGINE = MergeTree
   ORDER BY (toStartOfMinute(time_local), status, remote_addr)
   

   المفتاح الأساسي لـ Nginx

   يفترض المفتاح الأساسي أعلاه أنماط الوصول المعتادة في واجهة ClickStack لسجلات Nginx، لكن قد يلزم تعديله بحسب حمل العمل لديك في بيئات الإنتاج.

2. ​

   أضِف وجهة ClickHouse إلى إعدادات Vector

   عدّل إعدادات Vector لتشمل وجهة ClickHouse، مع تحديث الحقل inputs لاستقبال الأحداث من خطوط المعالجة الحالية لديك.

   يفترض هذا الإعداد أن خط المعالجة السابق في Vector لديك قد هيّأ البيانات بالفعل لتتوافق مع مخطط ClickHouse المستهدف، أي إن الحقول قد تم تحليلها وتسميتها بشكل صحيح وتحديد أنواعها بما يناسب الإدراج. راجع مثال Nginx أدناه للاطلاع على شرح كامل لكيفية تحليل أسطر السجل الخام وتطبيعها إلى مخطط مناسب لـ ClickStack.

   sinks:
     clickhouse:
       type: clickhouse
       inputs:
         - your_input
       endpoint: "<CLICKHOUSE_ENDPOINT>"
       database: logs
       format: json_each_row
       table: nginx_logs
       skip_unknown_fields: true
       auth:
         strategy: "basic"
         user: "default"
         password: "<CLICKHOUSE_PASSWORD>"
   

   افتراضيًا، نوصي باستخدام تنسيق json_each_row، الذي يرمّز كل حدث باعتباره كائن JSON واحدًا لكل صف. وهذا هو التنسيق الافتراضي والموصى به في ClickStack عند استيعاب بيانات JSON، ويُفضَّل على التنسيقات البديلة مثل كائنات JSON المرمّزة كسلاسل نصية.

   كما تدعم وجهة ClickHouse أيضًا ترميز Arrow stream (وهو حاليًا في مرحلة تجريبية). وقد يوفّر هذا معدل نقل أعلى، لكنه يفرض قيودًا مهمة: يجب أن تكون قاعدة البيانات والجدول ثابتين، لأن المخطط يُجلَب مرة واحدة فقط عند بدء التشغيل، كما أن التوجيه الديناميكي غير مدعوم. لذلك، يُعد ترميز Arrow الأنسب لخطوط استيعاب ثابتة ومحددة بوضوح.

   نوصي بمراجعة خيارات تهيئة الوجهة المتاحة في توثيق Vector:

   يستخدم المثال أعلاه المستخدم default في Managed ClickStack. أما في عمليات النشر على بيئة الإنتاج، فنوصي بإنشاء مستخدم استيعاب مخصص مع الأذونات والحدود المناسبة.

3. ​

   الانتقال إلى واجهة ClickStack

   انتقل إلى خدمة Managed ClickStack الخاصة بك، ثم اختر “ClickStack” من القائمة الجانبية اليسرى. إذا كنت قد أكملت الإعداد الأولي بالفعل، فسيؤدي ذلك إلى فتح واجهة ClickStack في علامة تبويب جديدة، وستتم مصادقتك تلقائيًا. وإذا لم تكن قد أكملت ذلك بعد، يمكنك متابعة الإعداد الأولي واختيار “Launch ClickStack” بعد تحديد Vector كمصدر للإدخال.

4. ​

   إنشاء مصدر بيانات

   أنشئ مصدر بيانات للسجلات. إذا لم تكن هناك أي مصادر بيانات، فسيُطلب منك إنشاء واحد عند تسجيل الدخول لأول مرة. وإلا، فانتقل إلى إعدادات الفريق وأضف مصدر بيانات جديدًا.

   يفترض هذا التكوين أعلاه مخططًا بأسلوب Nginx، مع استخدام العمود time_local كطابع زمني. وينبغي، حيثما أمكن، أن يكون هذا هو عمود الطابع الزمني المعرَّف في المفتاح الأساسي. هذا العمود مطلوب.

   كما نوصي بتحديث Default SELECT لتحديد الأعمدة التي تُعرَض في عرض السجلات بشكل صريح. وإذا كانت هناك حقول إضافية متاحة، مثل اسم الخدمة أو مستوى السجل أو عمود Body، فيمكن أيضًا تهيئتها. ويمكن كذلك تجاوز عمود عرض الطابع الزمني إذا كان مختلفًا عن العمود المستخدم في المفتاح الأساسي للجدول والمُهيأ أعلاه.

   في المثال أعلاه، لا يحتوي البيانات على عمود Body. وبدلًا من ذلك، يُعرَّف باستخدام تعبير SQL يعيد تكوين سطر سجل Nginx من الحقول المتاحة.

   لخيارات أخرى ممكنة، راجع مرجع التكوين.

5. ​

   استكشاف البيانات

   انتقل إلى عرض السجلات لاستكشاف البيانات والبدء في استخدام ClickStack.

ClickStack مفتوح المصدر

1. ​

   أنشئ قاعدة بيانات وجدولًا

   يتطلب Vector تعريف جدول ومخطط مسبقًا قبل إدخال البيانات.

   أنشئ أولًا قاعدة بيانات. يمكن القيام بذلك عبر واجهة مستخدم ClickHouse على الويب على http://localhost:8123/play. استخدم اسم المستخدم وكلمة المرور الافتراضيين api:api.

   في المثال أدناه، نستخدم logs:

   CREATE DATABASE IF NOT EXISTS logs
   

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

   CREATE TABLE logs.nginx_logs
   (
       `time_local` DateTime,
       `remote_addr` IPv4,
       `remote_user` LowCardinality(String),
       `request` String,
       `status` UInt16,
       `body_bytes_sent` UInt64,
       `http_referer` String,
       `http_user_agent` String,
       `http_x_forwarded_for` LowCardinality(String),
       `request_time` Float32,
       `upstream_response_time` Float32,
       `http_host` String
   )
   ENGINE = MergeTree
   ORDER BY (toStartOfMinute(time_local), status, remote_addr)
   

   المفتاح الأساسي لـ Nginx

   يفترض المفتاح الأساسي أعلاه أنماط الوصول المعتادة في واجهة ClickStack لسجلات Nginx، لكنه قد يحتاج إلى تعديل وفقًا لحمل العمل لديك في بيئات الإنتاج.

2. ​

   أضِف وجهة ClickHouse إلى إعدادات Vector

   يجب أن يتم إدخال البيانات إلى ClickStack عبر Vector مباشرةً إلى ClickHouse، مع تجاوز نقطة نهاية OTLP التي يوفّرها المجمّع.

   عدّل إعدادات Vector لتضمين وجهة ClickHouse، مع تحديث الحقل inputs لاستقبال الأحداث من مسارات المعالجة الحالية.

   يفترض هذا الإعداد أن مسار Vector المصدر لديك قد جهّز البيانات بالفعل لتتوافق مع مخطط ClickHouse المستهدف، أي إن الحقول قد تم تحليلها، وتسميتها بشكل صحيح، وتحديد أنواعها بما يلائم الإدراج. راجع مثال Nginx أدناه للاطلاع على توضيح كامل لكيفية تحليل أسطر السجل الخام وتطبيعها إلى مخطط مناسب لـ ClickStack.

   sinks:
     clickhouse:
       type: clickhouse
       inputs:
         - your_input
       endpoint: "http://localhost:8123"
       database: logs
       format: json_each_row
       table: nginx_logs
       skip_unknown_fields: true
       auth:
         strategy: "basic"
         user: "api"
         password: "api"
   

   افتراضيًا، نوصي باستخدام التنسيق json_each_row، الذي يرمّز كل حدث ككائن JSON واحد لكل صف. هذا هو التنسيق الافتراضي والموصى به في ClickStack عند إدخال بيانات JSON، ويجب تفضيله على التنسيقات البديلة مثل كائنات JSON المُرمَّزة كسلاسل نصية.

   يدعم مصب ClickHouse أيضًا ترميز Arrow stream (وهو حاليًا في مرحلة بيتا). قد يوفّر هذا معدل نقل أعلى، لكنه يأتي مع قيود مهمة: يجب أن تكون قاعدة البيانات والجدول ثابتين، لأن المخطط يُجلب مرة واحدة عند بدء التشغيل، كما أن التوجيه الديناميكي غير مدعوم. لذلك، يُعد ترميز Arrow الأنسب لخطوط إدخال ثابتة ومحددة بوضوح.

   نوصي بمراجعة خيارات تهيئة المصب المتاحة في وثائق Vector:

   يستخدم المثال أعلاه المستخدم api في ClickStack Open Source. بالنسبة إلى عمليات النشر في بيئة الإنتاج، نوصي بإنشاء مستخدم إدخال مخصص مع الأذونات والحدود المناسبة. كما يفترض الإعداد أعلاه أن Vector يعمل على نفس المضيف الذي يعمل عليه ClickStack. وفي عمليات النشر في بيئة الإنتاج، يُرجَّح أن يكون الأمر مختلفًا. ونوصي بإرسال البيانات عبر منفذ HTTPS الآمن 8443.

3. ​

   الانتقال إلى واجهة ClickStack

   انتقل إلى واجهة ClickStack على http://localhost:8080. أنشئ مستخدمًا إذا لم تكن قد أكملت خطوات الإعداد.

4. ​

   إنشاء مصدر بيانات

   انتقل إلى إعدادات الفريق وأضف مصدر بيانات جديدًا.

   تفترض الإعدادات أعلاه مخططًا على نمط Nginx، مع استخدام العمود time_local كطابع زمني. ويُفترض، متى أمكن، أن يكون هذا هو عمود الطابع الزمني المعرَّف في المفتاح الأساسي. هذا العمود إلزامي.

   نوصي أيضًا بتحديث Default SELECT لتحديد الأعمدة التي تُعرَض في عرض السجلات بشكل صريح. وإذا كانت هناك حقول إضافية متاحة، مثل اسم الخدمة أو مستوى السجل أو عمود body، فيمكن تهيئتها أيضًا. كما يمكن أيضًا تجاوز عمود عرض الطابع الزمني إذا كان مختلفًا عن العمود المستخدم في المفتاح الأساسي للجدول والمُحدَّد أعلاه.

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

   للاطلاع على خيارات أخرى، راجع مرجع الإعدادات.

5. ​

   استعرض البيانات

   انتقل إلى عرض السجلات لاستعراض البيانات وبدء استخدام ClickStack.

​

مجموعة بيانات تجريبية باستخدام Vector

للاطلاع على مثال أكثر اكتمالًا، نستخدم أدناه ملف سجلّات Nginx.

ClickStack المُدار

يفترض هذا الدليل أنك أنشأت بالفعل خدمة Managed ClickStack ودوّنت بيانات اعتماد الخدمة. إن لم تكن قد فعلت ذلك، اتّبع دليل البدء الخاص بـ Managed ClickStack حتى تصل إلى خطوة تهيئة Vector.

1. ​

   تثبيت Vector

   قبل المتابعة، تأكد من تثبيت Vector على النظام الذي تنوي تشغيل مسار إدخال البيانات عليه. اتبع دليل تثبيت Vector الرسمي لتثبيت ملف تنفيذي مُسبق البناء أو حزمة مناسبة لبيئتك:

   بعد التثبيت، تحقّق من أن الملف التنفيذي vector متاح في متغير PATH قبل متابعة خطوات الإعداد أدناه.

   يمكن تثبيت هذا على نفس المثيل الذي يعمل عليه ClickStack OTel collector.

   اتبع أفضل الممارسات المتعلقة بالبنية والأمان عند نقل Vector إلى بيئة الإنتاج.

2. ​

   نزّل عيّنة البيانات

   إذا كنت ترغب في تجربة مجموعة بيانات نموذجية، فنزّل عينة nginx التالية.

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
   

   جُمعت هذه البيانات من مثيل Nginx مُهيّأ لإخراج السجلات بتنسيق JSON لتسهيل تحليلها. للاطلاع على إعداد Nginx لهذه السجلات، راجع “مراقبة سجلات Nginx باستخدام ClickStack”.

3. ​

   أنشئ قاعدة بيانات وجدولًا

   يتطلب Vector تعريف جدول ومخطط قبل إدخال البيانات.

   أنشئ أولًا قاعدة بيانات. يمكن إجراء ذلك عبر ClickHouse Cloud console.

   أنشئ قاعدة بيانات logs:

   CREATE DATABASE IF NOT EXISTS logs
   

   أنشئ جدولًا لبياناتك.

   CREATE TABLE logs.nginx_logs
   (
       `time_local` DateTime,
       `remote_addr` IPv4,
       `remote_user` LowCardinality(String),
       `request` String,
       `status` UInt16,
       `body_bytes_sent` UInt64,
       `http_referer` String,
       `http_user_agent` String,
       `http_x_forwarded_for` LowCardinality(String),
       `request_time` Float32,
       `upstream_response_time` Float32,
       `http_host` String
   )
   ENGINE = MergeTree
   ORDER BY (toStartOfMinute(time_local), status, remote_addr)
   

   المفتاح الأساسي لـ Nginx

   يفترض المفتاح الأساسي المذكور أعلاه أنماط الوصول المعتادة في واجهة ClickStack لسجلات Nginx، لكنه قد يحتاج إلى تعديل وفقًا لحمل العمل لديك في بيئات الإنتاج.

4. ​

   انسخ تهيئة Vector

   انسخ تهيئة Vector وأنشئ ملفًا باسم nginx.yaml، مع ضبط CLICKHOUSE_ENDPOINT وCLICKHOUSE_PASSWORD.

   data_dir: ./.vector-data
   sources:
     nginx_logs:
       type: file
       include:
         - access.log
       read_from: beginning
   
   transforms:
     decode_json:
       type: remap
       inputs:
         - nginx_logs
       source: |
         . = parse_json!(to_string!(.message))
         ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
         # ClickHouse-friendly DateTime format
         .time_local = format_timestamp!(ts, format: "%F %T")
   
   sinks:
     clickhouse:
       type: clickhouse
       inputs:
         - decode_json
       endpoint: "<CLICKHOUSE_ENDPOINT>"
       database: logs
       format: json_each_row
       table: nginx_logs
       skip_unknown_fields: true
       auth:
         strategy: "basic"
         user: "default"
         password: "<CLICKHOUSE_PASSWORD>"
   

   يستخدم المثال أعلاه المستخدم default في Managed ClickStack. بالنسبة إلى عمليات النشر في بيئة الإنتاج، نوصي بإنشاء مستخدم مخصص للإدخال مع الأذونات والحدود المناسبة.

5. ​

   تشغيل Vector

   شغّل Vector بالأمر التالي، مع إنشاء دليل البيانات أولًا لتسجيل إزاحات الملف.

   mkdir ./.vector-data
   vector --config nginx.yaml
   
6. ​

   انتقل إلى واجهة مستخدم ClickStack

   انتقل إلى خدمة Managed ClickStack الخاصة بك وحدد “ClickStack” من القائمة الموجودة على الجانب الأيسر. إذا كنت قد أكملت بالفعل عملية التهيئة، فسيؤدي ذلك إلى فتح واجهة مستخدم ClickStack في علامة تبويب جديدة، وستتم مصادقتك تلقائيًا. وإذا لم تكن قد أكملت ذلك بعد، فيمكنك متابعة عملية التهيئة وتحديد “Launch ClickStack” بمجرد اختيار Vector كمصدر للإدخال.

7. ​

   إنشاء مصدر بيانات

   أنشئ مصدر بيانات للسجلات. إذا لم تكن هناك أي مصادر بيانات، فسيُطلب منك إنشاء واحد عند أول تسجيل دخول. بخلاف ذلك، انتقل إلى إعدادات الفريق وأضف مصدر بيانات جديدًا.

   يفترض هذا الإعداد مخطط Nginx مع استخدام العمود time_local كطابع زمني. وهذا هو عمود الطابع الزمني المصرَّح به في المفتاح الأساسي. هذا العمود إلزامي.

   لقد حدّدنا أيضًا عبارة SELECT الافتراضية لتكون time_local, remote_addr, status, request، ما يحدّد الأعمدة التي تُعرض في عرض السجلات.

   في المثال أعلاه، لا يوجد عمود Body في البيانات. وبدلًا من ذلك، يُعرَّف على أنه تعبير SQL:

   concat(
     remote_addr, ' ',
     remote_user, ' ',
     '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
     '"', request, '" ',
     toString(status), ' ',
     toString(body_bytes_sent), ' ',
     '"', http_referer, '" ',
     '"', http_user_agent, '" ',
     '"', http_x_forwarded_for, '" ',
     toString(request_time), ' ',
     toString(upstream_response_time), ' ',
     '"', http_host, '"'
   )
   

   يعيد هذا بناء سطر السجل من الحقول المنظَّمة.

   للاطلاع على الخيارات الأخرى المتاحة، راجع مرجع التهيئة.

8. ​

   استكشاف البيانات

   انتقل إلى عرض البحث ليوم October 20th, 2025 لاستكشاف البيانات وبدء استخدام ClickStack.

ClickStack مفتوح المصدر

يفترض هذا الدليل أنك أعددت ClickStack Open Source باتباع دليل البدء.

1. ​

   تثبيت Vector

   قبل المتابعة، تأكد من تثبيت Vector على النظام الذي تنوي تشغيل مسار إدخال البيانات عليه. اتبع دليل تثبيت Vector الرسمي لتثبيت ملف تنفيذي مُسبق البناء أو حزمة مناسبة لبيئتك:

   بعد التثبيت، تحقّق من أن الملف التنفيذي vector متاح في متغير PATH قبل متابعة خطوات الإعداد أدناه.

   يمكن تثبيت هذا على نفس المثيل الذي يعمل عليه ClickStack OTel collector.

   اتبع أفضل الممارسات المتعلقة بالبنية والأمان عند نقل Vector إلى بيئة الإنتاج.

2. ​

   نزّل بيانات العينة

   إذا كنت ترغب في تجربة مجموعة بيانات نموذجية، فنزّل عينة nginx التالية.

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
   

   جُمعت هذه البيانات من مثيل Nginx مُهيّأ لإخراج السجلات بتنسيق JSON لتسهيل تحليلها. للاطلاع على إعداد Nginx لهذه السجلات، راجع “مراقبة سجلات Nginx باستخدام ClickStack”.

3. ​

   أنشئ قاعدة بيانات وجدولًا

   يتطلب Vector تعريف جدول ومخطط مسبقًا قبل إدخال البيانات.

   أنشئ أولًا قاعدة بيانات. يمكن تنفيذ ذلك عبر واجهة الويب لـ ClickHouse على http://localhost:8123/play. استخدم اسم المستخدم وكلمة المرور الافتراضيين api:api.

   أنشئ قاعدة بيانات logs:

   CREATE DATABASE IF NOT EXISTS logs
   

   أنشئ جدولًا لبياناتك.

   CREATE TABLE logs.nginx_logs
   (
       `time_local` DateTime,
       `remote_addr` IPv4,
       `remote_user` LowCardinality(String),
       `request` String,
       `status` UInt16,
       `body_bytes_sent` UInt64,
       `http_referer` String,
       `http_user_agent` String,
       `http_x_forwarded_for` LowCardinality(String),
       `request_time` Float32,
       `upstream_response_time` Float32,
       `http_host` String
   )
   ENGINE = MergeTree
   ORDER BY (toStartOfMinute(time_local), status, remote_addr)
   

   المفتاح الأساسي لـ Nginx

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

4. ​

   انسخ إعدادات Vector

   يجب أن يتم إدخال البيانات إلى ClickStack من Vector مباشرةً إلى ClickHouse، مع تجاوز نقطة نهاية OTLP التي يوفّرها الـ collector.

   انسخ إعدادات Vector وأنشئ ملفًا باسم nginx.yaml.

   data_dir: ./.vector-data
   sources:
     nginx_logs:
       type: file
       include:
         - access.log
       read_from: beginning
   
   transforms:
     decode_json:
       type: remap
       inputs:
         - nginx_logs
       source: |
         . = parse_json!(to_string!(.message))
         ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
         # ClickHouse-friendly DateTime format
         .time_local = format_timestamp!(ts, format: "%F %T")
   
   sinks:
     clickhouse:
       type: clickhouse
       inputs:
         - decode_json
       endpoint: "http://localhost:8123"
       database: logs
       format: json_each_row
       table: nginx_logs
       skip_unknown_fields: true
       auth:
         strategy: "basic"
         user: "api"
         password: "api"
   

   يستخدم المثال أعلاه المستخدم api في ClickStack Open Source. بالنسبة إلى عمليات النشر في بيئة الإنتاج، نوصي بإنشاء مستخدم مخصص للإدخال مع الأذونات والقيود المناسبة. كما يفترض الإعداد أعلاه أن Vector يعمل على نفس المضيف الذي يعمل عليه ClickStack. وفي عمليات النشر في بيئة الإنتاج، من المرجح أن يختلف ذلك. ونوصي بإرسال البيانات عبر منفذ HTTPS الآمن 8443.

5. ​

   تشغيل Vector

   شغّل Vector باستخدام الأمر التالي.

   mkdir ./.vector-data
   vector --config nginx-local.yaml
   
6. ​

   إنشاء مصدر بيانات

   أنشئ مصدر بيانات للسجلات عبر Team -> Sources

   يفترض هذا التكوين مخطط Nginx مع استخدام العمود time_local كطابع زمني. وهذا هو عمود الطابع الزمني المعرَّف في المفتاح الأساسي. هذا العمود إلزامي.

   كما حددنا أيضًا استعلام SELECT الافتراضي ليكون time_local, remote_addr, status, request، وهو ما يحدد الأعمدة التي تُعرض في واجهة السجلات.

   في المثال أعلاه، لا يوجد عمود Body في البيانات. وبدلًا من ذلك، يُعرَّف كتعبير SQL:

   concat(
     remote_addr, ' ',
     remote_user, ' ',
     '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
     '"', request, '" ',
     toString(status), ' ',
     toString(body_bytes_sent), ' ',
     '"', http_referer, '" ',
     '"', http_user_agent, '" ',
     '"', http_x_forwarded_for, '" ',
     toString(request_time), ' ',
     toString(upstream_response_time), ' ',
     '"', http_host, '"'
   )
   

   يعيد هذا تكوين سطر السجل من الحقول المُهيكلة.

   للاطلاع على الخيارات الأخرى المتاحة، راجع مرجع التهيئة.

7. ​

   انتقل إلى واجهة ClickStack

   انتقل إلى واجهة ClickStack على http://localhost:8080. أنشئ مستخدمًا إذا لم تكن قد أكملت onboarding.

8. ​

   استكشاف البيانات

   انتقل إلى عرض البحث ليوم 20 أكتوبر 2025 لاستكشاف البيانات والبدء في استخدام ClickStack.