البدء مع ClickStack المُدار

من خدمة ClickHouse Cloud، شغّل ClickStack. في صفحة بدء الاستخدام في ClickStack، اختر بدء الاستيعاب.

في صفحة اختيار مصدر الاستيعاب، اختر OpenTelemetry.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON default.* TO `clickstack-ingest`;

docker run -e CLICKHOUSE_ENDPOINT="https://<host>:8443" \
    -e CLICKHOUSE_USER="default" \
    -e CLICKHOUSE_PASSWORD="<your_password_here>" \
    -p 4317:4317 -p 4318:4318 \
    clickhouse/clickstack-otel-collector:latest

receivers:
  otlp/hyperdx:
    protocols:
      grpc:
        include_metadata: true
        endpoint: "0.0.0.0:4317"
      http:
        cors:
          allowed_origins: ["*"]
          allowed_headers: ["*"]
        include_metadata: true
        endpoint: "0.0.0.0:4318"
processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G, adjust for low memory environments
    limit_mib: 1500
    # 25% of limit up to 2G, adjust for low memory environments
    spike_limit_mib: 512
    check_interval: 5s
connectors:
  routing/logs:
    default_pipelines: [logs/out-default]
    error_mode: ignore
    table:
      - context: log
        statement: route() where IsMatch(attributes["rr-web.event"], ".*")
        pipelines: [logs/out-rrweb]
exporters:
  clickhouse/rrweb:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    logs_table_name: hyperdx_sessions
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
  clickhouse:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/in:
      receivers: [otlp/hyperdx]
      exporters: [routing/logs]
    logs/out-default:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/out-rrweb:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse/rrweb]

أرسل سجل اختبار بالطابع الزمني الحالي:

NOW_NANO="$(date +%s)000000000"

curl -i "http://localhost:4318/v1/logs" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "resourceLogs": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "clickstack-docs-test"}
      }]
    },
    "scopeLogs": [{
      "scope": {"name": "clickstack-docs-test"},
      "logRecords": [{
        "timeUnixNano": "${NOW_NANO}",
        "severityText": "INFO",
        "body": {"stringValue": "ClickStack ingestion test"}
      }]
    }]
  }]
}
EOF

إذا كنت تستخدم مُجمِّعًا موجودًا، فاستبدل http://localhost:4318 بنقطة نهاية OTLP عبر HTTP الخاصة به. إذا كان المستقبِل يتطلب مصادقة، فأضف الترويسة المطلوبة إلى أمر curl.

يعيد الطلب الناجح HTTP/1.1 200 OK.

بعد أن يكتشف ClickStack مصادر بيانات OpenTelemetry، اختر بدء الاستكشاف لفتح عرض البحث. ابحث عن ClickStack ingestion test.

يجب أن تتضمن النتائج حدث الاختبار باسم الخدمة clickstack-docs-test.

من خدمة ClickHouse Cloud الخاصة بك، شغّل ClickStack. في صفحة بدء الاستخدام في ClickStack، حدد بدء الاستيعاب.

في صفحة Choose an ingestion source (اختيار مصدر الاستيعاب)، حدّد Vector.

Vector هو خط أنابيب لبيانات المراقبة عالي الأداء ومحايد تجاه المورّدين، ويحظى بشعبية خاصة في استيعاب السجلات نظرًا لمرونته واستهلاكه المنخفض للموارد.

عند استخدام Vector مع ClickStack، تكون أنت من يحدد المخطط (schema)، وبإمكانه اتباع اصطلاحات OpenTelemetry أو استخدام حقول خاصة بأحداثك.

إنشاء قاعدة بيانات وجدول

أنشئ قاعدة بيانات وجدولاً قبل تكوين sink في Vector.

في ClickHouse Cloud، افتح SQL Console الخاص بـ service الخاصة بك وأنشئ قاعدة بيانات:

على سبيل المثال، أنشئ قاعدة بيانات للسجلات (logs):

CREATE DATABASE IF NOT EXISTS logs

بعد ذلك، أنشئ جدولاً يتطابق مخططه مع بنية بيانات السجلات لديك. ويفترض المثال التالي استخدام تنسيق سجل وصول Nginx الكلاسيكي:

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr);

يجب أن يتوافق جدولك مع مخطط الخرج الذي ينتجه Vector. عدّل المخطط بما يلائم بياناتك، مع اتباع أفضل الممارسات الموصى بها للمخططات.

نوصي بشدة بفهم كيفية عمل المفاتيح الأساسية في ClickHouse واختيار مفتاح ترتيب يتوافق مع أنماط الوصول الخاصة بك. راجع الإرشادات الخاصة بـ ClickStack بشأن اختيار المفتاح الأساسي.

تهيئة وجهة الإخراج (sink) في ClickHouse

بعد التأكد من وجود الجدول، أضف وجهة إخراج (sink) لـ ClickHouse إلى تكوين Vector:

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "https://<host>:8443"
    database: logs
    table: nginx_logs
    format: json_each_row
    skip_unknown_fields: true
    auth:
      strategy: basic
      user: default
      password: "<your_password_here>"

استبدل your_input بالإدخال الخاص بـ pipeline الحالي لديك. واستبدل <host> و<your_password_here> بالقيم الخاصة بخدمة ClickHouse Cloud لديك. وإذا لزم الأمر، غيّر قاعدة البيانات أو الجدول الهدف.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT ON logs.nginx_logs TO `clickstack-ingest`;

احفظ التكوين المُحدَّث، ثم أعد تحميل Vector أو أعد تشغيله باستخدام عملية النشر الحالية لديك.

لمزيد من الأمثلة على استيعاب البيانات باستخدام Vector، راجع الاستيعاب باستخدام Vector، أو راجع توثيق وجهة (sink) ClickHouse في Vector للاطلاع على الخيارات المتقدمة.

إنشاء مصدر بيانات ClickStack

أنشئ مصدر بيانات للجدول الذي يعبّئه خط أنابيب Vector لديك. سيطالبك ClickStack بإنشاء مصدر عند أول تسجيل دخول.

يقوم النموذج تلقائيًا بتعبئة التعبيرات الخاصة بمخطط OpenTelemetry الافتراضي. أما بالنسبة إلى جدول Nginx الذي أنشأته في هذا الدليل، فقم بتهيئة المصدر بالقيم التالية:

لا يحتوي جدول Nginx على عمود Body. اضبط Body Expression على:

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%i:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

للتعرف على إعدادات المصدر الأخرى، راجع مرجع تكوين ClickStack.

أرسل حدثًا نموذجيًا عبر مُدخل مسار Vector الحالي لديك.

للاطّلاع على مزيد من أمثلة مصادر Vector وعمليات التحويل، راجع الاستيعاب باستخدام Vector.

بعد إنشاء مصدر البيانات، اختر بدء الاستكشاف لفتح عرض Search. اختر مصدر البيانات الخاص بجدولك وتأكد من احتوائه على الحدث الذي أرسلته.