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

تثبيت ClickStack OpenTelemetry collector

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

لمزيد من التفاصيل، راجع "نشر الـ 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، بما في ذلك:

• All-in-One
• Docker Compose
• Helm

تثبيت ClickStack OpenTelemetry collector

يمكن أيضًا نشر ClickStack OTel collector بشكل مستقل، بعيدًا عن بقية مكونات المكدس.

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

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

لمزيد من التفاصيل، راجع "نشر الـ 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]