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

إدخال البيانات باستخدام OpenTelemetry في ClickStack - حزمة Observability من ClickHouse

تُستقبل جميع البيانات في 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 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 مكوّن ClickStack OpenTelemetry collector، بما في ذلك:

• All-in-One
• Docker Compose
• Helm

​

تثبيت 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

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

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]