SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor · به‌روزرسانی شده 2026-11-06

راهنمای کامل نصب و Self-hosting ابزار Superlog

با نحوه میزبانی شخصی Superlog برای تحلیل لاگ‌ها و تریس‌های OTLP آشنا شوید. این راهنما جزئیات اجرای Postgres و ClickHouse با Docker Compose و نکات مهم پایداری را بررسی می‌کند.

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

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

Superlog تحت لایسنس Apache 2.0 منتشر شده و در github.com/superloglabs/superlog قرار دارد. تا تاریخ 13 October 2026، این پروژه حدود 1.5k ستاره و تقریباً 490 کامیت در main دارد و فاقد هرگونه release tag است. به‌جای اجرای هر آنچه که در صبح روز clone کردن در main وجود دارد، حتماً یک کامیت مشخص را برای خود ثابت (pin) کنید.

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

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

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

تمایزی که برای بودجه یک VPS اهمیت دارد، فضای ذخیره‌سازی است. 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 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"

باری که باعث ایجاد مشکل می‌شود، بار ناگهانی (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 به‌طور خودکار نصب را متوقف نمی‌کند: اعمال محدودیت موتور (engine enforcement) به پیکربندی بستگی دارد و pnpm 9.12.0 در صورت غیرفعال بودن engineStrict، یک مسیر هشدار دارد. بستهٔ 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 به این معنی است که 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 مطابقت دارند. اگر مهاجرت را به پورت 5432 روی سروری که از قبل Postgres دارد هدایت کنید، یا با خطای اتصال مواجه می‌شوید یا بدتر، مهاجرت روی دیتابیس اشتباه اعمال می‌شود.

دستور pnpm dev برنامه turbo run dev را اجرا می‌کند که اسکریپت dev هر برنامه را از طریق Turborepo شروع می‌کند، شامل api، web، worker و proxy، که خروجی آن‌ها در یک ترمینال ترکیب می‌شود. فایل Procfile در مخزن، همان چهار پردازش را لیست کرده و خروجی هر کدام را به tmp/logs/ هدایت می‌کند. اگر می‌خواهید tail -f tmp/logs/proxy.log جایی باشد که لاگ‌های ورودی را مشاهده می‌کنید، آن را با یک اجراکنندهٔ 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

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

برای یک سرویس Node، استفاده از مسیر zero code برای اثبات عملکرد pipeline کافی است:

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

حالا عمداً چیزی را خراب کنید. هر مسیری که خطا ایجاد کند، مناسب است:

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 متعلق به کدام پروژه است. ثابت ماندن تعداد در حالی که در لاگ proxy فعالیت وجود دارد، نشان‌دهنده مشکل در collector یا عملیات نوشتن در ClickHouse است؛ پس docker compose logs collector را مطالعه کنید. عدم وجود هرگونه فعالیت در لاگ proxy به این معناست که exporter هرگز به intake نرسیده است: پورت اشتباه، مسیر اشتباه یا کلید رد شده.

در وب‌اپلیکیشن، آن خطاهای تکراری به جای یک ردیف برای هر درخواست، به صورت یک incident واحد دریافت می‌شوند. Superlog سیگنال‌های ورودی را انگشت‌نگاری (fingerprint) کرده و موارد مشابه را گروه‌بندی می‌کند؛ این تفاوت بین یک صندوق ورودی با 4000 خطای یکسان و صفحه‌ای است که تنها یک مورد را نشان می‌دهد. سپس agent runner پیش‌فرض جامعه، یک خلاصه incident محلی برای آن گروه ثبت می‌کند.

تحقیقات مبتنی بر مدل به یک ارائه‌دهنده مدل و یک agent runner سازگار نیاز دارد؛ runner پیش‌فرض جامعه، یک خلاصه محلی ثبت می‌کند. نام این متغیرها را از فایل .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، سمت میزبان (host) خود را از یک متغیر محیطی می‌گیرد، بنابراین یک فایل .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 را نمایش ندهد. تعریف مجدد ports در یک فایل Compose override، هر دو اتصال را هنگام تفاوت IP میزبان حفظ می‌کند؛ نسخه 2.24.4 و بالاتر Compose از ports: !override برای جایگزینی لیست پشتیبانی می‌کند.

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

سپس نوبت خود عامل (agent) است. ادعای Superlog این است که عامل بررسی می‌کند و اصلاحیه‌ای پیشنهاد می‌دهد، و کلمه مهم در اینجا «پیشنهاد» است. تا زمانی که عملکرد آن را در چند حادثه واقعی مشاهده نکرده‌اید، دسترسی آن به محیط تولید را فقط‌خواندنی نگه دارید. یک GitHub App با دسترسی فقط‌خواندنی نمی‌تواند شاخه اصلاحیه (fix branch) ایجاد کند یا Pull request باز کند: راهنمای راه‌اندازی برای آن گردش کار، به مجوزهای نوشتن Contents و Pull requests، به‌علاوه مجوز نوشتن Issues برای ثبت نظرات نیاز دارد. عاملی که تله‌متری را می‌خواند و یک وصله (patch) می‌نویسد، مفید است. عاملی که می‌تواند سرویس‌های شما را ری‌استارت کند، سطح متفاوتی از ریسک است و این تصمیمی است که باید آگاهانه بگیرید، نه اینکه به‌صورت پیش‌فرض آن را به ارث ببرید. هنگام پیکربندی یک runner مبتنی بر مدل، هزینه نیز شایسته همین توجه است: پیش از آنکه آن را به سمت یک سیستم تولید پرسر و صدا هدایت کنید، بودجه برای مخارج عامل روی VPS را در نظر بگیرید و سوابقی از آنچه عامل واقعاً انجام داده است نگه دارید تا یک Pull request غیرمنتظره، یک مسیر حسابرسی (audit trail) پشت سر خود داشته باشد.

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

  • ERR_PNPM_UNSUPPORTED_ENGINE در حین pnpm install به این معناست که یکی از نیازمندی‌های موتور با سیستم ناسازگار است. نسخه pnpm 9.12.0 هم نیازمندی‌های Node و هم pnpm را بررسی می‌کند؛ نسخه‌های مورد نیاز و فعلی را در متن خطا بخوانید، سپس node -v و pnpm -v را بررسی کنید.
  • ECONNREFUSED 127.0.0.1:5434 در حین مهاجرت به این معناست که stack مربوط به compose بالا نیست، یا DATABASE_URL پورت اشتباهی را مشخص کرده است.
  • ری‌استارت‌های ClickHouse را با docker compose logs clickhouse بررسی کنید، سپس container را برای OOMKilled که مقدار آن true است، چک کنید.
  • اکسپورتری که گزارش موفقیت می‌دهد در حالی که وب‌اپلیکیشن خالی باقی می‌ماند، معمولاً به این معناست که داده‌ها مستقیماً به collector روی پورت 4318 ارسال شده‌اند؛ این کار باعث می‌شود مرحله stamp زدن پروژه که توسط پروکسی انجام می‌شود، نادیده گرفته شود.
  • خطای 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 اکنون CISRE را معرفی کرده است؛ یک پلتفرم AI SRE (مهندسی قابلیت اطمینان سایت) برای Kubernetes و زیرساخت‌های ابری که تحت مجوز PolyForm Noncommercial ارائه می‌شود. ابزار HyperProbe، کاوشگرهایی را درون یک پردازش در حال اجرا قرار می‌دهد تا وضعیت متغیرها را ثبت کرده و آن وضعیت را از طریق MCP (پروتکل زمینه مدل) در اختیار یک دستیار قرار دهد؛ این ابزار همچنین مستنداتی برای self-hosting با استفاده از Docker Compose و یک license key ارائه می‌دهد.

Superlog در میان این دو قرار می‌گیرد. این ابزار مالکیت کل خط لوله (pipeline) را از دریافت 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) نیاز دارد. به جای اعتماد به هر عدد منتشرشده، از جمله این مورد، اعداد واقعی خود را با docker stats --no-stream و free -m اندازه‌گیری کنید.

اکسپورتر 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) دسته‌بندی می‌کند. یک ابزار بررسی uptime خارجی را در کنار آن نگه دارید، زیرا ابزاری که در جای دیگری اجرا می‌شود، زمانی که سرورِ میزبانِ خط لوله تله‌متری شما از کار می‌افتد، همچنان گزارش وضعیت می‌دهد.

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

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

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

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

آیا این مقاله مفید بود؟