Superlog کو خود ہوسٹ کیسے کریں: مکمل گائیڈ

Superlog self-hosting میں درحقیقت کیا انسٹال ہوتا ہے

Superlog کو self-host کرنے کے لیے آپ repository کو clone کرتے ہیں، Docker Compose کے ذریعے Postgres، ClickHouse اور OpenTelemetry collector کو چلاتے ہیں، ایک database migration رن کرتے ہیں، اور پھر source سے چار Node سروسز شروع کرتے ہیں۔ آپ کی ایپلی کیشنز OTLP (OpenTelemetry protocol) ٹریسز، لاگز اور میٹرکس کو ایک intake port پر بھیجتی ہیں، Superlog ان کے fingerprints بناتا ہے، دہرائے گئے ڈیٹا کو ایک ہی incident میں گروپ کرتا ہے، اور ایک ایجنٹ triage کا پہلا مرحلہ مکمل کرتا ہے۔ انسٹالیشن میں ایک دوپہر کا وقت لگتا ہے۔ شروع کرنے سے پہلے اس کا footprint اور حقیقی حدود (honest limits) پڑھنا ضروری ہے۔

Superlog کا لائسنس Apache 2.0 ہے اور یہ github.com/superloglabs/superlog پر موجود ہے۔ اگست 2026 تک اس کے تقریباً 1.2k اسٹارز، main پر تقریباً 460 commits ہیں، اور کوئی release tag موجود نہیں ہے۔ یہ آخری نکتہ انسٹالیشن پر اثر انداز ہوتا ہے: git checkout v1.0.0 میں check out کرنے کے لیے کچھ نہیں ہے، اس لیے آپ خود کسی commit کو pin کرتے ہیں یا پھر جس وقت آپ نے clone کیا، اس وقت جو بھی main موجود ہو، اسی پر کام چلاتے ہیں۔

Superlog کن سوالات کے جواب دیتا ہے جو Uptime Kuma اور Langfuse نہیں دیتے

سیلف ہوسٹڈ مانیٹرنگ ٹولز باہر سے ایک جیسے دکھائی دیتے ہیں۔ حقیقت میں ایسا نہیں ہے، اور غلط ٹول چلانے کا مطلب ہے کہ آپ بغیر کسی فائدے کے سرور کے وسائل ضائع کر رہے ہیں۔

• Uptime Kuma آپ کے اینڈ پوائنٹس کو باہر سے چیک کرتا ہے اور صرف ایک سوال کا جواب دیتا ہے: کیا سروس آن لائن ہے؟
• Zabbix Ubuntu 24.04 پر ہوسٹس اور سروسز کی نگرانی کرتا ہے، جس میں آپ کی مقرر کردہ حد کے مطابق CPU، میموری، ڈسک اور سروس کی حالت دیکھی جاتی ہے۔
• Langfuse LLM کالز کو ٹریس کرتا ہے، جو ہر کال کے پرامپٹ، ماڈل، ٹوکنز، لیٹنسی اور لاگت کو ریکارڈ کرتا ہے۔
• Superlog ان ٹیلی میٹری ڈیٹا کو استعمال کرتا ہے جو آپ کی عام سروسز پہلے ہی خارج کر رہی ہوتی ہیں اور بار بار ہونے والی خرابیوں کو انسیڈنٹس (incidents) میں تبدیل کر دیتا ہے۔

Superlog کا دائرہ کار مختلف ہے: کچھ ٹوٹ گیا ہے، تو کیا ٹوٹا ہے، اور کیوں ٹوٹا ہے؟ اس کا LLM کالز کے بارے میں کوئی نظریہ نہیں ہے اور یہ آپ کو باہر سے پروب (probe) نہیں کرتا۔ یہ آپ کے عام ایپلیکیشن کوڈ سے OTLP وصول کرتا ہے اور ٹریاج (triage) کے مرحلے پر ایک ایجنٹ بٹھاتا ہے، جو کہ وہی پہلا کام ہے جو آن کال (on-call) پر موجود انسان ویسے بھی کرتا۔

VPS بجٹ کے لیے جو فرق اہم ہے وہ اسٹوریج کا ہے۔ Uptime Kuma 1 GB RAM پر آسانی سے چلتا ہے کیونکہ یہ صرف چند ہزار چیک کے نتائج محفوظ کرتا ہے۔ Superlog ایک کالم اسٹور (column store) رکھتا ہے، کیونکہ ٹیلی میٹری ایک بار لکھی جاتی ہے اور پھر لاکھوں قطاروں میں وقت کے لحاظ سے تلاش کی جاتی ہے۔ یہی کام ClickHouse کرتا ہے اور Postgres نہیں کرتا۔ Postgres اب بھی اسٹیک میں موجود ہے، جو چھوٹا ریلیشنل ڈیٹا سنبھالتا ہے: پروجیکٹس، صارفین، انسیڈنٹس اور ان جیسٹ کیز (ingest keys)۔

docker compose up -d اصل میں کیا شروع کرتا ہے؟

تین کنٹینرز، اور ان میں سے کوئی بھی Superlog نہیں ہے۔ یہ ان لوگوں کے لیے حیران کن ہے جو ایک کمانڈ میں تنصیب کی توقع رکھتے ہیں۔

• postgres:16، جو host port 5434 پر شائع ہوتا ہے۔
• clickhouse/clickhouse-server:26.1، HTTP کے لیے 8123 اور native protocol کے لیے 9000 پر۔
• otel/opentelemetry-collector-contrib:0.150.1، gRPC کے لیے 4317 اور OTLP over HTTP کے لیے 4318 پر۔

Superlog ایپلی کیشنز host پر، source سے چلتی ہیں، جنہیں pnpm dev شروع کرتا ہے۔ اگست 2026 تک repository میں کوئی production compose فائل موجود نہیں ہے، لہذا طویل مدتی تنصیب کا مطلب ہے کہ ہر ایپ کی start اسکرپٹ کے گرد آپ کے اپنے systemd یونٹس ہوں، یا وہ Dockerfiles جو tree میں شامل ہیں۔

اس راستے کو ذہن میں رکھیں جو ایک span اختیار کرتا ہے، کیونکہ نیچے دی گئی ہر ناکامی اس کے کسی ایک مرحلے میں رکاوٹ ہے۔ آپ کی ایپ OTLP کو Superlog انٹیک پراکسی پر پوسٹ کرتی ہے۔ پراکسی آپ کی ingest key کے ساتھ درخواست کی تصدیق کرتی ہے، اس پر پروجیکٹ آئی ڈی لگاتی ہے، اور اسے کلیکٹر کو بھیج دیتی ہے۔ کلیکٹر ان تمام superlog.* اوصاف (attributes) کو ہٹا دیتا ہے جنہیں کلائنٹ نے سیٹ کرنے کی کوشش کی تھی، پراکسی کے فراہم کردہ ہیڈر سے superlog.project_id شامل کرتا ہے، بیچ بناتا ہے، اور ClickHouse میں لکھ دیتا ہے۔ پھر ویب ایپ اور API ٹیلی میٹری کو ClickHouse سے اور باقی سب کچھ Postgres سے پڑھتے ہیں۔

یہ اوصاف کو ہٹانا (attribute stripping) ایک حقیقی multi-tenancy کنٹرول ہے، نہ کہ محض سجاوٹ۔ اس کے بغیر، کوئی بھی شخص جس کے پاس ایک درست ingest key ہو، خود superlog.project_id سیٹ کر سکتا ہے اور کسی دوسرے پروجیکٹ کے ڈیٹا میں لکھ سکتا ہے۔

VPS کا سائز کتنا ہونا چاہیے؟

کم ingest volume کے ساتھ سنگل نوڈ انسٹالیشن کے لیے 4 vCPU، 8 GB RAM اور 40 GB SSD کا منصوبہ بنائیں۔ یہ ایک بنیادی تخمینہ ہے، پیمائش نہیں، لہذا اسے ابتدائی سائز سمجھیں اور اپنے ٹریفک کے مطابق اس کا جائزہ لیں۔

میموری چار جگہوں پر استعمال ہوتی ہے۔ ClickHouse کو زیادہ RAM والی مشینوں کے لیے بنایا گیا ہے اور اس کی ڈیفالٹس اسی کا تقاضا کرتی ہیں۔ Postgres 16 یہاں کم وسائل لیتا ہے، کیونکہ یہ ٹیلی میٹری کے بجائے میٹا ڈیٹا کو محفوظ کرتا ہے۔ کلیکٹر (collector) بھی کم وسائل استعمال کرتا ہے۔ چار Node پروسیسز زیادہ وسائل لیتے ہیں: ایک Vite ڈویلپمنٹ سرور اور تین tsx watch پروسیسز ہر ایک سینکڑوں میگا بائٹس استعمال کرتے ہیں، یہی وجہ ہے کہ 2 GB کی مشین پر pnpm dev کا تجربہ تکلیف دہ ہوتا ہے۔

ڈسک ایک خاموش مسئلہ ہے۔ اس monorepo پر pnpm install ایک بھی span ingest کرنے سے پہلے ہی AWS SDK، ایک ClickHouse کلائنٹ، OpenTelemetry SDK اور ایک 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"

کم حجم پر، جہاں چند سروسز فی منٹ چند سو spans بھیج رہی ہوں، مشین پر بوجھ کم ہوتا ہے اور ClickHouse زیادہ تر وقت بیکار رہتا ہے۔ جو بوجھ نقصان دہ ہے وہ اچانک آنے والا رش (burst) ہے: ایک خراب ڈیپلائےمنٹ جو فی منٹ ہزاروں ایک جیسے ایررز پیدا کرے۔ Fingerprinting انہیں پڑھنے والے کے لیے ایک واقعے میں سمیٹ دیتی ہے، لیکن ClickHouse پھر بھی ہر قطار کو نیچے لکھتا ہے۔

ڈیٹا کو محفوظ رکھنے کی مدت (retention) آپ کو خود طے کرنی ہے۔ کلیکٹر کا ClickHouse ایکسپورٹر ٹیبلز، otel_traces، otel_logs اور ہر میٹرک ٹائپ کے لیے ایک ٹیبل بناتا ہے، اور یہ صرف تب ہی وقت کی حد (time to live) لاگو کرتا ہے اگر infra/collector/config.yaml میں موجود کنفیگریشن اسے سیٹ کرے۔ کوئی بھی چیز خود بخود ختم نہیں ہوتی، لہذا اگر آپ نے منصوبہ بندی نہ کی تو ایک مصروف مہینہ ڈسک کو مکمل بھر سکتا ہے۔

کسی مخصوص کمٹ (pinned commit) سے انسٹالیشن

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

git tag -l کا کچھ بھی پرنٹ نہ کرنا اگست 2026 تک متوقع نتیجہ ہے۔ جس کمٹ کو آپ نے ٹیسٹ کیا ہے اسے منتخب کریں اور اسی پر رہیں۔

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 کے ساتھ رک جاتا ہے اور مطلوبہ ورژن کا نام بتاتا ہے۔ Ubuntu 24.04 آرکائیو میں موجود nodejs پیکیج 20 سے پرانا ہے، لہذا NodeSource یا nvm سے Node 20 یا اس سے نیا ورژن انسٹال کریں۔ ریپوزٹری میں ایک .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 کا جواب دیتا ہے۔ 8123 پر Connection refused کا مطلب ہے کہ کنٹینر ابھی شروع ہو رہا ہے یا بند ہو چکا ہے۔ docker compose logs clickhouse دکھاتا ہے کہ ان میں سے کیا صورتحال ہے، اور docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled اس وقت true رپورٹ کرتا ہے جب کرنل نے میموری کی کمی کی وجہ سے اسے ختم کر دیا ہو، جو اس بات کی نشاندہی کرتا ہے کہ سرور کی صلاحیت کم ہے، نہ کہ آپ کی کنفیگریشن میں کوئی خرابی ہے۔

اس کے بعد مائیگریشن اور ایپلیکیشنز:

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

پورٹ پر توجہ دیں: 5434، نہ کہ 5432۔ Compose فائل Postgres کو 5434 پر پبلش کرتی ہے تاکہ یہ ہوسٹ پر پہلے سے انسٹال شدہ Postgres سے نہ ٹکرائے، اور ایپ کی .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 پر واپس آ جاتی ہے۔ ڈویلپمنٹ اسٹیک اسے آپ کے لیے سیٹ کر دیتا ہے۔ آپ کی اپنی لکھی ہوئی systemd یونٹ ایسا نہیں کرتی، لہذا 4000 پر سننے والی پراکسی کے خلاف 4101 پر بھیجا گیا ایکسپورٹر connection refused کے ساتھ ناکام ہو جائے گا اور آپ کو کوئی اور سراغ نہیں ملے گا۔

ایک ٹریس بھیجیں، ایک ایرر پیدا کریں، ایک انسیڈنٹ دیکھیں

ویب ایپ میں ایک پروجیکٹ بنائیں اور اس کی ingest key کاپی کریں۔ انٹیک ہر درخواست کی تصدیق اس کلید کے ذریعے کرتا ہے، لہذا اس کے بغیر بھیجی گئی ٹیلی میٹری کبھی بھی ClickHouse تک نہیں پہنچتی۔

کسی بھی OpenTelemetry SDK کو معیاری environment variables استعمال کرتے ہوئے انٹیک کی طرف پوائنٹ کریں:

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'

انٹیک کلید کو x-api-key ہیڈر سے پڑھتا ہے، اور اگر آپ کے ایکسپورٹر کو اس طرح کنفیگر کرنا آسان ہو تو 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 پر سیٹ کریں گے تو ہر ایکسپورٹ / پر پوسٹ ہوگی، جو کہ کوئی روٹ نہیں ہے، لہذا کچھ بھی موصول نہیں ہوگا اور SDK ایکسپورٹ فیل ہونے کا لاگ دے گا جبکہ آپ کی ایپ بظاہر ٹھیک کام کر رہی ہوگی۔

Node سروس کے لیے زیرو کوڈ پاتھ پائپ لائن کو ثابت کرنے کے لیے کافی ہے:

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

ہاپس (hops) کو ترتیب سے چیک کریں، کیونکہ پہلا گیپ آپ کو بتائے گا کہ کون سا حصہ ناکام ہوا:

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 کس پروجیکٹ سے تعلق رکھتی ہے۔ اگر پراکسی لاگ میں سرگرمی کے باوجود گنتی ساکت رہے تو یہ کلیکٹر یا ClickHouse رائٹ کی طرف اشارہ ہے، لہذا docker compose logs collector کو پڑھیں۔ پراکسی لاگ میں بالکل کوئی سرگرمی نہ ہونے کا مطلب ہے کہ ایکسپورٹر کبھی انٹیک تک پہنچا ہی نہیں: غلط پورٹ، غلط پاتھ، یا مسترد شدہ کلید۔

ویب ایپ میں وہ بار بار ہونے والی ناکامیاں فی درخواست ایک قطار کے بجائے ایک انسیڈنٹ کے طور پر پہنچتی ہیں۔ Superlog آنے والے سگنلز کے فنگر پرنٹس لیتا ہے اور مماثل سگنلز کو گروپ کرتا ہے، یہی فرق ہے ان باکس میں 4000 ایک جیسے ایررز ہونے اور ایک صفحے پر ایک انسیڈنٹ ہونے کے درمیان۔ اس کے بعد ایجنٹ اس گروپ پر اپنی تحقیقات لکھتا ہے۔

تحقیقات کا مرحلہ ایک ماڈل کو کال کرتا ہے، لہذا ورکر کے لیے ماڈل پرووائیڈر کا کنفیگر ہونا ضروری ہے۔ ان ویری ایبل ناموں کو کسی بیرونی تحریر کے بجائے اس کمٹ کی ہر ایپ ڈائریکٹری کے اندر موجود .env.example فائل سے لیں جسے آپ نے پن کیا ہے، کیونکہ وہ main کے ساتھ تبدیل ہوتے رہتے ہیں۔ یہی اصول GitHub اور Sentry انٹیگریشنز پر لاگو ہوتا ہے، جن کی اپنی سیٹ اپ دستاویزات docs/github-app-setup.md اور docs/sentry-app-setup.md پر موجود ہیں، اور ویب ہک پے لوڈز کی تفصیلات docs/webhooks.md میں درج ہیں۔

انٹیک کو نجی رکھیں اور ایجنٹ کو صرف پڑھنے کی حد تک محدود رکھیں

Docker بائی ڈیفالٹ کنٹینر پورٹس کو 0.0.0.0 پر پبلش کرتا ہے، اور یہ پبلش شدہ پورٹس ufw کو بائی پاس کر دیتی ہیں، کیونکہ Docker اپنے رولز کو DOCKER-USER چین میں لکھتا ہے جو ufw کے پیکٹ دیکھنے سے پہلے ہی لاگو ہو جاتے ہیں۔ پبلک IP والے VPS پر، فراہم کردہ 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 اوور رائڈ فائل سے ٹھیک کرنے کی کوشش نہ کریں جو ports کو دوبارہ ڈکلیئر کرتی ہو، کیونکہ Compose فائلز کے درمیان پورٹ لسٹس کو جوڑ دیتا ہے (concatenation) بجائے اس کے کہ انہیں تبدیل کر دے، لہذا آپ کے پاس دونوں بائنڈنگز موجود ہوں گی اور پبلک پورٹ اب بھی کھلی رہے گی۔

انٹیک کو بھی اسی احتیاط کی ضرورت ہے۔ آپ کی انٹیسٹ کی (ingest key) ہیڈر میں سفر کرتی ہے، لہذا اسے اپنے آگے TLS (ٹرانسپورٹ لیئر سیکیورٹی) کی ضرورت ہے: پراکسی سے پہلے nginx یا Caddy میں TLS کو ٹرمینیٹ کریں، یا انٹیسٹ کو نجی نیٹ ورک یا WireGuard ٹنل کے اندر رکھیں۔ 5173 پر موجود ویب ایپ ایک Vite ڈیولپمنٹ سرور ہے اور اسے انٹرنیٹ کے سامنے بالکل نہیں ہونا چاہیے۔

پھر خود ایجنٹ کی باری ہے۔ Superlog کا دعویٰ یہ ہے کہ ایجنٹ تحقیق کرتا ہے اور اصلاح تجویز کرتا ہے، اور اہم لفظ 'تجویز' ہے۔ اسے پروڈکشن کے خلاف صرف پڑھنے کی حد تک (read only) رکھیں جب تک کہ آپ اسے چند حقیقی واقعات پر کام کرتے ہوئے نہ دیکھ لیں۔ GitHub App کو صرف پڑھنے کی رسائی (read scopes) دیں اور اسے پل ریکویسٹس (pull requests) کھولنے دیں جن کا آپ جائزہ لیں۔ ایک ایسا ایجنٹ جو ٹیلی میٹری پڑھے اور پیچ (patch) لکھے، مفید ہے۔ ایک ایسا ایجنٹ جو آپ کی سروسز کو ری اسٹارٹ کر سکے، خطرے کی ایک مختلف سطح ہے، اور یہ ایک ایسا فیصلہ ہونا چاہیے جو آپ جان بوجھ کر کریں، نہ کہ کوئی ایسی ڈیفالٹ سیٹنگ جو آپ کو ورثے میں ملے۔ لاگت بھی اتنی ہی توجہ کی مستحق ہے، کیونکہ ہر تحقیق ایک ماڈل کال ہے: VPS پر ایجنٹ کے اخراجات کا بجٹ طے کریں اس سے پہلے کہ آپ اسے کسی شور مچانے والے پروڈکشن سسٹم پر لگائیں، اور ایجنٹ نے اصل میں کیا کیا اس کا ریکارڈ رکھیں تاکہ کسی حیران کن پل ریکویسٹ کے پیچھے ایک آڈٹ ٹریل موجود ہو۔

وہ ناکامیاں جن کا آپ کو سامنا ہوگا، اور ان کے نام بتانے والی سٹرنگز

• 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 ہے۔
• ایک ایکسپورٹر جو کامیابی کی اطلاع دیتا ہے جبکہ ویب ایپ خالی رہتی ہے، اس کا مطلب عام طور پر یہ ہے کہ ڈیٹا براہ راست 4318 پر کلیکٹر تک پہنچ گیا ہے، جس سے وہ پروجیکٹ سٹیمپنگ رہ جاتی ہے جو پراکسی کرتی ہے۔
• پروڈکشن انسٹالیشن میں 4101 پر Connection refused کا مطلب ہے کہ پراکسی PORT=4000 پر واپس چلی گئی ہے۔ یونٹ فائل میں PORT کو واضح طور پر سیٹ کریں۔
• docker compose ps میں 0.0.0.0:8123 ظاہر ہونے کا مطلب ہے کہ آپ کی لوپ بیک بائنڈنگز لاگو نہیں ہو رہی ہیں۔ docker compose config چلائیں اور ریزولو شدہ پورٹس کو پڑھیں۔

Flawless، HyperProbe، اور Superlog کا مقام

یہ زمرہ ابھی نیا ہے، اور اس میں موجود ٹولز اس بات پر منقسم ہیں کہ ایجنٹ کو کن چیزوں تک رسائی کی اجازت ہے۔ Flawless ایک اوپن سورس AI SRE (سائٹ ریلائبلٹی انجینئرنگ) ٹول ہے جو Kubernetes کے لیے بنایا گیا ہے۔ یہ پائپ لائن کا کنٹرول سنبھالنے کے بجائے موجودہ Prometheus، Loki اور Grafana اسٹیک سے ڈیٹا پڑھتا ہے۔ HyperProbe اس کے برعکس کام کرتا ہے: یہ ایک ہوسٹڈ پروڈکٹ ہے، جو اگست 2026 تک کلوزڈ سورس ہے، اور یہ چلتے ہوئے پروسیس کے اندر read-only پروبز لگاتا ہے تاکہ متغیر حالت (variable state) کو کیپچر کر سکے اور اس حالت کو MCP (ماڈل کانٹیکسٹ پروٹوکول) کے ذریعے اسسٹنٹ تک پہنچا سکے۔

Superlog ان دونوں کے درمیان واقع ہے۔ یہ پائپ لائن کو شروع سے آخر تک مکمل کنٹرول کرتا ہے، OTLP انٹیک سے لے کر ClickHouse اسٹوریج تک، اور یہ ایجنٹ کو فکس (fix) کرنے کے مرحلے کے بجائے ٹریاج (triage) کے مرحلے پر رکھتا ہے۔ یہی ڈیزائن اس بات کی وجہ ہے کہ اسے خود ہوسٹ کرنا (self-hosting) ایک انفراسٹرکچر کا فیصلہ ہے، نہ کہ کوئی ایسا کنٹینر جسے آپ بھول جائیں۔ جب آپ Superlog چلاتے ہیں، تو آپ دراصل ایک کالم اسٹور (column store) چلا رہے ہوتے ہیں، اور اسے اسی دیکھ بھال کی ضرورت ہوتی ہے جو آپ کی ملکیت میں موجود کسی بھی دوسرے ڈیٹا بیس کو درکار ہوتی ہے۔

FAQ

خود میزبانی (self-hosted) Superlog کے لیے کتنی RAM درکار ہے؟

کم ingest volume والے سنگل نوڈ کے لیے 8 GB RAM، 4 vCPU اور 40 GB ڈسک کا منصوبہ بنائیں۔ یہ اسٹیک Postgres، ClickHouse، ایک OpenTelemetry collector اور چار Node پروسیسز پر مشتمل ہے، اور ClickHouse کو اضافی میموری کی ضرورت ہوتی ہے۔ 1 GB یا 2 GB کا VPS کافی نہیں ہے: pnpm install بذات خود بھاری ہے، اور لوڈ بڑھنے پر ClickHouse کو kernel کا out of memory killer بند کر دیتا ہے۔ کسی بھی شائع شدہ اعداد و شمار پر بھروسہ کرنے کے بجائے، بشمول اس کے، اپنے اعداد و شمار کو docker stats --no-stream اور free -m کے ذریعے خود پیمائش کریں۔

مجھے اپنا OTLP exporter کس port پر پوائنٹ کرنا چاہیے؟

Superlog کا intake proxy، جسے README میں http://localhost:4101 پر رکھا گیا ہے۔ یہ /v1/traces، /v1/logs اور /v1/metrics کو سرو کرتا ہے، اور یہ آپ کے پروجیکٹ کی ingest key کے ساتھ تصدیق کرتا ہے جو x-api-key ہیڈر یا authorization: bearer ہیڈر سے لی جاتی ہے۔ Port 4318 اس کے نیچے موجود OpenTelemetry collector ہے، اور براہ راست وہاں ایکسپورٹ کرنے سے پراکسی بائی پاس ہو جاتی ہے، جو کہ وہ جزو ہے جو آپ کے ڈیٹا پر پروجیکٹ آئی ڈی ثبت کرتا ہے۔ جب PORT سیٹ نہ ہو تو پراکسی port 4000 پر واپس آ جاتی ہے، لہذا 4101 فرض کرنے سے پہلے ss -lntp چلائیں اور تصدیق کریں کہ یہ کس پر bind ہوا ہے۔

کیا Superlog، Uptime Kuma یا Zabbix کی جگہ لے سکتا ہے؟

نہیں۔ Uptime Kuma جواب دیتا ہے کہ آیا کوئی اینڈ پوائنٹ آپ کے نیٹ ورک کے باہر سے جواب دے رہا ہے، اور Zabbix آپ کے مقرر کردہ تھریش ہولڈز کے خلاف ہوسٹ اور سروس میٹرکس کی نگرانی کرتا ہے۔ Superlog ان ٹریسز، لاگز اور میٹرکس کو استعمال کرتا ہے جو آپ کی ایپلی کیشنز خارج کرتی ہیں اور بار بار ہونے والی خرابیوں کو واقعات (incidents) میں گروپ کرتی ہے۔ اس کے ساتھ ایک بیرونی uptime probe ضرور رکھیں، کیونکہ کہیں اور چلنے والا پروب تب بھی رپورٹ کرتا ہے جب وہ مشین خود بند ہو جائے جس پر آپ کی ٹیلی میٹری پائپ لائن چل رہی ہے۔

کیا Superlog ایجنٹ میرے پروڈکشن سسٹمز کو تبدیل کر سکتا ہے؟

صرف ان اجازتوں کے ذریعے جو آپ اسے دیتے ہیں۔ اس کی آؤٹ پٹ ایک تحقیق اور مجوزہ تبدیلی ہوتی ہے جس کا جائزہ ایک انسان لیتا ہے۔ GitHub App کو شروع میں صرف read scopes اور pull requests تک محدود رکھیں، اور ورکر کے پاس موجود کسی بھی اسناد (credentials) کو صرف پڑھنے تک محدود رکھیں۔ پروڈکشن تک write access دینے کا فیصلہ الگ اور سوچ سمجھ کر کریں، کیونکہ ایک ایسا ایجنٹ جو سروسز کو ری اسٹارٹ کر سکتا ہے، اس ایجنٹ سے کہیں زیادہ بڑی ذمہ داری ہے جو صرف ٹیلی میٹری پڑھتا ہے اور جائزے کے لیے پیچ لکھتا ہے۔

کیا مجھے کسی کمٹ (commit) کو پن (pin) کرنا چاہیے یا main برانچ کو ٹریک کرنا چاہیے؟

کسی کمٹ کو پن کریں۔ اگست 2026 تک ریپوزٹری میں کوئی ریلیز ٹیگز موجود نہیں ہیں، لہذا main ہی واحد متحرک ہدف ہے اور اس میں ہفتے میں کئی کمٹس ہوتے ہیں۔ جس SHA کو آپ نے ٹیسٹ کیا ہے اسے ریکارڈ کریں، اسی کو ڈیپلائے کریں، اور آگے بڑھنے سے پہلے diff کو پڑھیں۔ .env.example فائلیں، جو ہر ایپ کے لیے الگ ہوتی ہیں، کسی بھی اپ ڈیٹ کے بعد نئی درکار ویری ایبلز کو دیکھنے کے لیے پہلی جگہ ہیں۔ git log --oneline <old-sha>..main جائزہ لینے کا عمل ہے۔