آموزش نصب و میزبانی شخصی Superlog برای مدیریت لاگ‌ها

نصب Superlog در حالت self-hosting شامل چه مواردی است

برای میزبانی شخصی (self-hosting) Superlog، باید مخزن آن را clone کنید، Postgres، ClickHouse و یک OpenTelemetry collector را با Docker Compose بالا بیاورید، یک migration دیتابیس اجرا کنید و سپس چهار سرویس Node را از سورس اجرا نمایید. برنامه‌های شما تریس‌ها، لاگ‌ها و متریک‌های OTLP (پروتکل OpenTelemetry) را به یک پورت ورودی ارسال می‌کنند؛ Superlog آن‌ها را انگشت‌نگاری (fingerprint) کرده، موارد تکراری را در یک حادثه (incident) واحد گروه‌بندی می‌کند و یک عامل (agent)، اولین مرحله از تریاژ (triage) را می‌نویسد. نصب این برنامه یک بعدازظهر زمان می‌برد. پیش از شروع، مطالعه بخش‌های مربوط به ردپای منابع (footprint) و محدودیت‌های واقعی آن توصیه می‌شود.

Superlog تحت مجوز Apache 2.0 منتشر شده و در github.com/superloglabs/superlog قرار دارد. تا آگوست 2026، این پروژه حدود 1.2k ستاره، تقریباً 460 کامیت در main و هیچ تگ release ندارد. نکته آخر، نحوه نصب را تحت تأثیر قرار می‌دهد: git checkout v1.0.0 هیچ نسخه‌ای برای checkout ندارد، بنابراین باید خودتان یک کامیت را pin کنید یا هر چیزی که در صبح روز clone کردن در main وجود دارد را اجرا نمایید.

پاسخ‌هایی که Superlog می‌دهد و Uptime Kuma و Langfuse نمی‌دهند

ابزارهای مانیتورینگ self-hosted از بیرون مشابه به نظر می‌رسند. اما این‌طور نیست و استفاده از ابزار اشتباه، باعث هدر رفتن منابع سرور بدون هیچ دستاوردی می‌شود.

• Uptime Kuma اندپوینت‌های شما را از بیرون بررسی می‌کند و تنها به یک پرسش پاسخ می‌دهد: آیا سرویس در دسترس است؟
• Zabbix میزبان‌ها و سرویس‌ها را روی Ubuntu 24.04 پایش می‌کند و وضعیت CPU، حافظه، دیسک و سرویس‌ها را بر اساس آستانه‌هایی که تعیین کرده‌اید، می‌سنجد.
• Langfuse فراخوانی‌های LLM را ردیابی می‌کند و پرامپت، مدل، توکن‌ها، تأخیر و هزینه هر فراخوانی را ثبت می‌کند.
• Superlog تله‌متری‌هایی را که سرویس‌های معمولی شما از قبل ارسال می‌کنند دریافت کرده و شکست‌های مکرر را به حادثه (incident) تبدیل می‌کند.

Superlog به پرسش متفاوتی پاسخ می‌دهد: چیزی خراب شده است، چه چیزی خراب شده و چرا؟ این ابزار هیچ دیدگاهی درباره فراخوانی‌های LLM ندارد و شما را از بیرون بررسی نمی‌کند. این ابزار داده‌های OTLP را از کد برنامه معمولی شما دریافت کرده و یک عامل (agent) را در مرحله تریاژ قرار می‌دهد؛ همان کاری که یک فرد در حال شیفت (on-call) در اولین گام انجام می‌دهد.

تفاوتی که برای بودجه یک VPS اهمیت دارد، فضای ذخیره‌سازی است. Uptime Kuma به‌راحتی روی 1 GB رم اجرا می‌شود، زیرا تنها چند هزار نتیجه بررسی را ذخیره می‌کند. Superlog از یک column store استفاده می‌کند، زیرا تله‌متری یک‌بار نوشته شده و سپس بر اساس بازه زمانی در میان میلیون‌ها ردیف پرس‌وجو می‌شود. این همان کاری است که ClickHouse برای آن ساخته شده و Postgres برای آن مناسب نیست. Postgres همچنان در پشته (stack) باقی می‌ماند تا داده‌های رابطه‌ای کوچک شامل پروژه‌ها، کاربران، حوادث و کلیدهای دریافت داده را نگهداری کند.

دستور docker compose up -d دقیقاً چه چیزی را اجرا می‌کند؟

سه کانتینر اجرا می‌شوند و هیچ‌کدام از آن‌ها Superlog نیست. این موضوع برای کسانی که انتظار نصب با یک دستور را دارند، غافلگیرکننده است.

• postgres:16، که روی پورت 5434 میزبان منتشر شده است.
• clickhouse/clickhouse-server:26.1، روی پورت 8123 برای HTTP و پورت 9000 برای پروتکل native.
• otel/opentelemetry-collector-contrib:0.150.1، روی پورت 4317 برای gRPC و پورت 4318 برای OTLP روی HTTP.

برنامه‌های Superlog از روی سورس‌کد و توسط pnpm dev روی میزبان اجرا می‌شوند. تا اوت 2026، هیچ فایل compose برای محیط production در مخزن وجود ندارد؛ بنابراین برای یک نصب پایدار، باید unitهای systemd اختصاصی خود را برای اسکریپت start هر برنامه ایجاد کنید یا از Dockerfileهای موجود در هر پوشه استفاده نمایید.

مسیر طی‌شده توسط یک span را در ذهن داشته باشید، زیرا هر خرابی در ادامه، ناشی از شکست در یکی از گام‌های این مسیر است. برنامه شما داده‌های OTLP را به پروکسی دریافت (intake) در Superlog ارسال می‌کند. پروکسی درخواست را با کلید ingest شما احراز هویت کرده، شناسه پروژه را روی آن درج می‌کند و به collector می‌فرستد. collector هرگونه ویژگی superlog.* که کلاینت سعی در تنظیم آن داشته را حذف کرده، superlog.project_id را از هدر ارائه‌شده توسط پروکسی اضافه می‌کند، داده‌ها را دسته‌بندی (batch) کرده و در ClickHouse می‌نویسد. سپس برنامه وب و API، داده‌های تله‌متری را از ClickHouse و سایر اطلاعات را از Postgres می‌خوانند.

حذف آن ویژگی‌ها یک کنترل واقعی برای چندمستأجری (multi-tenancy) است و جنبه تزئینی ندارد. بدون این کار، هر کسی که یک کلید ingest معتبر داشته باشد، می‌تواند خودش superlog.project_id را تنظیم کرده و در داده‌های پروژه دیگری بنویسد.

حداقل منابع مورد نیاز برای VPS چقدر است؟

برای نصب تک‌گره (single node) با حجم ورودی پایین، حداقل 4 هسته vCPU، 8 گیگابایت رم و 40 گیگابایت فضای SSD در نظر بگیرید. این یک کفِ برنامه‌ریزی است، نه یک اندازه‌گیری دقیق؛ بنابراین آن را به عنوان نقطه شروع در نظر بگیرید و با توجه به ترافیک واقعی خود، آن را ارزیابی کنید.

حافظه رم در چهار بخش مصرف می‌شود. ClickHouse برای ماشین‌هایی با رم بالا طراحی شده و تنظیمات پیش‌فرض آن نیز بر همین اساس است. Postgres 16 در اینجا مصرف کمی دارد، زیرا به جای تلمتری، متادیت‌ها را نگهداری می‌کند. Collector نیز مصرف کمی دارد. اما چهار پردازش Node این‌طور نیستند: یک سرور توسعه Vite به همراه سه پردازش tsx watch، هر کدام صدها مگابایت رم اشغال می‌کنند؛ به همین دلیل اجرای pnpm dev روی یک سرور 2 گیگابایتی دشوار است.

دیسک، چالش پنهان‌تری است. pnpm install در این monorepo، پیش از آنکه حتی یک span دریافت کنید، AWS SDK، کلاینت ClickHouse، ابزارهای OpenTelemetry و زنجیره ابزار React را فراخوانی می‌کند. پس از آن، ClickHouse متناسب با ترافیک شما رشد می‌کند. هر دو مورد را اندازه‌گیری کنید:

df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"

در حجم پایین، یعنی زمانی که تعداد انگشت‌شماری سرویس، چند صد span در دقیقه ارسال می‌کنند، سرور خلوت است و ClickHouse بیشتر اوقات در حالت idle قرار دارد. باری که باعث ایجاد مشکل می‌شود، ترافیک ناگهانی (burst) است: یک استقرار (deploy) ناموفق که هزاران خطای مشابه در دقیقه تولید می‌کند. قابلیت Fingerprinting این موارد را برای خواننده در یک رخداد واحد خلاصه می‌کند، اما ClickHouse همچنان تمام ردیف‌ها را در لایه زیرین می‌نویسد.

تعیین دوره نگهداری (retention) بر عهده شماست. صادرکننده (exporter) مربوط به ClickHouse در collector، جداول otel_traces، otel_logs و به ازای هر نوع متریک یک جدول ایجاد می‌کند و تنها در صورتی که در فایل پیکربندی infra/collector/config.yaml تنظیم شده باشد، زمان انقضا (TTL) اعمال می‌شود. هیچ داده‌ای به‌صورت خودکار حذف نمی‌شود، بنابراین اگر برای آن برنامه‌ریزی نکنید، یک ماه پرکار منجر به پر شدن دیسک خواهد شد.

نصب از یک commit مشخص (pinned)

git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'

git tag -l چاپ نکردن هیچ خروجی، نتیجهٔ مورد انتظار تا اوت 2026 است. commitای را که تست کرده‌اید انتخاب کنید و روی همان بمانید:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

سپس، زنجیرهٔ ابزار (toolchain):

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

package.json مقدار engines.node را به عنوان >=20.0.0 و packageManager را به عنوان pnpm@9.12.0 اعلام می‌کند. اگر نصب را روی نسخهٔ قدیمی Node اجرا کنید، pnpm با خطای ERR_PNPM_UNSUPPORTED_ENGINE متوقف می‌شود و نسخهٔ مورد نیاز خود را اعلام می‌کند. بستهٔ nodejs در مخازن Ubuntu 24.04 قدیمی‌تر از 20 است، بنابراین Node 20 یا جدیدتر را از NodeSource یا nvm نصب کنید. این مخزن شامل یک .nvmrc است، بنابراین اگر nvm دارید، nvm use نسخهٔ مورد نظر را انتخاب می‌کند.

pnpm install
docker compose up -d
docker compose ps

به جای اعتماد به up -d برای اطمینان از آماده بودن سرویس، منتظر بررسی‌های سلامت (health checks) بمانید. Postgres و ClickHouse هر دو یکی را در فایل compose تعریف کرده‌اند:

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

ClickHouse پاسخ Ok. می‌دهد و pg_isready پاسخ accepting connections را برمی‌گرداند. خطای Connection refused روی پورت 8123 به این معنی است که کانتینر هنوز در حال بالا آمدن است یا متوقف شده است. دستور docker compose logs clickhouse وضعیت را نشان می‌دهد و docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled در صورتی که هسته (kernel) به دلیل کمبود حافظه کانتینر را کشته باشد، true را گزارش می‌کند؛ این نشان می‌دهد که سرور شما کوچک است و مشکل از پیکربندی شما نیست.

سپس مهاجرت (migration) و برنامه‌ها:

pnpm --filter @superlog/db db:migrate
pnpm dev

به پورت دقت کنید: 5434، نه 5432. فایل compose سرویس Postgres را روی پورت 5434 منتشر می‌کند تا با Postgres نصب‌شده روی میزبان (host) تداخل نداشته باشد، و فایل‌های .env.example برنامه نیز با DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog مطابقت دارند. اگر مهاجرت را به پورت 5432 روی سروری که از قبل Postgres دارد هدایت کنید، یا با خطای اتصال مواجه می‌شوید یا بدتر، مهاجرت روی دیتابیس اشتباه اعمال می‌شود.

pnpm dev چهار پردازش لیست‌شده در Procfile مخزن را شروع می‌کند: api، web، worker و proxy. هر کدام خروجی خود را در tmp/logs/ می‌نویسند، بنابراین tail -f tmp/logs/proxy.log جایی است که باید ingest را مانیتور کنید. فایل README برنامهٔ وب را روی http://localhost:5173، رابط API را روی http://localhost:4100 و دریافت OTLP را روی http://localhost:4101 قرار می‌دهد.

پیش از هدایت هر چیزی به سمت سرویس‌ها، بررسی کنید که واقعاً روی چه پورتی bind شده‌اند:

ss -lntp | grep -E '4100|4101|5173'
curl -sS http://127.0.0.1:4101/health

این موضوع بعداً اهمیت پیدا می‌کند. پروکسی پورت خود را از متغیر محیطی PORT می‌خواند و در صورتی که PORT تنظیم نشده باشد، به صورت پیش‌فرض از 4000 استفاده می‌کند. استک توسعه این متغیر را برای شما تنظیم می‌کند. اما unitای که خودتان برای systemd می‌نویسید این کار را انجام نمی‌دهد؛ بنابراین اگر یک exporter را به سمت 4101 هدایت کنید در حالی که پروکسی روی 4000 گوش می‌دهد، با خطای connection refused مواجه می‌شوید و هیچ سرنخ دیگری دریافت نخواهید کرد.

ارسال یک trace، ایجاد یک خطا، مشاهده یک incident

یک پروژه در وب‌اپلیکیشن ایجاد کنید و ingest key آن را کپی کنید. بخش intake هر درخواست را با استفاده از این کلید احراز هویت می‌کند، بنابراین تله‌متری که بدون کلید ارسال شود، هرگز به ClickHouse نمی‌رسد.

با استفاده از متغیرهای محیطی استاندارد، هر OpenTelemetry SDK را به سمت intake نشانه بروید:

export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'

بخش intake کلید را از هدر x-api-key می‌خواند و اگر پیکربندی exporter شما به این صورت آسان‌تر است، authorization: bearer YOUR_INGEST_KEY را نیز می‌پذیرد. این بخش سه مسیر استاندارد OTLP یعنی /v1/traces، /v1/logs و /v1/metrics، به‌علاوه /health را سرویس‌دهی می‌کند.

یک دام رایج ارزش ذکر کردن دارد. OTEL_EXPORTER_OTLP_ENDPOINT یک URL پایه است و SDK مسیر سیگنال را به انتهای آن اضافه می‌کند. متغیرهای اختصاصی سیگنال مانند OTEL_EXPORTER_OTLP_TRACES_ENDPOINT دقیقاً همان‌طور که نوشته شده‌اند استفاده می‌شوند و هیچ مسیری به آن‌ها اضافه نمی‌شود. اگر متغیر اختصاصی سیگنال را روی http://127.0.0.1:4101 تنظیم کنید، هر export به / ارسال می‌شود که یک مسیر معتبر نیست؛ در نتیجه هیچ داده‌ای دریافت نمی‌شود و SDK خطای export گزارش می‌دهد، در حالی که اپلیکیشن شما سالم به نظر می‌رسد.

برای یک سرویس Node، روش zero-code برای اثبات کارکرد pipeline کافی است:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js

اکنون عمداً چیزی را خراب کنید. هر مسیری که خطا (throw) ایجاد کند، مناسب است:

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom

گام‌ها را به ترتیب بررسی کنید، زیرا اولین شکاف نشان می‌دهد کدام بخش با شکست مواجه شده است:

tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'

افزایش تعداد در otel_traces در حالی که وب‌اپلیکیشن خالی است، به معنای عدم تطابق پروژه است؛ بنابراین بررسی کنید که ingest key متعلق به کدام پروژه است. تعداد ثابت در حالی که لاگ‌های پروکسی فعالیت دارند، نشان‌دهنده مشکل در collector یا عملیات نوشتن در ClickHouse است، پس docker compose logs collector را مطالعه کنید. عدم وجود هرگونه فعالیت در لاگ پروکسی به این معنی است که exporter هرگز به intake نرسیده است: پورت اشتباه، مسیر اشتباه یا کلید رد شده.

در وب‌اپلیکیشن، آن خطاهای تکراری به‌جای یک ردیف به ازای هر درخواست، به صورت یک incident واحد دریافت می‌شوند. Superlog سیگنال‌های ورودی را انگشت‌نگاری (fingerprint) کرده و موارد مشابه را گروه‌بندی می‌کند؛ این تفاوت بین یک اینباکس با 4,000 خطای یکسان و صفحه‌ای است که تنها یک مورد را نشان می‌دهد. سپس agent بررسی‌های خود را روی آن گروه اعمال می‌کند.

مرحله بررسی (investigation) یک مدل را فراخوانی می‌کند، بنابراین worker نیاز به یک ارائه‌دهنده مدل پیکربندی‌شده دارد. نام این متغیرها را از فایل .env.example موجود در دایرکتوری هر اپلیکیشن در commit که پین کرده‌اید بردارید، نه از مستندات خارجی، زیرا این متغیرها همراه با main تغییر می‌کنند. همین موضوع در مورد یکپارچه‌سازی‌های GitHub و Sentry نیز صدق می‌کند که مستندات راه‌اندازی اختصاصی خود را در docs/github-app-setup.md و docs/sentry-app-setup.md دارند و ساختار payloadهای webhook آن‌ها در docs/webhooks.md مستند شده است.

ورودی را خصوصی نگه دارید و عامل را در حالت فقط‌خواندنی قرار دهید

Docker به‌صورت پیش‌فرض پورت‌های کانتینر را روی 0.0.0.0 منتشر می‌کند. این پورت‌های منتشرشده از ufw عبور می‌کنند، زیرا Docker قوانین اختصاصی خود را در زنجیره DOCKER-USER می‌نویسد که پیش از بررسی بسته‌ها توسط ufw ارزیابی می‌شوند. در یک VPS با IP عمومی، فایل compose ارائه‌شده، ClickHouse HTTP را روی 8123 و Postgres را روی 5434 قرار می‌دهد که از طریق اینترنت قابل‌دسترسی هستند. اعتبارنامه‌های موجود در آن فایل، مقادیر پیش‌فرض توسعه هستند: کاربر ClickHouse با نام default و بدون رمز عبور، و Postgres با postgres برای نام کاربری و رمز عبور.

آن‌ها را به loopback متصل کنید. هر پورت منتشرشده در فایل compose، سمت میزبان خود را از یک متغیر محیطی می‌گیرد، بنابراین یک .env در ریشه مخزن کافی است:

POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318

پیش از اعتماد به نتیجه، آن را بررسی کرده و سپس کانتینرها را دوباره ایجاد کنید:

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

دستور docker compose config فایل نهایی را چاپ می‌کند، بنابراین می‌توانید به جای حدس‌زدن، 127.0.0.1:5434:5432 را بخوانید. خروجی ss باید 127.0.0.1:5434 را نشان دهد و هرگز 0.0.0.0:5434 نباشد. سعی نکنید این مشکل را با یک فایل compose override که ports را دوباره تعریف می‌کند حل کنید، زیرا Compose لیست پورت‌ها را در فایل‌ها ادغام می‌کند و جایگزین نمی‌کند؛ در نتیجه هر دو اتصال باقی می‌مانند و پورت همچنان در دسترس عموم خواهد بود.

بخش ورودی (intake) نیز به همین مراقبت نیاز دارد. کلید دریافت (ingest key) شما در یک هدر ارسال می‌شود، بنابراین به TLS (امنیت لایه انتقال) در مقابل آن نیاز دارد: TLS را در nginx یا Caddy پیش از پروکسی خاتمه دهید، یا ingest را در یک شبکه خصوصی یا تونل WireGuard نگه دارید. وب‌اپلیکیشن روی 5173 یک سرور توسعه Vite است و به‌هیچ‌وجه نباید در معرض اینترنت قرار گیرد.

سپس خودِ عامل (agent). ادعای Superlog این است که عامل بررسی کرده و اصلاحیه‌ای پیشنهاد می‌دهد؛ کلمه کلیدی در اینجا «پیشنهاد» است. تا زمانی که عملکرد آن را در چند حادثه واقعی مشاهده نکرده‌اید، دسترسی آن به محیط تولید را در حالت فقط‌خواندنی نگه دارید. به GitHub App دسترسی‌های خواندن (read scopes) بدهید و اجازه دهید pull requestهایی ایجاد کند که شما آن‌ها را بررسی می‌کنید. عاملی که تله‌متری را می‌خواند و یک وصله (patch) می‌نویسد، مفید است. عاملی که می‌تواند سرویس‌های شما را restart کند، سطح متفاوتی از ریسک دارد و این تصمیمی است که باید آگاهانه بگیرید، نه اینکه یک پیش‌فرض ارثی باشد. هزینه‌ها نیز شایسته همین توجه هستند، زیرا هر بررسی یک فراخوانی مدل است: پیش از آنکه آن را روی یک سیستم پرسر و صدای تولیدی فعال کنید، بودجه‌ای برای مخارج عامل روی VPS در نظر بگیرید و سوابقی از آنچه عامل واقعاً انجام داده است نگه دارید تا هر pull request غیرمنتظره‌ای، یک مسیر حسابرسی (audit trail) پشت سر خود داشته باشد.

خطاهایی که با آن‌ها مواجه خواهید شد و رشته‌هایی که آن‌ها را نام‌گذاری می‌کنند

• ERR_PNPM_UNSUPPORTED_ENGINE در حین pnpm install به این معنی است که نسخه Node قدیمی‌تر از 20 است. دستور node -v این موضوع را در یک خط تأیید می‌کند.
• ECONNREFUSED 127.0.0.1:5434 در حین مهاجرت به این معنی است که compose stack بالا نیست، یا DATABASE_URL پورت اشتباهی را مشخص کرده است.
• ری‌استارت شدن متوالی ClickHouse معمولاً به دلیل کمبود حافظه است. docker compose logs clickhouse را بخوانید، سپس کانتینر را برای OOMKilled که مقدار آن true است بررسی کنید.
• اکسپورتری که گزارش موفقیت می‌دهد در حالی که وب‌اپلیکیشن خالی می‌ماند، معمولاً به این معنی است که داده‌ها مستقیماً به collector روی پورت 4318 ارسال شده‌اند، که باعث می‌شود stamp پروژه که توسط پروکسی انجام می‌شود، نادیده گرفته شود.
• خطای Connection refused روی پورت 4101 در نصب production به این معنی است که پروکسی به PORT=4000 بازگشته است. مقدار PORT را به‌طور صریح در فایل unit تنظیم کنید.
• docker compose ps که 0.0.0.0:8123 را نشان می‌دهد به این معنی است که bindingهای loopback شما اعمال نشده‌اند. دستور docker compose config را اجرا کنید و پورت‌های resolved را بخوانید.

Flawless، HyperProbe و جایگاه Superlog

این دسته‌بندی نوپا است و ابزارهای موجود در آن بر سر اینکه عامل (agent) اجازه دارد به چه بخش‌هایی دسترسی داشته باشد، اختلاف نظر دارند. Flawless یک ابزار متن‌باز AI SRE (مهندسی قابلیت اطمینان سایت) برای Kubernetes است که به‌جای در اختیار گرفتن خط لوله (pipeline)، داده‌ها را از پشته موجود Prometheus، Loki و Grafana می‌خواند. HyperProbe رویکرد متفاوتی دارد: این یک محصول میزبانی‌شده (hosted) است که تا اوت 2026 متن‌بسته باقی مانده و پروب‌های فقط‌خواندنی (read-only) را درون یک پردازش در حال اجرا قرار می‌دهد تا وضعیت متغیرها را ثبت کرده و آن را از طریق MCP (پروتکل زمینه مدل) در اختیار یک دستیار قرار دهد.

Superlog در میان این دو قرار می‌گیرد. این ابزار مالکیت کامل خط لوله را از دریافت OTLP تا ذخیره‌سازی در ClickHouse بر عهده دارد و عامل خود را در مرحله تریاژ (triage) قرار می‌دهد، نه در مرحله اصلاح (fix). همین طراحی دقیقاً دلیلی است که خود-میزبانی (self-hosting) آن یک تصمیم زیرساختی محسوب می‌شود و نه صرفاً یک کانتینر که بتوان آن را به حال خود رها کرد. هنگامی که Superlog را اجرا می‌کنید، در واقع یک پایگاه‌داده ستونی (column store) را مدیریت می‌کنید که به همان مراقبتی نیاز دارد که هر پایگاه‌داده دیگری که مالکیت آن را بر عهده دارید، نیازمند است.

FAQ

Superlog برای میزبانی شخصی به چه مقدار RAM نیاز دارد؟

برای یک گره (node) با حجم ورودی پایین، 8 گیگابایت RAM، 4 هسته vCPU و 40 گیگابایت فضای دیسک در نظر بگیرید. این پشته شامل Postgres، ClickHouse، یک OpenTelemetry collector و چهار پردازش Node است و ClickHouse به فضای آزاد (headroom) نیاز دارد. یک VPS با 1 یا 2 گیگابایت RAM کافی نیست: pnpm install به تنهایی سنگین است و ClickHouse تحت فشار، توسط OOM Killer هسته سیستم‌عامل متوقف می‌شود. به جای اعتماد به ارقام منتشرشده، از جمله این مورد، اعداد واقعی خود را با docker stats --no-stream و free -m اندازه‌گیری کنید.

صادرکننده (exporter) OTLP خود را به کدام پورت هدایت کنم؟

به پروکسی ورودی Superlog که در README روی http://localhost:4101 تنظیم شده است. این پروکسی از /v1/traces، /v1/logs و /v1/metrics پشتیبانی می‌کند و احراز هویت را با کلید ورودی پروژه شما که از هدر x-api-key یا هدر authorization: bearer دریافت می‌شود، انجام می‌دهد. پورت 4318 مربوط به OpenTelemetry collector در لایه زیرین است و ارسال مستقیم داده به آن، پروکسی را دور می‌زند؛ در حالی که پروکسی همان مؤلفه‌ای است که شناسه پروژه شما را روی داده‌ها درج می‌کند. اگر PORT تنظیم نشده باشد، پروکسی به پورت 4000 بازمی‌گردد؛ بنابراین پیش از فرض کردن پورت 4101، دستور ss -lntp را اجرا کنید و بررسی کنید که سرویس روی چه پورتی bind شده است.

آیا Superlog جایگزین Uptime Kuma یا Zabbix می‌شود؟

خیر. Uptime Kuma پاسخ می‌دهد که آیا یک endpoint از خارج شبکه شما پاسخگو است یا خیر، و Zabbix معیارهای میزبان و سرویس را بر اساس آستانه‌هایی که تعیین کرده‌اید، پایش می‌کند. Superlog تریس‌ها، لاگ‌ها و معیارهایی که برنامه‌های شما منتشر می‌کنند را دریافت کرده و خطاهای تکراری را در قالب حوادث (incidents) دسته‌بندی می‌کند. یک کاوشگر (probe) خارجی برای بررسی uptime در کنار آن داشته باشید، زیرا کاوشگری که در جای دیگری اجرا می‌شود، زمانی که سرورِ میزبانِ خط لوله تله‌متری شما از کار می‌افتد، همچنان گزارش وضعیت را ارسال می‌کند.

آیا عامل (agent) Superlog می‌تواند سیستم‌های تولید (production) من را تغییر دهد؟

فقط از طریق مجوزهایی که شما به آن اعطا می‌کنید. خروجی آن یک بررسی و یک تغییر پیشنهادی است که توسط یک انسان بازبینی می‌شود. در ابتدا، GitHub App را در سطح دسترسی خواندن (read) با pull request نگه دارید و هرگونه اعتبارنامه‌ای که worker در اختیار دارد را محدود به خواندن کنید. دسترسی نوشتن به محیط تولید را به عنوان یک تصمیم جداگانه و آگاهانه در نظر بگیرید، زیرا عاملی که می‌تواند سرویس‌ها را restart کند، تعهد بسیار بزرگ‌تری نسبت به عاملی است که فقط تله‌متری را می‌خواند و یک patch برای بازبینی می‌نویسد.

آیا باید یک commit خاص را pin کنم یا شاخه main را دنبال کنم؟

یک commit را pin کنید. تا اوت 2026 هیچ release tag در مخزن وجود ندارد، بنابراین main تنها هدف متغیر موجود است که در هفته چندین commit دریافت می‌کند. SHA که تست کرده‌اید را ثبت کنید، همان را مستقر کنید و پیش از به‌روزرسانی، diff را مطالعه کنید. git log --oneline <old-sha>..main محل بازبینی است و فایل‌های .env.example در هر برنامه، اولین جایی هستند که باید پس از هر به‌روزرسانی برای متغیرهای جدید مورد نیاز، بررسی شوند.