الانتقال إلى المحتوى الرئيسي
جرّب OTel FYI - توثيق OTel collector بصورة مبسّطةيوفّر OTel FYI توثيقًا واضحًا ومختصرًا لـ OpenTelemetry collector يغطي receivers وprocessors وexporters وpipelines. وهو مورد مساعد ممتاز لتهيئة ClickStack OTel collector.
تتضمن هذه الصفحة تفاصيل حول تهيئة ClickStack OpenTelemetry (OTel) collector الرسمي.

​
أدوار المجمّع

يمكن نشر OpenTelemetry collectors في دورين رئيسيين:
  • الوكيل - تجمع مثيلات الوكيل البيانات على الأطراف، مثل الخوادم أو عُقد Kubernetes، أو تستقبل الأحداث مباشرةً من التطبيقات المزوّدة بـ OpenTelemetry SDK. وفي الحالة الأخيرة، يعمل مثيل الوكيل مع التطبيق أو على المضيف نفسه الذي يعمل عليه التطبيق (مثل sidecar أو DaemonSet). ويمكن للوكلاء إرسال بياناتهم مباشرةً إلى ClickHouse أو إلى مثيل بوابة. وفي الحالة الأولى، يُشار إلى ذلك باسم نمط نشر الوكيل.
  • البوابة - توفّر مثيلات البوابة خدمة مستقلة، على سبيل المثال على هيئة عملية نشر في Kubernetes، وعادةً ما تكون لكل عنقود أو لكل مركز بيانات أو لكل منطقة. وتستقبل هذه المثيلات الأحداث من التطبيقات (أو من collectors أخرى تعمل كوكلاء) عبر OTLP endpoint واحد. وعادةً ما تُنشر مجموعة من مثيلات البوابة، مع استخدام load balancer جاهز لتوزيع الحمل بينها. وإذا كانت جميع الوكلاء والتطبيقات ترسل إشاراتها إلى نقطة النهاية الواحدة هذه، فغالبًا ما يُشار إلى ذلك باسم نمط نشر البوابة.
مهم: يعمل المجمّع، بما في ذلك في توزيعات ClickStack الافتراضية، وفق دور البوابة الموضّح أدناه، بحيث يستقبل البيانات من الوكلاء أو SDKs. المستخدمون الذين ينشرون OTel collectors في دور الوكيل يستخدمون عادةً توزيعة contrib الافتراضية للمجمّع وليس إصدار ClickStack، لكن يمكنهم استخدام تقنيات أخرى متوافقة مع OTLP مثل Fluentd وVector.

​
نشر المُجمِّع


نوصي باستخدام توزيعة ClickStack الرسمية للمُجمِّع لدور البوابة عند الإرسال إلى Managed ClickStack، كلما أمكن ذلك. إذا اخترت استخدام مُجمِّعك الخاص، فتأكد من أنه يتضمن ClickHouse exporter.يمكن نشر المُجمِّع إما عبر Helm (الموصى به لبيئات Kubernetes) أو عبر Docker. يتضمّن مخطط Helm الرسمي لـ ClickStack مخطط Helm الخاص بـ OpenTelemetry Collector من المصدر الأصلي بوصفه مخططًا فرعيًا، مع تهيئة مسبقة لصورة توزيعة ClickStack—راجع دليل نشر ClickStack عبر Helm إذا كنت ترغب في تثبيت المجموعة الكاملة بما فيها HyperDX. أما لنشر المُجمِّع بصورة مستقلة، فيمكن استخدام المخطط الأصلي مباشرةً مع صورة ClickStack، كما هو موضح أدناه.
أضف مستودع Helm المصدر لـ OpenTelemetry:
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
أنشئ ملف values.yaml لإعداد صورة ClickStack وبيانات اعتماد Managed ClickStack:
# values.yaml
mode: deployment

image:
  repository: docker.clickhouse.com/clickhouse/clickstack-otel-collector
  tag: "2.19.0"

ports:
  otlp:
    enabled: true
  otlp-http:
    enabled: true

extraEnvs:
  - name: CLICKHOUSE_ENDPOINT
    value: "https://your-instance.clickhouse.cloud:8443"
  - name: CLICKHOUSE_USER
    value: "default"
  - name: CLICKHOUSE_PASSWORD
    value: "<password>"
ثبّت الـ chart:
helm install clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml
في عمليات النشر الخاصة ببيئات الإنتاج، نوصي بتخزين CLICKHOUSE_PASSWORD في Kubernetes secret والإشارة إليه عبر extraEnvsFrom بدلًا من تضمين القيمة مباشرة.
يتم تهيئة نسخة ClickHouse المستهدفة عبر متغيرات البيئة CLICKHOUSE_ENDPOINT وCLICKHOUSE_USER وCLICKHOUSE_PASSWORD. يجب أن يكون CLICKHOUSE_ENDPOINT هو عنوان HTTP endpoint الكامل لـ ClickHouse Cloud، بما يشمل البروتوكول والمنفذ—على سبيل المثال: https://99rr6dm6v3.us-central1.gcp.clickhouse.cloud:8443.للاطلاع على تفاصيل استرداد بيانات اعتماد Managed ClickStack الخاصة بك، انظر هنا.
مستخدم الإنتاجيجب استخدام مستخدم لديه بيانات الاعتماد المناسبة في بيئة الإنتاج.

​
تعديل التهيئة

​
تهيئة نسخة Managed ClickStack

يمكن تهيئة OpenTelemetry Collector للاتصال بنسخة Managed ClickStack عبر متغيرات البيئة CLICKHOUSE_ENDPOINT وCLICKHOUSE_USER وCLICKHOUSE_PASSWORD. تختلف طريقة ضبط هذه المتغيرات بحسب أسلوب النشر المُتّبع:
عدِّل الإدخالات ذات الصلة ضمن extraEnvs في ملف values.yaml، ثم حدِّث الإصدار:
# values.yaml
extraEnvs:
  - name: CLICKHOUSE_ENDPOINT
    value: "<HTTPS_ENDPOINT>"
  - name: CLICKHOUSE_USER
    value: "<CLICKHOUSE_USER>"
  - name: CLICKHOUSE_PASSWORD
    value: "<CLICKHOUSE_PASSWORD>"

helm upgrade clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml

​
توسيع تهيئة الـ مُجمِّع

يدعم توزيع ClickStack من OTel مُجمِّع توسيع التهيئة الأساسية من خلال تركيب ملف تهيئة مخصص وتعيين متغير بيئة.لإضافة receivers أو processors أو pipelines مخصصة:
  1. أنشئ ملف تهيئة مخصصًا يتضمن التهيئة الإضافية
  2. ركّب الملف في /etc/otelcol-contrib/custom.config.yaml
  3. عيّن متغير البيئة CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
مثال على تهيئة مخصصة:
receivers:
  # Collect logs from local files
  filelog:
    include:
      - /var/log/**/*.log
      - /var/log/syslog
      - /var/log/messages
    start_at: beginning

  # Collect host system metrics
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
        metrics:
          system.cpu.utilization:
            enabled: true
      memory:
        metrics:
          system.memory.utilization:
            enabled: true
      disk:
      network:
      filesystem:
        metrics:
          system.filesystem.utilization:
            enabled: true

service:
  pipelines:
    # Logs pipeline
    logs/host:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
    
    # Metrics pipeline
    metrics/hostmetrics:
      receivers: [hostmetrics]
      processors:
        - memory_limiter
        - batch
      exporters:
        - clickhouse
النشر باستخدام المُجمِّع المستقل:
docker run -d \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  # -e OPAMP_SERVER_URL=${OPAMP_SERVER_URL} \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -v "$(pwd)/custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-otel-collector:latest
لا تُعرِّف في التهيئة المخصّصة سوى receivers وprocessors وpipelines الجديدة. أمّا processors الأساسية (memory_limiter وbatch) وexporters (clickhouse) فهي معرّفة مسبقًا، لذا اكتفِ بالإشارة إليها بالاسم. تُدمَج التهيئة المخصّصة مع التهيئة الأساسية، ولا يمكنها تجاوز المكوّنات الموجودة.
بالنسبة إلى التهيئات الأكثر تعقيدًا، راجع التهيئة الافتراضية لمجمّع ClickStack ووثائق مُصدِّر ClickHouse.

​
هيكل التهيئة

للاطلاع على تفاصيل حول إعداد مكوّنات OTel مُجمِّع، بما في ذلك receivers، وoperators، وprocessors، نوصي بالرجوع إلى الوثائق الرسمية لـ OpenTelemetry مُجمِّع.

​
Docker Compose

باستخدام Docker Compose، عدِّل إعداد الـ collector باستخدام متغيرات البيئة ذاتها المذكورة أعلاه:
  otel-collector:
    image: hyperdx/hyperdx-otel-collector
    environment:
      CLICKHOUSE_ENDPOINT: 'https://mxl4k3ul6a.us-east-2.aws.clickhouse-staging.com:8443'
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      CLICKHOUSE_USER: 'default'
      CLICKHOUSE_PASSWORD: 'password'
      CUSTOM_OTELCOL_CONFIG_FILE: '/etc/otelcol-contrib/custom.config.yaml'
    ports:
      - '13133:13133' # health_check extension
      - '24225:24225' # fluentd receiver
      - '4317:4317' # OTLP gRPC receiver
      - '4318:4318' # OTLP http receiver
      - '8888:8888' # metrics extension
    volumes:
      - ./custom-config.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
    restart: always
    networks:
      - internal

​
تأمين المجمِّع

افتراضيًا، لا يكون جامع OpenTelemetry الخاص بـ ClickStack مؤمّنًا عند نشره خارج التوزيعات مفتوحة المصدر، ولا يتطلب مصادقة على منافذ OTLP الخاصة به.لتأمين إدخال البيانات، حدِّد رمز مصادقة عند نشر الجامع باستخدام متغير البيئة OTLP_AUTH_TOKEN. وتعتمد طريقة ضبط ذلك على أسلوب النشر الذي تستخدمه:
أضف OTLP_AUTH_TOKEN إلى extraEnvs في ملف values.yaml، ثم قم بترقية الإصدار:
# values.yaml
extraEnvs:
  - name: OTLP_AUTH_TOKEN
    value: "a_very_secure_string"
  - name: CLICKHOUSE_ENDPOINT
    value: "<HTTPS_ENDPOINT>"
  - name: CLICKHOUSE_USER
    value: "<CLICKHOUSE_USER>"
  - name: CLICKHOUSE_PASSWORD
    value: "<CLICKHOUSE_PASSWORD>"

helm upgrade clickstack-otel-collector open-telemetry/opentelemetry-collector -f values.yaml
بالنسبة إلى عمليات النشر في بيئة production، نوصي بتخزين OTLP_AUTH_TOKEN وCLICKHOUSE_PASSWORD في Kubernetes secret والإشارة إليهما عبر extraEnvsFrom.
نوصي أيضًا بما يلي:
  • تهيئة الجامع للتواصل مع ClickHouse عبر HTTPS.
  • إنشاء مستخدم مخصص لإدخال البيانات بصلاحيات محدودة — انظر أدناه.
  • تمكين TLS لنقطة نهاية OTLP، بما يضمن اتصالًا مشفرًا بين SDKs/agents والجامع. ويمكن تهيئة ذلك عبر تهيئة مخصصة للجامع.

​
إنشاء مستخدم لإدخال البيانات

نوصي بإنشاء قاعدة بيانات ومستخدم مخصصين لجامع OTel لإدخال البيانات إلى Managed ClickStack. ويجب أن يمتلك هذا المستخدم صلاحية إنشاء الجداول التي ينشئها ClickStack ويستخدمها وإدخال البيانات فيها.
CREATE DATABASE otel;
CREATE USER hyperdx_ingest IDENTIFIED WITH sha256_password BY 'ClickH0u3eRocks123!';
GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON otel.* TO hyperdx_ingest;
يفترض هذا أن الـ collector مُعدّ لاستخدام قاعدة البيانات otel. يمكن التحكم في ذلك عبر متغير البيئة HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE. مرّر هذا إلى الـ collector على غرار متغيرات البيئة الأخرى.

​
المعالجة - التصفية، والتحويل، والإثراء

سيرغب المستخدمون حتمًا في تصفية رسائل الأحداث وتحويلها وإثرائها أثناء الإدخال. ونظرًا إلى أن إعدادات موصل ClickStack لا يمكن تعديلها، فإننا نوصي المستخدمين الذين يحتاجون إلى مزيد من تصفية الأحداث ومعالجتها بأحد الخيارين التاليين:
  • نشر نسختهم الخاصة من OTel collector لتنفيذ التصفية والمعالجة، ثم إرسال الأحداث إلى ClickStack collector عبر OTLP لإدخالها إلى ClickHouse.
  • نشر نسختهم الخاصة من OTel collector وإرسال الأحداث مباشرةً إلى ClickHouse باستخدام ClickHouse exporter.
إذا كانت المعالجة تُنفَّذ باستخدام OTel collector، فنوصي بإجراء التحويلات على مثيلات gateway وتقليل العمل المنفَّذ على مثيلات agent إلى الحد الأدنى. وهذا يضمن أن تبقى الموارد المطلوبة من agents عند الطرف، التي تعمل على الخوادم، عند أقل مستوى ممكن. وعادةً ما نرى المستخدمين يكتفون بإجراء التصفية فقط (لتقليل استخدام الشبكة غير الضروري)، وضبط الطابع الزمني (عبر operators)، والإثراء الذي يتطلب سياقًا في agents. على سبيل المثال، إذا كانت مثيلات gateway موجودة في Kubernetes cluster مختلف، فسيكون من الضروري إجراء k8s enrichment في agent. يدعم OpenTelemetry ميزات المعالجة والتصفية التالية التي يمكنك الاستفادة منها:
  • Processors - تأخذ Processors البيانات التي تجمعها receivers وتعدّلها أو تحوّلها قبل إرسالها إلى exporters. وتُطبَّق Processors بالترتيب المحدد في قسم processors ضمن إعدادات collector. وهي اختيارية، لكن يُوصى عادةً باستخدام الحد الأدنى منها. عند استخدام OTel collector مع ClickHouse، نوصي بقصر Processors على ما يلي:
  • استخدام memory_limiter لمنع حالات نفاد الذاكرة في collector. راجع تقدير الموارد للاطلاع على التوصيات.
  • أي processor ينفّذ إثراءً استنادًا إلى السياق. على سبيل المثال، يتيح Kubernetes Attributes Processor الضبط التلقائي لـ resource attributes الخاصة بـ spans وmetrics وlogs باستخدام metadata الخاصة بـ k8s، مثل إثراء الأحداث بمعرّف pod المصدر.
  • Tail أو head sampling عند الحاجة إلى traces.
  • Basic filtering - إسقاط الأحداث غير المطلوبة إذا تعذر تنفيذ ذلك عبر operator (انظر أدناه).
  • Batching - وهو أمر أساسي عند العمل مع ClickHouse لضمان إرسال البيانات على دفعات. راجع “Optimizing inserts”.
  • Operators - توفّر Operators أبسط وحدة معالجة متاحة على مستوى receiver. ويجري دعم parsing الأساسي، مما يسمح بضبط حقول مثل Severity وTimestamp. كما يجري دعم parsing باستخدام JSON وregex هنا، إلى جانب تصفية الأحداث والتحويلات الأساسية. ونوصي بتنفيذ تصفية الأحداث هنا.
نوصي المستخدمين بتجنّب الإفراط في معالجة الأحداث باستخدام operators أو transform processors. فقد يترتب على ذلك overhead كبير على الذاكرة ووحدة المعالجة المركزية، ولا سيما parsing الخاص بـ JSON. ومن الممكن تنفيذ كل المعالجة في ClickHouse عند insert time باستخدام materialized views وcolumns، مع بعض الاستثناءات - وتحديدًا الإثراء المعتمد على السياق، مثل إضافة metadata الخاصة بـ k8s. لمزيد من التفاصيل، راجع Extracting structure with SQL.

​
مثال

يوضح الإعداد التالي كيفية جمع بيانات ملف السجل غير المنظَّم هذا. ويمكن استخدام هذا الإعداد بواسطة مُجمِّع يعمل بدور agent لإرسال البيانات إلى بوابة ClickStack. لاحظ استخدام المشغّلات لاستخراج البنية من أسطر السجل (regex_parser) وتصفية الأحداث، إلى جانب معالج لتجميع الأحداث على دفعات والحد من استخدام الذاكرة.
file=code_snippets/ClickStack/config-unstructured-logs-with-processor.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-unstructured.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<ip>[\d.]+)\s+-\s+-\s+\[(?P<timestamp>[^\]]+)\]\s+"(?P<method>[A-Z]+)\s+(?P<url>[^\s]+)\s+HTTP/[^\s]+"\s+(?P<status>\d+)\s+(?P<size>\d+)\s+"(?P<referrer>[^"]*)"\s+"(?P<user_agent>[^"]*)"'
        timestamp:
          parse_from: attributes.timestamp
          layout: '%d/%b/%Y:%H:%M:%S %z'
          #22/Jan/2019:03:56:14 +0330
processors:
  batch:
    timeout: 1s
    send_batch_size: 10000
  memory_limiter:
    check_interval: 1s
    limit_mib: 2048
    spike_limit_mib: 256
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_INGESTION_API_KEY>
    compression: gzip

  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
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]
لاحظ ضرورة تضمين ترويسة authorization التي تحتوي على مفتاح API للإدخال الخاص بك في أي تواصل عبر OTLP. لإعدادات أكثر تقدمًا، نوصي بالاطلاع على وثائق OpenTelemetry Collector.

​
تحسين عمليات الإدراج

لتحقيق أداء عالٍ لعمليات الإدراج مع ضمانات قوية للاتساق، ينبغي الالتزام ببعض القواعد البسيطة عند إدراج بيانات observability في ClickHouse عبر ClickStack collector. ومع الإعداد الصحيح لـ OTel collector، يفترض أن يكون اتباع القواعد التالية سهلًا. ويساعد ذلك أيضًا على تجنّب المشكلات الشائعة التي يواجهها المستخدمون عند استخدام ClickHouse للمرة الأولى.

​
التجميع على دفعات

بشكل افتراضي، تؤدي كل عملية insert تُرسَل إلى ClickHouse إلى أن ينشئ ClickHouse فورًا جزءًا تخزينيًا يحتوي على بيانات عملية insert، إلى جانب بيانات وصفية أخرى يجب تخزينها. لذلك، فإن إرسال عدد أقل من عمليات insert بحيث تحتوي كل واحدة منها على قدر أكبر من البيانات، مقارنةً بإرسال عدد أكبر من عمليات insert بحيث تحتوي كل واحدة منها على قدر أقل من البيانات، يقلل عدد عمليات الكتابة المطلوبة. نوصي بإدراج البيانات في دفعات كبيرة نسبيًا، لا تقل عن 1,000 صف في كل مرة. يمكن العثور على مزيد من التفاصيل هنا. بشكل افتراضي، تكون عمليات insert إلى ClickHouse متزامنة، وتكون idempotent إذا كانت متطابقة. بالنسبة إلى الجداول التي تنتمي إلى عائلة محركات MergeTree، يطبّق ClickHouse افتراضيًا إلغاء تكرار عمليات insert تلقائيًا. وهذا يعني أن عمليات insert تتحمّل حالات مثل ما يلي:
  • (1) إذا واجهت العقدة التي تستقبل البيانات مشكلات، فستنتهي مهلة insert query (أو ستظهر error أكثر تحديدًا) ولن يصل أي إقرار.
  • (2) إذا كانت العقدة قد كتبت البيانات، ولكن تعذّر إعادة الإقرار إلى مُرسل query بسبب انقطاع الشبكة، فسيحصل المُرسل إما على timeout أو على error في الشبكة.
من منظور collector، قد يكون من الصعب التمييز بين الحالتين (1) و(2). ومع ذلك، في كلتا الحالتين، يمكن ببساطة إعادة محاولة عملية insert التي لم يصل إقرار بها فورًا. وما دامت insert query المُعادَة تحتوي على البيانات نفسها وبالترتيب نفسه، فسيتجاهل ClickHouse تلقائيًا عملية insert المُعادَة إذا كانت عملية insert الأصلية (التي لم يصل إقرار بها) قد نجحت. لهذا السبب، يستخدم توزيع ClickStack من OTel collector مكوّن batch processor. وهذا يضمن إرسال عمليات insert على شكل دفعات متسقة من الصفوف تستوفي المتطلبات المذكورة أعلاه. إذا كان من المتوقع أن يحقق collector throughput مرتفعًا (أحداثًا في الثانية)، وكان بالإمكان إرسال 10,000 حدث على الأقل في كل عملية insert، فعادةً ما يكون هذا هو التجميع الوحيد المطلوب في pipeline. ويمكن استخدام قيم تصل إلى 100,000 إذا سمحت الذاكرة بذلك. في هذه الحالة، سيقوم collector بعمل flush للدفعات قبل الوصول إلى timeout الخاص بـ batch processor، مما يضمن بقاء latency من طرف إلى طرف في pipeline منخفضًا، وأن تكون الدفعات ذات حجم متسق.

​
استخدم عمليات الإدراج غير المتزامنة

عادةً ما يضطر المستخدمون إلى إرسال دفعات أصغر عندما يكون معدل النقل لدى المجمّع منخفضًا، ومع ذلك يظلون يتوقعون وصول البيانات إلى ClickHouse بأقل زمن وصول ممكن من طرف إلى طرف. في هذه الحالة، تُرسل الدفعات الصغيرة عند انتهاء مهلة timeout الخاصة بـ batch processor. وقد يسبب ذلك مشكلات، وهنا تصبح عمليات الإدراج غير المتزامنة ضرورية. ونادرًا ما تظهر هذه المشكلة إذا كنت ترسل البيانات إلى ClickStack collector الذي يعمل كبوابة Gateway، إذ يخفف هذا الإشكال من خلال عمله كمجمّع — راجع أدوار المجمّع. إذا تعذر ضمان دفعات كبيرة، يمكنك إسناد التجميع إلى ClickHouse باستخدام عمليات الإدراج غير المتزامنة. ففي عمليات الإدراج غير المتزامنة، تُدرج البيانات أولًا في مخزن مؤقت، ثم تُكتب لاحقًا إلى تخزين قاعدة البيانات بشكل غير متزامن. عند تمكين عمليات الإدراج غير المتزامنة، عندما يستقبل ClickHouse ① insert query، تُكتب بيانات الاستعلام ② فورًا إلى مخزن مؤقت داخل الذاكرة. وعندما يحدث ③ التفريغ التالي للمخزن المؤقت، تُرتَّب بياناته sorted وتُكتب كجزء إلى تخزين قاعدة البيانات. لاحظ أن البيانات لا تكون قابلة للبحث عبر الاستعلامات قبل تفريغها إلى تخزين قاعدة البيانات؛ كما أن تفريغ المخزن المؤقت قابل للتهيئة. لتمكين عمليات الإدراج غير المتزامنة للمجمّع، أضف async_insert=1 إلى connection string. ونوصي باستخدام wait_for_async_insert=1 (وهو الإعداد الافتراضي) للحصول على ضمانات التسليم — راجع هنا لمزيد من التفاصيل. تُدرج البيانات من async insert بمجرد تفريغ المخزن المؤقت في ClickHouse. ويحدث ذلك إما بعد تجاوز async_insert_max_data_size أو بعد مرور async_insert_busy_timeout_ms Milliseconds منذ أول INSERT query. وإذا ضُبط async_insert_stale_timeout_ms على قيمة غير صفرية، فستُدرج البيانات بعد async_insert_stale_timeout_ms milliseconds منذ آخر query. يمكنك ضبط هذه الإعدادات للتحكم في زمن الوصول من طرف إلى طرف في pipeline لديك. وتجد هنا إعدادات إضافية يمكن استخدامها لضبط تفريغ المخزن المؤقت. وبوجه عام، تكون القيم الافتراضية مناسبة.
ضع في اعتبارك عمليات الإدراج غير المتزامنة التكيفيةفي الحالات التي يُستخدم فيها عدد قليل من agent، مع معدل نقل منخفض ولكن متطلبات صارمة لزمن الوصول من طرف إلى طرف، قد تكون عمليات الإدراج غير المتزامنة التكيفية مفيدة. لكن عمومًا، لا تكون مناسبة لحالات استخدام Observability ذات معدل النقل المرتفع، كما هو الحال مع ClickHouse.
أخيرًا، فإن سلوك deduplication السابق المرتبط بعمليات الإدراج المتزامنة في ClickHouse لا يكون مفعّلًا افتراضيًا عند استخدام عمليات الإدراج غير المتزامنة. وإذا لزم الأمر، فراجع الإعداد async_insert_deduplicate. يمكن العثور على التفاصيل الكاملة حول تهيئة هذه الميزة في صفحة التوثيق، أو في منشور المدونة المتعمق.

​
التوسّع

يعمل ClickStack OTel collector كمثيل gateway — راجع أدوار المجمّع. وتوفّر هذه المثيلات خدمة مستقلة، عادةً لكل مركز بيانات أو لكل منطقة. وهي تستقبل الأحداث من التطبيقات (أو من collectors أخرى بدور agent) عبر OTLP endpoint واحد. وعادةً ما يُنشر عدد من مثيلات collector، مع استخدام موازن تحميل جاهز لتوزيع الحمل بينها. الهدف من هذه المعمارية هو تخفيف عبء المعالجة كثيفة الاستهلاك عن agents، مما يقلّل استخدامهم للموارد. ويمكن لبوابات ClickStack هذه تنفيذ مهام التحويل التي كان سيتعيّن على agents تنفيذها لولا ذلك. إضافةً إلى ذلك، من خلال تجميع الأحداث من عدد كبير من agents، يمكن للبوابات ضمان إرسال دفعات كبيرة إلى ClickHouse، مما يتيح إدراجًا بكفاءة. ويمكن توسيع gateway collectors هذه بسهولة مع إضافة المزيد من agents ومصادر SDK وزيادة throughput للأحداث.

​
إضافة Kafka

قد يلاحظ القرّاء أن البُنى المعمارية المذكورة أعلاه لا تستخدم Kafka كصفّ رسائل. يُعد استخدام صفّ Kafka كمخزن مؤقت للرسائل نمطًا تصميميًا شائعًا في معماريات logging، وقد اشتهرت به حزمة ELK. ويوفّر ذلك عدة مزايا: أبرزها أنه يساعد في توفير ضمانات أقوى لتسليم الرسائل، كما يساعد على التعامل مع الضغط العكسي. تُرسَل الرسائل من وكلاء التجميع إلى Kafka وتُكتَب على القرص. ومن الناحية النظرية، ينبغي أن يوفّر مثيل Kafka عنقودي مخزنًا مؤقتًا عالي الإنتاجية للرسائل، لأن كتابة البيانات تسلسليًا إلى القرص تفرض عبئًا حسابيًا أقل من parse الرسالة ومعالجتها. في Elastic، على سبيل المثال، تفرض tokenization وindexing عبئًا إضافيًا كبيرًا. ومن خلال إبعاد البيانات عن الوكلاء، فإنك تقلل أيضًا من خطر فقدان الرسائل نتيجة تدوير السجلات في المصدر. وأخيرًا، يوفّر بعض إمكانات إعادة تشغيل الرسائل والنسخ المتماثل بين المناطق، وهو ما قد يكون جذابًا لبعض حالات الاستخدام. ومع ذلك، يستطيع ClickHouse التعامل مع insert البيانات بسرعة كبيرة جدًا — ملايين الصفوف في الثانية على عتاد متوسط. كما أن الضغط العكسي من ClickHouse نادر. وفي كثير من الأحيان، يعني الاعتماد على صفّ Kafka مزيدًا من التعقيد المعماري والتكلفة. وإذا كان بإمكانك تبنّي مبدأ أن السجلات لا تحتاج إلى ضمانات التسليم نفسها التي تحتاجها المعاملات البنكية وغيرها من البيانات بالغة الأهمية، فنحن نوصي بتجنّب تعقيد Kafka. ومع ذلك، إذا كنت تحتاج إلى ضمانات تسليم عالية أو إلى القدرة على إعادة تشغيل البيانات (وربما إلى مصادر متعددة)، فقد تكون Kafka إضافة معمارية مفيدة. في هذه الحالة، يمكن تهيئة وكلاء OTel لإرسال البيانات إلى Kafka عبر Kafka exporter. وتستهلك مثيلات gateway الرسائل بدورها باستخدام Kafka receiver. نوصي بالرجوع إلى وثائق Confluent وOTel لمزيد من التفاصيل.
تهيئة OTel collectorيمكن تهيئة توزيعة ClickStack OpenTelemetry collector مع Kafka باستخدام تهيئة collector مخصّصة.

​
تقدير الموارد

تعتمد متطلبات الموارد لـ OTel collector على معدل مرور الأحداث، وحجم الرسائل، ومقدار المعالجة التي تُجرى. ويوفّر مشروع OpenTelemetry اختبارات benchmark يمكن للمستخدمين الاستفادة منها لتقدير متطلبات الموارد. وفقًا لتجربتنا، يمكن لمثيل gateway في ClickStack مزوّد بـ 3 أنوية و12GB من RAM معالجة نحو 60 ألف حدث في الثانية. ويفترض ذلك pipeline معالجة بسيطًا يقتصر على إعادة تسمية الحقول، من دون استخدام regular expressions. بالنسبة إلى مثيلات agent المسؤولة عن إرسال الأحداث إلى gateway، والتي يقتصر دورها على تعيين timestamp للحدث، فنوصي بتحديد الحجم بناءً على العدد المتوقع من logs في الثانية. وتمثل الأرقام التالية قيماً تقريبية يمكنك استخدامها كنقطة بداية:
معدل السجلاتالموارد المخصصة لـ collector agent
1k/second0.2CPU, 0.2GiB
5k/second0.5 CPU, 0.5GiB
10k/second1 CPU, 1GiB

​
اختيار المخطط: Map مقابل JSON

ينشئ مُجمِّع ClickStack جداول تخزّن السمات في أعمدة من النوع Map(LowCardinality(String), String) افتراضيًا. وهذا هو المخطط الموصى به لأعباء عمل observability. كما يتوفر مخطط من النوع JSON بحالة Beta للتقييم في أعباء العمل التي تحتوي على مجموعة صغيرة ومستقرة من مفاتيح السمات. للاطّلاع على المقارنة الكاملة، ومعرفة متى يكون كلٌّ منهما مناسبًا، ومتغيرات البيئة المطلوبة لتمكين المخطط من النوع JSON، ودليل الترحيل، راجع Map vs JSON type.
آخر تعديل في ٢٥ يونيو ٢٠٢٦