مُدار

لإرسال بيانات OpenTelemetry إلى Managed ClickStack، يُنصح باستخدام OpenTelemetry Collector. يعمل الـ collector كبوابة تستقبل بيانات OpenTelemetry من تطبيقاتك (ومن collectors أخرى) وتُمرّرها إلى ClickHouse Cloud.

إذا لم يكن لديك collector قيد التشغيل بالفعل، فابدأ تشغيله باتباع الخطوات أدناه. وإذا كانت لديك collectors موجودة، فستجد أيضًا مثالًا على التهيئة.

ابدأ collector

يفترض ما يلي المسار الموصى به، وهو استخدام توزيعة ClickStack من OpenTelemetry Collector، التي تتضمن معالجة إضافية ومُحسّنة خصيصًا لـ ClickHouse Cloud. إذا كنت تريد استخدام OpenTelemetry Collector الخاص بك، فراجع "تهيئة collectors الموجودة."

للبدء بسرعة، انسخ أمر Docker الموضّح وشغّله.

يجب أن يتضمن هذا الأمر بيانات اعتماد الاتصال الخاصة بك مُعبأة مسبقًا.

يؤدي تشغيل هذا الأمر الواحد إلى بدء ClickStack collector مع إتاحة OTLP endpoints على المنفذين 4317 ‏(gRPC) و4318 ‏(HTTP). إذا كان لديك بالفعل instrumentation وagents لـ OpenTelemetry، فيمكنك البدء فورًا في إرسال بيانات telemetry إلى هذه endpoints.

تهيئة collectors الموجودة

يمكنك أيضًا تهيئة OpenTelemetry Collectors الموجودة لديك أو استخدام التوزيعة الخاصة بك من collector.

ولهذا الغرض، نوفّر مثالًا على تهيئة OpenTelemetry Collector يستخدم ClickHouse exporter مع الإعدادات المناسبة ويُفعّل OTLP receivers. تتوافق هذه التهيئة مع الواجهات والسلوك المتوقعين من توزيعة ClickStack.

استبدل العنصرين النائبين endpoint وpassword ببيانات الاعتماد التي أنشأها ClickStack:

receivers:
  otlp/hyperdx:
    protocols:
      grpc:
        include_metadata: true
        endpoint: "0.0.0.0:4317"
      http:
        cors:
          allowed_origins: ["*"]
          allowed_headers: ["*"]
        include_metadata: true
        endpoint: "0.0.0.0:4318"
processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G, adjust for low memory environments
    limit_mib: 1500
    # 25% of limit up to 2G, adjust for low memory environments
    spike_limit_mib: 512
    check_interval: 5s
connectors:
  routing/logs:
    default_pipelines: [logs/out-default]
    error_mode: ignore
    table:
      - context: log
        statement: route() where IsMatch(attributes["rr-web.event"], ".*")
        pipelines: [logs/out-rrweb]
exporters:
  clickhouse/rrweb:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    logs_table_name: hyperdx_sessions
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
  clickhouse:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/in:
      receivers: [otlp/hyperdx]
      exporters: [routing/logs]
    logs/out-default:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/out-rrweb:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse/rrweb]

لمزيد من التفاصيل حول تهيئة OpenTelemetry collectors، راجع "إدخال البيانات باستخدام OpenTelemetry."

ابدأ إدخال البيانات (اختياري)

إذا كانت لديك تطبيقات أو بنية تحتية قائمة تريد تزويدها بأدوات OpenTelemetry، فانتقل إلى الأدلة ذات الصلة المرتبطة من خلال UI.

لتزويد تطبيقاتك بالأدوات لجمع traces وlogs، استخدم language SDKs المدعومة التي ترسل البيانات إلى OpenTelemetry Collector الخاص بك، والذي يعمل كبوابة لإدخالها إلى Managed ClickStack.

يمكن جمع السجلات باستخدام OpenTelemetry Collectors التي تعمل في وضع agent، مع إعادة توجيه البيانات إلى collector نفسها. ولمراقبة Kubernetes، اتبع الدليل المخصص. وللتكاملات الأخرى، راجع أدلة البدء السريع الخاصة بنا.

بيانات تجريبية

بدلًا من ذلك، إذا لم تكن لديك بيانات موجودة، فجرّب إحدى مجموعات البيانات النموذجية لدينا.

• مجموعة بيانات نموذجية - حمّل مجموعة بيانات نموذجية من العرض التجريبي العام الخاص بنا. شخّص مشكلة بسيطة.
• الملفات المحلية وmetrics - حمّل ملفات محلية وراقب النظام على OSX أو Linux باستخدام OTel collector محلي.

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

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

يفترض ما يلي أن لديك مثيلًا من Vector قيد التشغيل ومهيّأ مسبقًا باستخدام ingest pipelines لتسليم البيانات.

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

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

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

على سبيل المثال، أنشئ قاعدة بيانات للسجلات:

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);

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

نوصي بشدة بفهم كيفية عمل المفاتيح الأساسية في ClickHouse واختيار مفتاح ترتيب بناءً على أنماط الوصول لديك. راجع الإرشادات الخاصة بـ ClickStack بشأن اختيار مفتاح أساسي.

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

للمزيد من أمثلة إدخال البيانات باستخدام Vector، راجع "الإدخال باستخدام Vector" أو توثيق ClickHouse sink في Vector للاطلاع على الخيارات المتقدمة.

سيتم إنشاء مصادر البيانات مسبقًا لأي بيانات OpenTelemetry.

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

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

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

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

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

بمجرد إنشائه، ينبغي أن يتم توجيهك إلى عرض البحث حيث يمكنك البدء فورًا في استكشاف بياناتك.

لإرسال بيانات OpenTelemetry إلى Managed ClickStack، يُنصح باستخدام OpenTelemetry Collector. يعمل الـ collector كبوابة تستقبل بيانات OpenTelemetry من تطبيقاتك (ومن collectors أخرى) ثم تُمرّرها إلى ClickHouse Cloud.

إذا لم يكن لديك collector قيد التشغيل بالفعل، فابدأ بتشغيل واحد باتباع الخطوات أدناه. وإذا كانت لديك collectors موجودة، فستجد أيضًا مثالًا على التهيئة.

بدء تشغيل collector

يفترض ما يلي المسار الموصى به، وهو استخدام توزيعة ClickStack من OpenTelemetry Collector، التي تتضمن معالجة إضافية ومُحسّنة خصيصًا لـ ClickHouse Cloud. إذا كنت تريد استخدام OpenTelemetry Collector الخاص بك، فراجع "تهيئة collectors الموجودة."

للبدء بسرعة، انسخ أمر Docker الموضّح وشغّله.

عدّل هذا الأمر باستخدام بيانات اعتماد الخدمة الخاصة بك، التي دوّنتها عند إنشاء خدمتك.

يؤدي تشغيل هذا الأمر الواحد إلى بدء ClickStack collector مع إتاحة نقاط نهاية OTLP على المنفذين 4317 ‏(gRPC) و4318 ‏(HTTP). إذا كانت لديك بالفعل إعدادات instrumentation ووكلاء OpenTelemetry، فيمكنك البدء فورًا في إرسال بيانات القياس عن بُعد إلى نقاط النهاية هذه.

تهيئة collectors الموجودة

يمكنك أيضًا تهيئة OpenTelemetry Collectors الموجودة لديك أو استخدام التوزيعة الخاصة بك من الـ collector.

ولهذا الغرض، يتوفر مثال على تهيئة OpenTelemetry Collector يستخدم ClickHouse exporter مع الإعدادات المناسبة ويُعرّض OTLP receivers. تتطابق هذه التهيئة مع الواجهات والسلوك المتوقعَين من توزيعة ClickStack.

استبدل العنصرين النائبين endpoint وpassword ببيانات الاعتماد التي أنشأها ClickStack:

receivers:
  otlp/hyperdx:
    protocols:
      grpc:
        include_metadata: true
        endpoint: "0.0.0.0:4317"
      http:
        cors:
          allowed_origins: ["*"]
          allowed_headers: ["*"]
        include_metadata: true
        endpoint: "0.0.0.0:4318"
processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G, adjust for low memory environments
    limit_mib: 1500
    # 25% of limit up to 2G, adjust for low memory environments
    spike_limit_mib: 512
    check_interval: 5s
connectors:
  routing/logs:
    default_pipelines: [logs/out-default]
    error_mode: ignore
    table:
      - context: log
        statement: route() where IsMatch(attributes["rr-web.event"], ".*")
        pipelines: [logs/out-rrweb]
exporters:
  clickhouse/rrweb:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    logs_table_name: hyperdx_sessions
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
  clickhouse:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/in:
      receivers: [otlp/hyperdx]
      exporters: [routing/logs]
    logs/out-default:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/out-rrweb:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse/rrweb]

لمزيد من التفاصيل حول تهيئة OpenTelemetry Collectors، راجع "إدخال البيانات باستخدام OpenTelemetry."

بدء إدخال البيانات (اختياري)

إذا كانت لديك تطبيقات أو بنية تحتية قائمة وتريد تزويدها بـ OpenTelemetry، فانتقل إلى الأدلة ذات الصلة المرتبطة من "ربط تطبيق".

لتزويد تطبيقاتك بما يمكّنها من جمع traces وlogs، استخدم language SDKs المدعومة التي ترسل البيانات إلى OpenTelemetry Collector الخاص بك، والذي يعمل كبوابة لإدخالها إلى Managed ClickStack.

ويمكن جمع السجلات باستخدام OpenTelemetry Collectors التي تعمل في وضع agent، مع إعادة توجيه البيانات إلى الـ collector نفسه. ولمراقبة Kubernetes، اتبع الدليل المخصص. أما للتكاملات الأخرى، فراجع أدلة quickstart الخاصة بنا.

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

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

يفترض ما يلي أن لديك مثيلًا من Vector قيد التشغيل ومُهيّأ مسبقًا باستخدام ingest pipelines ويقوم بإرسال البيانات.

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

يتطلب Vector تحديد جدول ومخطط قبل ingest البيانات.

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

على سبيل المثال، أنشئ قاعدة بيانات للسجلات:

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);

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

نوصي بشدة بفهم كيفية عمل المفاتيح الأساسية في ClickHouse واختيار مفتاح ترتيب استنادًا إلى أنماط الوصول لديك. راجع الإرشادات الخاصة بـ ClickStack حول اختيار مفتاح أساسي.

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

للمزيد من أمثلة إدخال البيانات باستخدام Vector، راجع "الإدخال باستخدام Vector" أو توثيق مصبّ ClickHouse في Vector للاطلاع على الخيارات المتقدمة.

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

هذا كل ما في الأمر — أصبحت جاهزًا 🎉.

إذا كنت قد أدخلت البيانات عبر Vector أو أي مصدر آخر، فسيُطلب منك تهيئة مصدر البيانات.

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

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

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

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

بعد تهيئة المصدر، انقر فوق "حفظ" وابدأ في استكشاف بياناتك.