Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

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

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


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

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

يتطلب 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)

أضِف وجهة 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:

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

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

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

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

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

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

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

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

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

سجلات Nginx في ClickStack

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

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

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

تثبيت Vector

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

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

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

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

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

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

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

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

يتطلب 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)

انسخ تهيئة 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>"

تشغيل Vector

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

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

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

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

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

يفترض هذا الإعداد مخطط 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, '"'
)

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

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

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

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

واجهة مستخدم HyperDX
Navigation