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

آنچه Superlog در حالت self-hosting واقعاً نصب می‌کند

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

Superlog تحت مجوز Apache 2.0 است و در github.com/superloglabs/superlog قرار دارد. تا تاریخ 13 October 2026، این پروژه حدود 1.5k ستاره، تقریباً 490 کامیت در main و هیچ release tag ندارد. نکته آخر بر نحوه نصب تأثیر می‌گذارد: 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 برای پروتکل بومی.
• otel/opentelemetry-collector-contrib:0.150.1، روی پورت 4317 برای gRPC و پورت 4318 برای OTLP روی HTTP.

برنامه‌های Superlog روی میزبان و از روی سورس‌کد اجرا می‌شوند که توسط pnpm dev راه‌اندازی شده‌اند. تا تاریخ 13 October 2026، هیچ فایل compose برای محیط production در مخزن وجود ندارد؛ بنابراین برای یک نصب پایدار، باید از unitهای systemd اختصاصی خود یا Dockerfileهای موجود در درخت فایل‌های هر برنامه استفاده کنید. برنامه‌های api، worker و proxy هر کدام یک اسکریپت start برای بسته‌بندی در یک unit دارند. برنامه web فاقد این مورد است: این یک برنامه Vite است، بنابراین باید آن را با اسکریپت build خود build کنید و خروجی را به صورت فایل‌های استاتیک توسط nginx یا Caddy سرو کنید، یا اسکریپت preview آن را اجرا کنید که همان vite preview است.

مسیر طی‌شده توسط یک span را در ذهن داشته باشید، زیرا هر خرابی در ادامه، ناشی از شکست در یکی از گام‌های این مسیر است. برنامه شما داده‌های OTLP را به پروکسی دریافت (intake proxy) در Superlog ارسال می‌کند. پروکسی درخواست را با کلید ingest شما احراز هویت کرده، شناسه پروژه را روی آن درج می‌کند و به collector می‌فرستد. collector هرگونه ویژگی superlog.* که کلاینت سعی کرده تنظیم کند را حذف کرده، superlog.project_id را از هدر ارائه‌شده توسط پروکسی اضافه می‌کند، دسته‌بندی (batch) کرده و در ClickHouse می‌نویسد. سپس برنامه web و 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 چاپ نکردن هیچ خروجی، نتیجهٔ مورد انتظار تا تاریخ 13 اکتبر 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 checkها بمانید. 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 به این معنی است که container هنوز در حال بالا آمدن است یا متوقف شده است. دستور 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 مطابقت دارند. اگر migration را روی پورت 5432 در سروری که از قبل Postgres دارد اجرا کنید، یا با خطای refused connection مواجه می‌شوید یا بدتر از آن، migration روی دیتابیس اشتباه اعمال می‌شود.

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

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

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

این موضوع بعداً اهمیت پیدا می‌کند. proxy پورت خود را از متغیر محیطی PORT می‌خواند و در صورتی که PORT تنظیم نشده باشد، به 4000 بازمی‌گردد؛ همچنین فایل apps/proxy/.env.example که بارگذاری می‌کند نیز PORT=4000 را تنظیم می‌کند، اگرچه README ورودی را روی 4101 لیست کرده است (هر دو مورد در 13 اکتبر 2026 بررسی شده‌اند). از هر پورتی که ss نشان می‌دهد استفاده کنید. مثال‌های زیر از 4101 استفاده می‌کنند، بنابراین اگر پورت bind شده 4000 است، آن را جایگزین کنید. یک unit فایل systemd که خودتان می‌نویسید هیچ چیزی را تنظیم نمی‌کند مگر اینکه PORT را در آن قرار دهید، بنابراین یک exporter که به 4101 اشاره دارد در حالی که proxy روی 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 ترافیک کانتینر را در جدول nat مسیریابی می‌کند، بنابراین بسته‌ای که به سمت یک پورت منتشرشده می‌رود، پیش از رسیدن به زنجیره‌های INPUT و OUTPUT که قوانین ufw در آنجا قرار دارند، منحرف می‌شود و 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 لیست پورت‌ها را در فایل‌ها به هم می‌چسباند (concatenation) و جایگزین نمی‌کند؛ در نتیجه با هر دو اتصال مواجه می‌شوید و پورت عمومی همچنان باز می‌ماند.

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

سپس خودِ عامل (agent). ادعای Superlog این است که عامل بررسی می‌کند و اصلاحی پیشنهاد می‌دهد، و کلمه مهم در اینجا «پیشنهاد» است. تا زمانی که عملکرد آن را در چند حادثه واقعی مشاهده نکرده‌اید، آن را در برابر محیط تولید (production) در حالت فقط‌خواندنی نگه دارید. به GitHub App دسترسی‌های خواندن بدهید و اجازه دهید pull requestهایی ایجاد کند که شما آن‌ها را بررسی می‌کنید. عاملی که تله‌متری را می‌خواند و یک وصله (patch) می‌نویسد، مفید است. عاملی که می‌تواند سرویس‌های شما را restart کند، سطح متفاوتی از ریسک است و این تصمیمی است که باید آگاهانه بگیرید، نه اینکه یک پیش‌فرض ارثی باشد. هزینه نیز شایسته همین توجه است، زیرا هر بررسی یک فراخوانی مدل (model call) است: پیش از آنکه آن را به سمت یک سیستم پر سروصدای تولید هدایت کنید، بودجه برای هزینه عامل روی یک 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 ارسال شده‌اند؛ این کار باعث می‌شود مرحله برچسب‌گذاری (stamping) که توسط پروکسی انجام می‌شود، نادیده گرفته شود.
• خطای Connection refused روی پورت 4101 معمولاً به این معنی است که پروکسی روی پورت 4000 گوش می‌دهد؛ پورتی که کد پروکسی در صورت عدم تنظیم، به آن بازمی‌گردد و همان پورتی است که .env.example تعیین می‌کند. متغیر PORT را به‌طور صریح در فایل unit یا در .env برنامه تنظیم کنید.
• docker compose ps که 0.0.0.0:8123 را نشان می‌دهد، به این معنی است که bindingهای loopback شما اعمال نشده‌اند. دستور docker compose config را اجرا کنید و پورت‌های resolve شده را بخوانید.

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 این ابزار یک تصمیم زیرساختی است و نه صرفاً یک container که بتوان آن را به حال خود رها کرد. هنگامی که 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 تحت بار کاری توسط kernel out of memory 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 بازمی‌گردد و .env.example آن نیز 4000 را تنظیم می‌کند؛ بنابراین پیش از فرض کردن پورت 4101، دستور ss -lntp را اجرا کنید و بررسی کنید که روی چه پورتی bind شده است.

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

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

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

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

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

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