Superlog स्वतःच्या सर्व्हरवर कसे इन्स्टॉल करावे?

Superlog self-hosting मध्ये नक्की काय इन्स्टॉल होते

Superlog स्वतःच्या सर्व्हरवर चालवण्यासाठी तुम्ही रिपॉझिटरी क्लोन करता, Docker Compose वापरून Postgres, ClickHouse आणि OpenTelemetry collector सुरू करता, एक डेटाबेस मायग्रेशन रन करता आणि त्यानंतर चार Node सेवा सोर्स कोडवरून सुरू करता. तुमचे ॲप्लिकेशन्स OTLP (OpenTelemetry protocol) ट्रेसेस, लॉग्स आणि मेट्रिक्स एका इनटेक पोर्टवर पाठवतात. Superlog त्यांचे फिंगरप्रिंट्स तयार करते, पुनरावृत्ती होणाऱ्या नोंदींना एकाच इन्सिडेंटमध्ये गटबद्ध करते आणि एक एजंट ट्रायजची पहिली फेरी पूर्ण करतो. हे इन्स्टॉलेशन पूर्ण व्हायला एक दुपार लागते. सुरू करण्यापूर्वी सिस्टिमचा आकार (footprint) आणि मर्यादा (limits) वाचणे महत्त्वाचे आहे.

Superlog हे Apache 2.0 लायसन्स अंतर्गत उपलब्ध आहे आणि ते github.com/superloglabs/superlog येथे आहे. ऑगस्ट 2026 पर्यंत, याला सुमारे 1.2k स्टार्स आहेत, main वर अंदाजे 460 कमिट्स आहेत आणि एकही रिलीज टॅग नाही. या शेवटच्या मुद्द्यामुळे इन्स्टॉलेशनवर परिणाम होतो: git checkout v1.0.0 वर चेकआउट करण्यासाठी काहीही उपलब्ध नसल्यामुळे, तुम्हाला स्वतःला एक कमिट पिन करावी लागते किंवा तुम्ही ज्या दिवशी क्लोन केले त्या दिवशी main वर जे काही उपलब्ध असेल तेच रन करावे लागते.

Superlog अशी कोणती उत्तरे देते जी Uptime Kuma आणि Langfuse देत नाहीत

Self-hosted मॉनिटरिंग टूल्स बाहेरून पाहताना सारखीच वाटतात. प्रत्यक्षात तसे नसते आणि चुकीचे टूल वापरल्यास कोणत्याही फायद्याशिवाय सर्व्हरची संसाधने वाया जातात.

• Uptime Kuma तुमच्या एंडपॉइंट्सची बाहेरून तपासणी करते आणि एकाच प्रश्नाचे उत्तर देते: सेवा सुरू आहे का?
• Zabbix Ubuntu 24.04 वरील होस्ट आणि सेवांचे निरीक्षण करते, ज्यामध्ये तुम्ही सेट केलेल्या मर्यादेनुसार CPU, मेमरी, डिस्क आणि सेवेची स्थिती तपासली जाते.
• Langfuse LLM कॉल्सचा मागोवा घेते, ज्यामध्ये प्रत्येक प्रॉम्प्ट, मॉडेल, टोकन्स, लॅटन्सी आणि खर्च यांची नोंद केली जाते.
• Superlog तुमच्या सामान्य सेवांकडून मिळणारी टेलिमेट्री घेते आणि वारंवार होणाऱ्या अपयशांचे रूपांतर इन्सिडेंट्समध्ये करते.

Superlog एका वेगळ्या प्रश्नावर लक्ष केंद्रित करते: काहीतरी बिघडले आहे, तर ते काय बिघडले आणि का? LLM कॉल्सबद्दल याचे कोणतेही मत नाही आणि हे बाहेरून तुमच्या सर्व्हरची तपासणी करत नाही. हे तुमच्या सामान्य ॲप्लिकेशन कोडमधून OTLP डेटा स्वीकारते आणि ट्रायज (triage) टप्प्यावर एक एजंट तैनात करते, जे काम ऑन-कॉल असलेल्या व्यक्तीला पहिल्या टप्प्यावर करावे लागते.

VPS बजेटच्या दृष्टीने महत्त्वाचा फरक म्हणजे स्टोरेज. Uptime Kuma 1 GB RAM वर सहज चालते कारण ते फक्त काही हजार चेक रिझल्ट्स साठवते. Superlog मध्ये कॉलम स्टोअर असते, कारण टेलिमेट्री एकदा लिहिली जाते आणि नंतर लाखो ओळींमधून वेळेच्या मर्यादेनुसार क्वेरी केली जाते. यासाठीच ClickHouse वापरले जाते, जे Postgres करू शकत नाही. Postgres अजूनही स्टॅकमध्ये असते, जे लहान रिलेशनल डेटा जसे की प्रोजेक्ट्स, युजर्स, इन्सिडेंट्स आणि इनजेस्ट कीज साठवण्याचे काम करते.

docker compose up -d नक्की काय सुरू करते?

तीन कंटेनर्स, आणि त्यापैकी एकही Superlog नाही. ज्यांना एका कमांडमध्ये इन्स्टॉलेशनची अपेक्षा असते, त्यांना हे पाहून आश्चर्य वाटते.

• postgres:16, होस्ट पोर्ट 5434 वर पब्लिश केलेले
• clickhouse/clickhouse-server:26.1, HTTP साठी 8123 आणि नेटिव्ह प्रोटोकॉलसाठी 9000 वर
• otel/opentelemetry-collector-contrib:0.150.1, gRPC साठी 4317 आणि HTTP वर OTLP साठी 4318 वर

Superlog ॲप्लिकेशन्स होस्टवर, सोर्स कोडपासून, pnpm dev द्वारे सुरू केली जातात. ऑगस्ट 2026 पर्यंत रिपॉझिटरीमध्ये कोणतीही प्रोडक्शन compose फाईल उपलब्ध नाही, त्यामुळे दीर्घकाळ चालणाऱ्या इन्स्टॉलेशनसाठी तुम्हाला प्रत्येक ॲपच्या start स्क्रिप्टभोवती स्वतःचे systemd युनिट्स तयार करावे लागतील, किंवा ट्रीमध्ये दिलेल्या प्रति-ॲप Dockerfiles वापरावे लागतील.

एका स्पॅनचा (span) मार्ग लक्षात ठेवा, कारण खालील प्रत्येक त्रुटी त्या मार्गातील एका टप्प्यावर खंड पडल्यामुळे होते. तुमचे ॲप Superlog इनटेक प्रॉक्सीकडे OTLP पोस्ट करते. प्रॉक्सी तुमच्या इनजेस्ट की (ingest key) द्वारे विनंती प्रमाणित करते, त्यावर प्रोजेक्ट आयडी (project id) स्टॅम्प करते आणि ती कलेक्टरकडे फॉरवर्ड करते. कलेक्टर क्लायंटने सेट करण्याचा प्रयत्न केलेले कोणतेही superlog.* ॲट्रिब्युट्स काढून टाकतो, प्रॉक्सीने दिलेल्या हेडरमधून superlog.project_id जोडतो, बॅच तयार करतो आणि ClickHouse मध्ये लिहितो. त्यानंतर वेब ॲप आणि API हे ClickHouse मधून टेलिमेट्री आणि इतर सर्व माहिती Postgres मधून वाचतात.

ते ॲट्रिब्युट स्ट्रिपिंग (attribute stripping) हे केवळ सजावट नसून एक वास्तविक मल्टी-टेनन्सी नियंत्रण आहे. त्याशिवाय, ज्याच्याकडे एक वैध इनजेस्ट की आहे, तो स्वतः superlog.project_id सेट करून दुसऱ्या प्रोजेक्टच्या डेटामध्ये लिहू शकला असता.

VPS चा आकार किती असावा?

कमी ingest व्हॉल्यूम असलेल्या सिंगल नोड इन्स्टॉलसाठी 4 vCPU, 8 GB RAM आणि 40 GB SSD चे नियोजन करा. हे केवळ नियोजनासाठीचे किमान परिमाण आहे, मोजमाप नाही. त्यामुळे याला सुरुवातीचा आकार समजा आणि तुमच्या ट्रॅफिकनुसार त्याची पडताळणी करा.

मेमरी चार ठिकाणी वापरली जाते. ClickHouse हे मुबलक RAM असलेल्या मशीनसाठी बनवलेले आहे आणि त्याचे डिफॉल्ट्स हेच गृहीत धरतात. Postgres 16 येथे कमी मेमरी वापरते, कारण ते टेलिमेट्रीऐवजी मेटाडेटा साठवते. कलेक्टरचा वापरही मर्यादित आहे. चार 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"

कमी व्हॉल्यूम असताना, म्हणजे काही सेवा प्रति मिनिट काहीशे स्पॅन्स पाठवत असताना, बॉक्स शांत असतो आणि ClickHouse बहुतेक वेळ आयडल असतो. ज्या लोडमुळे समस्या निर्माण होते तो म्हणजे 'बर्स्ट' (burst): एका चुकीच्या डिप्लॉयमुळे प्रति मिनिट हजारो सारख्याच त्रुटी निर्माण होणे. फिंगरप्रिंटिंगमुळे त्या सर्व त्रुटी वाचकांसाठी एकाच घटनेत रूपांतरित होतात, परंतु ClickHouse तरीही त्यातील प्रत्येक ओळ (row) लिहित असतो.

रिटेन्शन (Retention) तुम्ही ठरवायचे आहे. कलेक्टरचा ClickHouse एक्स्पोर्टर टेबल्स तयार करतो, जसे की otel_traces, otel_logs आणि प्रत्येक मेट्रिक प्रकारासाठी एक टेबल. जर infra/collector/config.yaml मधील कॉन्फिगरेशनमध्ये 'time to live' सेट केले असेल, तरच ते लागू होते. कोणतीही गोष्ट आपोआप एक्सपायर होत नाही, त्यामुळे जर तुम्ही नियोजन केले नाही, तर व्यस्त महिन्याभरात डिस्क पूर्ण भरू शकते.

पिन केलेल्या कमिटवरून इन्स्टॉल करा

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

पुढे, टूलचेन:

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 म्हणजे सर्व काही तयार आहे असे मानण्याऐवजी हेल्थ चेकची वाट पहा. 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

पोर्टची नोंद घ्या: 5432 नाही, तर 5434. compose फाईल Postgres ला 5434 वर पब्लिश करते जेणेकरून ते होस्टवर आधीच इन्स्टॉल असलेल्या Postgres सोबत क्लॅश होणार नाही, आणि ॲपच्या .env.example फाईल्स DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog सह जुळतात. जर तुम्ही आधीच Postgres चालणाऱ्या सर्व्हरवर मायग्रेशन 5432 वर पॉइंट केले, तर तुम्हाला एकतर 'refused connection' मिळेल किंवा त्याहून वाईट म्हणजे चुकीच्या डेटाबेसवर मायग्रेशन लागू होईल.

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 वर असते.

कोणत्याही गोष्टीला पॉइंट करण्यापूर्वी नक्की कोणत्या पोर्टवर बाइंडिंग झाले आहे ते तपासा:

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 पर्यंत पोहोचत नाही.

मानक environment variables वापरून कोणताही OpenTelemetry SDK इनटेककडे निर्देशित करा:

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

आता मुद्दाम काहीतरी बिघडवा. कोणताही राउट जो त्रुटी (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 कोणत्या प्रोजेक्टची आहे ते तपासा. जर प्रॉक्सी लॉगमध्ये हालचाल असूनही संख्या स्थिर असेल, तर ते कलेक्टर किंवा ClickHouse राइटमधील समस्या दर्शवते, म्हणून docker compose logs collector वाचा. प्रॉक्सी लॉगमध्ये कोणतीही हालचाल नसल्यास, याचा अर्थ एक्सपोर्टर इनटेकपर्यंत पोहोचलाच नाही: चुकीचा पोर्ट, चुकीचा पाथ किंवा नाकारलेली की.

वेब ॲपमध्ये, अशा वारंवार होणाऱ्या त्रुटी प्रत्येक विनंतीसाठी एक स्वतंत्र ओळ न येता, एका इन्सिडेंटच्या स्वरूपात येतात. Superlog येणाऱ्या सिग्नलचे फिंगरप्रिंट्स घेते आणि जुळणाऱ्या सिग्नलना एकत्रित करते. यामुळे इनबॉक्समध्ये 4,000 सारख्याच त्रुटी असण्याऐवजी, एका पानावर एकच इन्सिडेंट दिसतो. त्यानंतर एजंट त्या ग्रुपवर आपली तपासणी (investigation) लिहितो.

तपासणीची पायरी एका मॉडेलला कॉल करते, म्हणून वर्करकडे मॉडेल प्रोव्हायडर कॉन्फिगर केलेले असणे आवश्यक आहे. त्या व्हेरिएबलची नावे कोणत्याही बाह्य दस्तऐवजातून घेण्याऐवजी, तुम्ही पिन केलेल्या कमिटमधील प्रत्येक ॲप डिरेक्टरीमधील .env.example फाईलमधून घ्या, कारण ती main नुसार बदलतात. हेच GitHub आणि Sentry इंटिग्रेशन्सना लागू होते, ज्यांची स्वतःची सेटअप कागदपत्रे docs/github-app-setup.md आणि docs/sentry-app-setup.md वर उपलब्ध आहेत, आणि वेबहूक पेलोड्स docs/webhooks.md मध्ये दस्तऐवजीकरण केलेले आहेत.

इनटेक खाजगी ठेवा आणि एजंटला 'read-only' ठेवा

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 फाईल्समधील पोर्ट लिस्ट बदलण्याऐवजी एकत्र जोडते (concatenate). यामुळे तुम्हाला दोन्ही बाइंडिंग्ज मिळतील आणि सार्वजनिक पोर्ट अजूनही उघडाच राहील.

इनटेकसाठीही अशीच काळजी घेणे आवश्यक आहे. तुमची इनजेस्ट की (ingest key) हेडरमध्ये प्रवास करते, त्यामुळे त्याआधी TLS (transport layer security) असणे आवश्यक आहे: प्रॉक्सीच्या आधी nginx किंवा Caddy मध्ये TLS टर्मिनेट करा, किंवा इनजेस्टला खाजगी नेटवर्क किंवा WireGuard टनेलमध्ये ठेवा. 5173 वरील वेब ॲप हे Vite डेव्हलपमेंट सर्व्हर आहे आणि त्याचा इंटरनेटशी कोणताही संबंध नसावा.

आता एजंटबद्दल. Superlog चा मुख्य उद्देश असा आहे की एजंट तपासणी करतो आणि दुरुस्ती सुचवतो, आणि येथे 'सुचवणे' हा शब्द महत्त्वाचा आहे. काही वास्तविक घटनांवर तो कसा काम करतो हे पाहिल्याशिवाय त्याला प्रोडक्शनवर 'read-only' ठेवा. GitHub App ला 'read' स्कोप द्या आणि त्याला पुल रिक्वेस्ट्स (pull requests) उघडू द्या, ज्या तुम्ही तपासा. जो एजंट टेलिमेट्री वाचतो आणि पॅच लिहितो तो उपयुक्त असतो. जो एजंट तुमच्या सेवा रीस्टार्ट करू शकतो, तो वेगळ्या स्तराचा धोका आहे. हा निर्णय तुम्ही जाणीवपूर्वक घेतला पाहिजे, तो डीफॉल्ट म्हणून स्वीकारू नका. खर्चाकडेही तितकेच लक्ष देणे आवश्यक आहे, कारण प्रत्येक तपासणी ही एक मॉडेल कॉल असते: तुम्ही त्याला गोंधळलेल्या प्रोडक्शन सिस्टिमवर वापरण्यापूर्वी 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 हे Kubernetes साठी बनवलेले एक open source AI SRE (site reliability engineering) साधन आहे. ते पाइपलाइन स्वतः नियंत्रित करण्याऐवजी विद्यमान Prometheus, Loki आणि Grafana स्टॅकवरून माहिती वाचते. HyperProbe याच्या उलट काम करते: हे एक hosted उत्पादन आहे (ऑगस्ट 2026 पर्यंत closed source). हे चालू असलेल्या process मध्ये read-only probes टाकते, जेणेकरून variable state कॅप्चर करता येईल आणि MCP (model context protocol) द्वारे ती स्थिती एका असिस्टंटला उपलब्ध करून दिली जाईल.

Superlog या दोघांच्या मध्ये येते. हे OTLP intake पासून ClickHouse स्टोरेजपर्यंत संपूर्ण पाइपलाइन स्वतः नियंत्रित करते आणि एजंटला fix करण्याच्या टप्प्यावर न ठेवता triage करण्याच्या टप्प्यावर ठेवते. याच रचनेमुळे Superlog चे self-hosting करणे हा एक पायाभूत सुविधांचा (infrastructure) निर्णय ठरतो, केवळ एक कंटेनर म्हणून याकडे दुर्लक्ष करता येत नाही. एकदा तुम्ही Superlog चालवले की, तुम्ही एक column store चालवत असता आणि इतर कोणत्याही database प्रमाणेच याची काळजी घेणे आवश्यक असते.

FAQ

self-hosted Superlog साठी किती RAM आवश्यक आहे?

कमी ingest volume असलेल्या सिंगल नोडसाठी 8 GB RAM, 4 vCPU आणि 40 GB डिस्कचे नियोजन करा. या स्टॅकमध्ये Postgres, ClickHouse, OpenTelemetry collector आणि चार Node प्रोसेस असतात, आणि ClickHouse ला अतिरिक्त मेमरीची (headroom) गरज असते. 1 GB किंवा 2 GB चा VPS पुरेसा नाही: pnpm install स्वतःच खूप मेमरी वापरते आणि लोड वाढल्यावर ClickHouse ला कर्नलच्या out of memory killer द्वारे बंद केले जाते. कोणत्याही प्रकाशित आकड्यांवर विश्वास ठेवण्यापेक्षा docker stats --no-stream आणि free -m वापरून स्वतःची मोजमापे घ्या.

माझ्या OTLP exporter ला मी कोणत्या पोर्टवर पॉइंट करू?

Superlog intake proxy ला, जो README नुसार http://localhost:4101 वर असतो. तो /v1/traces, /v1/logs आणि /v1/metrics ला सर्व्ह करतो आणि तुमच्या प्रोजेक्टची ingest key, जी x-api-key हेडर किंवा authorization: bearer हेडरमधून घेतली जाते, त्याद्वारे ऑथेंटिकेशन करतो. पोर्ट 4318 हा खालील OpenTelemetry collector चा आहे आणि तिथे थेट एक्सपोर्ट केल्यास प्रॉक्सीला वगळले जाते, जो डेटावर तुमचा प्रोजेक्ट आयडी स्टॅम्प करण्याचे काम करतो. जेव्हा PORT सेट केलेले नसते तेव्हा प्रॉक्सी पोर्ट 4000 वर परत जातो, म्हणून 4101 गृहीत धरण्यापूर्वी ss -lntp चालवून तो कोणत्या पोर्टवर bound झाला आहे ते तपासा.

Superlog हे Uptime Kuma किंवा Zabbix ला रिप्लेस करते का?

नाही. Uptime Kuma तुमच्या नेटवर्कच्या बाहेरून एंडपॉइंट प्रतिसाद देतो का हे तपासते, तर Zabbix तुम्ही सेट केलेल्या मर्यादेनुसार होस्ट आणि सर्व्हिस मेट्रिक्सवर लक्ष ठेवते. Superlog तुमच्या ॲप्लिकेशन्सद्वारे उत्सर्जित होणारे ट्रेसेस, लॉग्स आणि मेट्रिक्स गोळा करते आणि वारंवार होणाऱ्या त्रुटींचे incidents मध्ये रूपांतर करते. त्यासोबत एक बाह्य uptime probe ठेवा, कारण जर तुमची टेलिमेट्री पाइपलाइन असलेला सर्व्हरच बंद पडला, तर बाहेरून चालणारा प्रोबच तुम्हाला अहवाल देऊ शकेल.

Superlog एजंट माझ्या प्रोडक्शन सिस्टममध्ये बदल करू शकतो का?

केवळ तुम्ही दिलेल्या परवानग्यांच्या मर्यादेतच. त्याचे आउटपुट हे एक तपासणी आणि प्रस्तावित बदल असते, ज्याचे पुनरावलोकन माणूस करतो. सुरुवातीला GitHub App ला फक्त read scopes आणि pull requests ची परवानगी द्या, आणि वर्करकडे असलेली क्रेडेन्शियल्स फक्त वाचण्यासाठी (read-only) मर्यादित ठेवा. प्रोडक्शनमध्ये write access देणे हा एक स्वतंत्र आणि विचारपूर्वक घेतलेला निर्णय असावा, कारण सेवा रीस्टार्ट करू शकणारा एजंट हा केवळ टेलिमेट्री वाचून पॅच सुचवणाऱ्या एजंटपेक्षा अधिक जोखमीचा असतो.

मी कमिट पिन करावी की main ट्रॅक करावे?

कमिट पिन करा. ऑगस्ट 2026 पर्यंत रिपॉझिटरीमध्ये कोणतेही release tags नाहीत, त्यामुळे main हाच एकमेव पर्याय आहे जो सतत बदलत असतो आणि त्यात आठवड्याला अनेक कमिट्स होतात. तुम्ही टेस्ट केलेली SHA नोंदवून ठेवा, तीच डिप्लॉय करा आणि पुढे जाण्यापूर्वी diff वाचा. git log --oneline <old-sha>..main हे पुनरावलोकनासाठी आहे आणि कोणत्याही अपडेटनंतर नवीन आवश्यक व्हेरिएबल्स शोधण्यासाठी प्रति-ॲप .env.example फाइल्स हे पहिले ठिकाण आहे.