ClickStack OpenTelemetry 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.

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

# 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>"

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

docker run -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest

# 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

export CLICKHOUSE_ENDPOINT=<HTTPS ENDPOINT>
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

docker run -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest

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

  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

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

# 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: "tcp://clickhouse.your-namespace.svc.cluster.local:9000?dial_timeout=10s"
  - name: CLICKHOUSE_USER
    value: "otelcollector"
  - name: CLICKHOUSE_PASSWORD
    value: "<password>"
  - name: OPAMP_SERVER_URL
    value: "http://hyperdx.your-namespace.svc.cluster.local:4320"
  - name: HYPERDX_API_KEY
    value: "<your-ingestion-api-key>"

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

docker run -e OPAMP_SERVER_URL=${OPAMP_SERVER_URL} -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest

# values.yaml
extraEnvs:
  - name: OPAMP_SERVER_URL
    value: "<OPAMP_SERVER_URL>"
  - 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

export OPAMP_SERVER_URL=<OPAMP_SERVER_URL>
export CLICKHOUSE_ENDPOINT=<HTTPS ENDPOINT>
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

docker run -e OPAMP_SERVER_URL=${OPAMP_SERVER_URL} -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-otel-collector:latest

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

  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'
      OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}'
    ports:
      - '13133:13133' # health_check extension
      - '24225:24225' # fluentd receiver
      - '4317:4317' # OTLP gRPC receiver
      - '4318:4318' # OTLP http receiver
      - '8888:8888' # metrics extension
    restart: always
    networks:
      - internal

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

افتراضيًا، لا يكون جامع OpenTelemetry الخاص بـ ClickStack مؤمّنًا عند نشره خارج التوزيعات مفتوحة المصدر، ولا يتطلب مصادقة على منافذ OTLP الخاصة به.

لتأمين إدخال البيانات، حدِّد رمز مصادقة عند نشر الجامع باستخدام متغير البيئة OTLP_AUTH_TOKEN. وتعتمد طريقة ضبط ذلك على أسلوب النشر الذي تستخدمه:

HelmDocker

أضف 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) وتصفية الأحداث، إلى جانب معالج لتجميع الأحداث على دفعات والحد من استخدام الذاكرة.

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 معالج. وقد يسبب ذلك مشكلات، وهنا تصبح عمليات الإدراج غير المتزامنة ضرورية. ونادرًا ما تظهر هذه المشكلة إذا كنت ترسل البيانات إلى ClickStack مجمّع الذي يعمل كبوابة، إذ يخفف هذا الإشكال من خلال عمله كمجمّع — راجع أدوار المجمّع.

إذا تعذر ضمان دفعات كبيرة، يمكنك إسناد التجميع إلى 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 لديك. وتجد هنا إعدادات إضافية يمكن استخدامها لضبط تفريغ المخزن المؤقت. وبوجه عام، تكون القيم الافتراضية مناسبة.

أخيرًا، فإن سلوك deduplication السابق المرتبط بعمليات الإدراج المتزامنة في ClickHouse لا يكون مفعّلًا افتراضيًا عند استخدام عمليات الإدراج غير المتزامنة. وإذا لزم الأمر، فراجع الإعداد async_insert_deduplicate.

يمكن العثور على التفاصيل الكاملة حول تهيئة هذه الميزة في صفحة التوثيق، أو في منشور المدونة المتعمق.

يعمل ClickStack OTel مجمّع كمثيل بوابة — راجع أدوار المجمّع. وتوفّر هذه المثيلات خدمة مستقلة، عادةً لكل مركز بيانات أو لكل منطقة. وهي تستقبل الأحداث من التطبيقات (أو من مجمّعات أخرى بدور وكيل) عبر OTLP endpoint واحد. وعادةً ما يُنشر عدد من مثيلات مجمّع، مع استخدام موازن تحميل جاهز لتوزيع الحمل بينها.

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

قد يلاحظ القرّاء أن البُنى المعمارية المذكورة أعلاه لا تستخدم Kafka كصفّ رسائل.

يُعد استخدام صفّ Kafka كمخزن مؤقت للرسائل نمطًا تصميميًا شائعًا في معماريات logging، وقد اشتهرت به حزمة ELK. ويوفّر ذلك عدة مزايا: أبرزها أنه يساعد في توفير ضمانات أقوى لتسليم الرسائل، كما يساعد على التعامل مع الضغط العكسي. تُرسَل الرسائل من وكلاء التجميع إلى Kafka وتُكتَب على القرص. ومن الناحية النظرية، ينبغي أن يوفّر مثيل Kafka عنقودي مخزنًا مؤقتًا عالي الإنتاجية للرسائل، لأن كتابة البيانات تسلسليًا إلى القرص تفرض عبئًا حسابيًا أقل من parse الرسالة ومعالجتها. في Elastic، على سبيل المثال، تفرض tokenization وindexing عبئًا إضافيًا كبيرًا. ومن خلال إبعاد البيانات عن الوكلاء، فإنك تقلل أيضًا من خطر فقدان الرسائل نتيجة تدوير السجلات في المصدر. وأخيرًا، يوفّر بعض إمكانات إعادة تشغيل الرسائل والنسخ المتماثل بين المناطق، وهو ما قد يكون جذابًا لبعض حالات الاستخدام.

ومع ذلك، يستطيع ClickHouse التعامل مع insert البيانات بسرعة كبيرة جدًا — ملايين الصفوف في الثانية على عتاد متوسط. كما أن الضغط العكسي من ClickHouse نادر. وفي كثير من الأحيان، يعني الاعتماد على صفّ Kafka مزيدًا من التعقيد المعماري والتكلفة. وإذا كان بإمكانك تبنّي مبدأ أن السجلات لا تحتاج إلى ضمانات التسليم نفسها التي تحتاجها المعاملات البنكية وغيرها من البيانات بالغة الأهمية، فنحن نوصي بتجنّب تعقيد Kafka.

ومع ذلك، إذا كنت تحتاج إلى ضمانات تسليم عالية أو إلى القدرة على إعادة تشغيل البيانات (وربما إلى مصادر متعددة)، فقد تكون Kafka إضافة معمارية مفيدة.

في هذه الحالة, يمكن تهيئة وكلاء OTel لإرسال البيانات إلى Kafka عبر Kafka exporter. وتستهلك مثيلات بوابة الرسائل بدورها باستخدام Kafka receiver. نوصي بالرجوع إلى وثائق Confluent وOTel لمزيد من التفاصيل.

تعتمد متطلبات الموارد لـ OTel collector على معدل مرور الأحداث، وحجم الرسائل، ومقدار المعالجة التي تُجرى. ويوفّر مشروع OpenTelemetry اختبارات benchmark يمكن للمستخدمين الاستفادة منها لتقدير متطلبات الموارد.

وفقًا لتجربتنا، يمكن لمثيل gateway في ClickStack مزوّد بـ 3 أنوية و12GB من RAM معالجة نحو 60 ألف حدث في الثانية. ويفترض ذلك pipeline معالجة بسيطًا يقتصر على إعادة تسمية الحقول، من دون استخدام regular expressions.

بالنسبة إلى مثيلات agent المسؤولة عن إرسال الأحداث إلى gateway، والتي يقتصر دورها على تعيين timestamp للحدث، فنوصي بتحديد الحجم بناءً على العدد المتوقع من logs في الثانية. وتمثل الأرقام التالية قيماً تقريبية يمكنك استخدامها كنقطة بداية:

ينشئ ClickStack مجمّع جداول تخزّن السمات في أعمدة Map(LowCardinality(String), String) بشكل افتراضي. وهذا هو المخطط المُوصى به لأحمال عمل observability. كما يتوفر مخطط من النوع JSON في إصدار بيتا للتقييم على أحمال العمل التي تتضمن مجموعة صغيرة ومستقرة من مفاتيح السمات.

للاطلاع على المقارنة الكاملة، ومعرفة الحالات المناسبة لكل خيار، ومتغيرات البيئة المطلوبة لتمكين مخطط النوع JSON، وخطوات الترحيل التفصيلية، راجع Map vs JSON type.