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

تُستقبل جميع البيانات في ClickStack عبر مثيل OpenTelemetry (OTel) collector، الذي يعمل كنقطة الدخول الأساسية للسجلات والمقاييس والتتبعات وبيانات الجلسات. نوصي باستخدام توزيعة ClickStack الرسمية من الـ collector لهذا المثيل.

تتوفر أيضًا نسخة مُدارة من ClickStack — راجع Managed ClickStack.

يرسل المستخدمون البيانات إلى هذا الـ collector من خلال language SDKs أو عبر وكلاء جمع البيانات الذين يجمعون مقاييس البنية التحتية والسجلات (مثل OTel collectors التي تعمل بدور agent، أو تقنيات أخرى مثل Fluentd أو Vector). أما الفرق التي تريد pipeline مُدارة لـ OpenTelemetry، فإن Bindplane يوفر حلًا أصليًا لـ OpenTelemetry مع وجهة ClickStack أصلية، مما يبسّط جمع بيانات telemetry ومعالجتها وتوجيهها.

إرسال بيانات OpenTelemetry

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

تثبيت ClickStack OpenTelemetry collector

لإرسال البيانات إلى Managed ClickStack، يجب نشر OTel collector في دور gateway. سترسل أدوات instrumentation المتوافقة مع OTel الأحداث إلى هذا الـ OTel collector عبر OTLP باستخدام HTTP أو gRPC.

نوصي باستخدام ClickStack OpenTelemetry collectorيتيح لك ذلك الاستفادة من إدخال بيانات موحّد، وschemas موحّدة ومفروضة، وتوافق جاهز مع ClickStack UI ‏(HyperDX). كما يتيح استخدام schema الافتراضي الاكتشاف التلقائي للمصادر وعمليات تعيين الأعمدة المُعدّة مسبقًا.

لمزيد من التفاصيل، راجع “نشر الـ collector”.

إرسال البيانات إلى الـ collector

لإرسال البيانات إلى Managed ClickStack، وجّه أدوات OpenTelemetry instrumentation إلى نقاط النهاية التالية التي يوفّرها OpenTelemetry Collector:

HTTP (OTLP): http://localhost:4318
gRPC (OTLP): localhost:4317

بالنسبة إلى language SDKs ومكتبات telemetry التي تدعم OpenTelemetry، يمكنك ببساطة تعيين متغير البيئة OTEL_EXPORTER_OTLP_ENDPOINT في تطبيقك:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

إذا كنت تنشر توزيعة contrib من OTel collector بدور agent، فيمكنك استخدام OTLP exporter للإرسال إلى ClickStack collector. فيما يلي مثال على إعداد agent يستهلك ملف السجل المهيكل هذا.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

يتضمّن معظم توزيعات ClickStack مكوّن ClickStack OpenTelemetry collector، بما في ذلك:

تثبيت ClickStack OpenTelemetry collector

يمكن أيضًا نشر ClickStack OTel collector بشكل مستقل، بعيدًا عن بقية مكونات المكدس.إذا كنت تستخدم توزيعة HyperDX-only، فستكون مسؤولًا بنفسك عن إيصال البيانات إلى ClickHouse. ويمكنك القيام بذلك من خلال:

تشغيل OpenTelemetry collector الخاص بك وتوجيهه إلى ClickHouse - انظر أدناه.
الإرسال مباشرةً إلى ClickHouse باستخدام أدوات بديلة، مثل Vector، وFluentd، وغير ذلك، أو حتى توزيعة OTel contrib collector الافتراضية.

نوصي باستخدام ClickStack OpenTelemetry collectorيتيح لك ذلك الاستفادة من آلية ingestion موحّدة، وschemas مفروضة، وتوافق جاهز مع HyperDX UI. كما أن استخدام schema الافتراضي يتيح الاكتشاف التلقائي للمصادر وعمليات تعيين الأعمدة المُعدّة مسبقًا.

لمزيد من التفاصيل، راجع “نشر الـ collector”.

إرسال البيانات إلى الـ collector

لإرسال البيانات إلى ClickStack، وجّه إعدادات OpenTelemetry instrumentation في تطبيقك إلى endpoints التالية التي يوفّرها OpenTelemetry collector:

HTTP (OTLP): http://localhost:4318
gRPC (OTLP): localhost:4317

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

بالإضافة إلى ذلك، يلزم إرسال ترويسة تفويض تتضمن مفتاح API للإدخال. يمكنك العثور على المفتاح في تطبيق HyperDX ضمن Team Settings → API Keys.بالنسبة إلى SDKs الخاصة باللغات، يمكن بعد ذلك ضبط هذا إما بواسطة الدالة init أو عبر متغير البيئة OTEL_EXPORTER_OTLP_HEADERS، على سبيل المثال:

OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'

ينبغي كذلك أن تتضمّن المكوّنات العاملة بدور agent ترويسة Authorization هذه في أي اتصال عبر OTLP. على سبيل المثال، إذا كنت تنشر إصدار contrib من OTel collector بدور agent، فيمكنه استخدام مُصدِّر OTLP. يرد أدناه مثال على إعداد agent يستهلك ملف السجل المنظَّم هذا. لاحظ ضرورة تحديد مفتاح تفويض — راجع <YOUR_API_INGESTION_KEY>.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

​إرسال بيانات OpenTelemetry

​تثبيت ClickStack OpenTelemetry collector

​إرسال البيانات إلى الـ collector

​تثبيت ClickStack OpenTelemetry collector

​إرسال البيانات إلى الـ collector

إرسال بيانات OpenTelemetry

تثبيت ClickStack OpenTelemetry collector

إرسال البيانات إلى الـ collector

تثبيت ClickStack OpenTelemetry collector

إرسال البيانات إلى الـ collector