آشنایی با ClickStack برای Observability

ClickStack یک پلتفرم Observability در سطح تولید (Production-grade) است که بر پایه ClickHouse ساخته شده و چهار حوزه کلیدی لاگ‌ها (Logs)، ردیابی‌ها (Traces)، متریک‌ها (Metrics) و جلسات (Sessions) را در یک راهکار واحد و یکپارچه ترکیب می‌کند. هدف اصلی آن ساده‌سازی پایش و اشکال‌زدایی سیستم‌های پیچیده است؛ به‌طوری که توسعه‌دهندگان و تیم‌های SRE بتوانند مشکلات را به‌صورت سرتاسری (End-to-End) بدون نیاز به جابه‌جایی بین ابزارهای مختلف یا همبستگی دستی داده‌ها بر اساس تایم‌استمپ یا Correlation ID بررسی کنند.

ایده اصلی

در قلب ClickStack یک ایده ساده اما قدرتمند وجود دارد: تمام داده‌های Observability باید به شکل رویدادهای غنی و گسترده (Wide, Rich Events) ذخیره شوند. این رویدادها بر اساس نوع داده (لاگ، متریک، تریس و سشن) در جداول ClickHouse نگهداری می‌شوند، اما همچنان در سطح پایگاه داده قابل کوئری و همبسته‌سازی متقابل هستند.

ویژگی‌ها

• جستجو و همبستگی بین لاگ‌ها، متریک‌ها، تریس‌ها و سشن‌ها در یک محیط واحد
• کارایی بسیار بالا در پردازش داده‌های پرکاردینالیتی به کمک معماری ستونی ClickHouse
• پشتیبانی بومی از JSON برای انعطاف‌پذیری در طرح‌واره (Schema Evolution)
• داشبوردهای سریع و آماده برای داده‌های حجیم بدون نیاز به زبان پرس‌وجوی پیچیده
• جستجوی متنی کامل و Syntax ساده برای فیلتر (SQL اختیاری)
• امکان مانیتورینگ زنده (Live tail) برای لاگ‌ها و تریس‌ها
• پشتیبانی کامل از OpenTelemetry برای جمع‌آوری داده‌ها
• تحلیل روندها، تشخیص انحرافات و شناسایی الگوهای لاگ

اجزای اصلی ClickStack

1. HyperDX UI: رابط کاربری تحت وب برای جستجو، داشبوردها، هشدارها و تحلیل داده‌ها.
2. OpenTelemetry Collector: جمع‌آوری‌کننده داده با طرح‌واره پیشنهادی، بهینه‌سازی‌شده برای ClickHouse.
3. ClickHouse: موتور تحلیلی سریع برای ذخیره و پردازش داده‌ها در مقیاس بالا.
   (در معماری کامل، MongoDB نیز برای ذخیره تنظیمات، داشبوردها و حساب‌های کاربری استفاده می‌شود.)

اصول طراحی

• راه‌اندازی سریع و آسان: در چند دقیقه روی هر ClickHouse قابل راه‌اندازی است.
• انعطاف‌پذیر و کاربرپسند: هم SQL و هم Lucene-style Query را پشتیبانی می‌کند.
• Observability سرتاسری: پوشش کامل از سشن‌های کاربر تا متریک‌های زیرساخت و تریس‌های توزیع‌شده.
• بهره‌برداری کامل از ClickHouse: سرعت بالا در جستجو و تجمیع داده‌ها در مقیاس بزرگ.
• OpenTelemetry-native: جمع‌آوری داده از طریق OTel Collector به‌صورت پیش‌فرض.
• متن‌باز و قابل سفارشی‌سازی کامل: هر جزء را می‌توان به‌صورت مستقل یا مجتمع در محیط‌های مختلف مستقر کرد.

شروع به کار با ClickStack

اجزای اصلی ClickStack

ClickStack از سه بخش کلیدی تشکیل شده است:

1. HyperDX UI → رابط کاربری برای جستجو، داشبوردها، هشدارها و بررسی داده‌ها.
2. OpenTelemetry Collector → جمع‌آوری‌کننده داده‌های لاگ، متریک و تریس و ارسال آنها به ClickHouse.
3. ClickHouse → پایگاه داده تحلیلی سریع برای ذخیره‌سازی و پردازش داده‌های Observability.

(در معماری کامل، MongoDB هم برای ذخیره تنظیمات و داشبوردها به‌کار می‌رود.)

روش‌های نصب و استقرار

۱. استقرار محلی (Local Deployment)

ساده‌ترین روش، استفاده از ایمیج all-in-one است که تمام اجزای اصلی (UI، OTel Collector و ClickHouse) را در یک کانتینر ارائه می‌دهد.
این روش برای آزمایش سریع، توسعه محلی یا دمو مناسب است.

docker run -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one

• پورت ۸۰۸۰ → رابط کاربری HyperDX
• پورت‌های ۴۳۱۷ و ۴۳۱۸ → برای دریافت داده‌های OpenTelemetry

برای دسترسی به UI کافی است وارد آدرس زیر شوید:
👉 http://localhost:8080

نگهداری داده‌ها (Persistence)

برای اینکه داده‌ها و تنظیمات بعد از ری‌استارت پاک نشوند، باید مسیرهای مربوط به داده و لاگ‌ها را روی سیستم محلی Mount کنید:

docker run \
  -p 8080:8080 \
  -p 4317:4317 \
  -p 4318:4318 \
  -v "$(pwd)/.volumes/db:/data/db" \
  -v "$(pwd)/.volumes/ch_data:/var/lib/clickhouse" \
  -v "$(pwd)/.volumes/ch_logs:/var/log/clickhouse-server" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one

۲. اتصال به ClickHouse Cloud

برای محیط‌های جدی‌تر یا تولید (Production)، می‌توانید ClickStack را به ClickHouse Cloud متصل کنید:

1. یک سرویس ClickHouse Cloud بسازید.
2. جزئیات اتصال (endpoint و password) را از کنسول دریافت کنید.
3. کانتینر ClickStack را با متغیرهای محیطی زیر اجرا کنید:

export CLICKHOUSE_USER=default
export CLICKHOUSE_ENDPOINT=<YOUR HTTPS ENDPOINT>
export CLICKHOUSE_PASSWORD=<YOUR_PASSWORD>

docker run \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=${CLICKHOUSE_USER} \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one

سپس در HyperDX UI (روی http://localhost:8080) یک Connection جدید برای ClickHouse Cloud بسازید.

۳. Local Mode (حالت سبک و بدون احراز هویت)

برای تست سریع، می‌توانید نسخه local mode را اجرا کنید:

docker run -p 8080:8080 docker.hyperdx.io/hyperdx/hyperdx-local

• در این حالت نیازی به ساخت کاربر نیست.
• امکان اتصال به ClickHouse شخصی یا استفاده از Demo Dataset فراهم است.
• برای دمو می‌توانید مستقیماً از play.hyperdx.io استفاده کنید.

جمع‌بندی

• برای یادگیری و آزمایش سریع → نسخه all-in-one یا local mode بهترین انتخاب است.
• برای محیط تولید → اتصال به ClickHouse Cloud یا استقرار اختصاصی ClickHouse پیشنهاد می‌شود.
• HyperDX UI به‌صورت خودکار منابع داده (لاگ، متریک، تریس، سشن) را ایجاد کرده و امکان مشاهده و تحلیل داده‌ها را فوراً در اختیار شما می‌گذارد.