ద్వారా Matt Connor 2026-08-06 · అప్‌డేట్ చేయబడింది 2026-08-13

Superlog ను మీ సొంత VPS లో self-host చేయడం ఎలా?

Q: నా OTLP exporter ను ఏ port కు పంపాలి?

README లో పేర్కొన్న విధంగా Superlog intake proxy ని http://localhost:4101 వద్ద ఉంచండి. ఇది /v1/traces, /v1/logs మరియు /v1/metrics లను అందిస్తుంది, మరియు ఇది x-api-key header లేదా authorization: bearer header నుండి తీసుకున్న మీ ప్రాజెక్ట్ ingest key తో authentication చేస్తుంది. Port 4318 అనేది లోపల ఉన్న OpenTelemetry collector, అక్కడికి నేరుగా export చేస్తే proxy ని దాటవేస్తుంది; కానీ మీ ప్రాజెక్ట్ id ని డేటాపై ముద్రించేది ఈ proxy మాత్రమే. PORT సెట్ చేయనప్పుడు proxy పోర్ట్ 4000 కు మారుతుంది, కాబట్టి 4101 అని అనుకునే ముందు ss -lntp రన్ చేసి అది దేనికి bound అయిందో నిర్ధారించుకోండి.

Q: Superlog, Uptime Kuma లేదా Zabbix కు ప్రత్యామ్నాయమా?

కాదు. మీ నెట్వర్క్ వెలుపల నుండి ఒక endpoint స్పందిస్తుందో లేదో Uptime Kuma చెబుతుంది, మరియు మీరు సెట్ చేసిన పరిమితులకు అనుగుణంగా host మరియు service metrics ను Zabbix పర్యవేక్షిస్తుంది. మీ అప్లికేషన్లు పంపే traces, logs మరియు metrics ను Superlog స్వీకరించి, పదేపదే వచ్చే వైఫల్యాలను incidents గా సమూహపరుస్తుంది. దీనితో పాటు ఒక external uptime probe ను ఉంచండి, ఎందుకంటే మీ telemetry pipeline ఉన్న సర్వర్ డౌన్ అయినప్పుడు, బయట నడుస్తున్న probe మాత్రమే ఆ విషయాన్ని తెలియజేస్తుంది.

Q: Superlog agent నా production సిస్టమ్స్ను మార్చగలదా?

మీరు ఇచ్చే అనుమతుల ద్వారా మాత్రమే అది సాధ్యం. దీని అవుట్పుట్ ఒక విశ్లేషణ మరియు మానవ సమీక్షకు పంపే ప్రతిపాదిత మార్పు మాత్రమే. మొదట్లో GitHub App కు read scopes మరియు pull requests అనుమతులు మాత్రమే ఇవ్వండి, మరియు worker కు ఉండే credentials ను కేవలం reading కే పరిమితం చేయండి. Production కు write access ఇవ్వడం అనేది ఒక ప్రత్యేక నిర్ణయం; ఎందుకంటే telemetry చదివి patch రాసే agent కంటే, సేవలను restart చేయగల agent కు ఎక్కువ బాధ్యత ఉంటుంది.

Superlog ను self-host చేయడానికి Docker Compose ద్వారా Postgres, ClickHouse మరియు OTLP collector లను ఎలా సెటప్ చేయాలో తెలుసుకోండి. దీనివల్ల కలిగే ప్రయోజనాలు మరియు పరిమితులను ఇక్కడ

Superlog ను self-host చేసినప్పుడు వాస్తవానికి ఏమి ఇన్‌స్టాల్ అవుతుంది

Superlog ను self-host చేయడానికి మీరు repository ని clone చేయాలి, Docker Compose తో Postgres, ClickHouse మరియు OpenTelemetry collector లను సిద్ధం చేయాలి, ఒక database migration ను రన్ చేయాలి, ఆపై source నుండి నాలుగు Node సేవలను ప్రారంభించాలి. మీ అప్లికేషన్లు OTLP (OpenTelemetry protocol) traces, logs మరియు metrics ను ఒక intake port కు పంపుతాయి. Superlog వాటిని fingerprint చేస్తుంది, పునరావృతమయ్యే వాటిని ఒకే incident గా సమూహపరుస్తుంది, మరియు ఒక agent triage యొక్క మొదటి దశను పూర్తి చేస్తుంది. ఈ ఇన్‌స్టాలేషన్ పూర్తి కావడానికి ఒక మధ్యాహ్నం సమయం పడుతుంది. మీరు ప్రారంభించే ముందు దాని footprint మరియు వాస్తవిక పరిమితుల గురించి చదవడం మంచిది.

Superlog అనేది Apache 2.0 లైసెన్స్ కలిగి ఉంది మరియు github.com/superloglabs/superlog లో అందుబాటులో ఉంది. ఆగస్టు 2026 నాటికి, దీనికి సుమారు 1.2k stars ఉన్నాయి, main లో దాదాపు 460 commits ఉన్నాయి, మరియు ఎటువంటి release tags లేవు. ఈ చివరి అంశం ఇన్‌స్టాలేషన్‌ను ప్రభావితం చేస్తుంది: git checkout v1.0.0 లో checkout చేయడానికి ఏమీ లేదు, కాబట్టి మీరు ఒక commit ను మీరే pin చేసుకోవాలి లేదా మీరు clone చేసిన రోజున main లో ఏది ఉంటే దానినే రన్ చేయాలి.

Uptime Kuma మరియు Langfuse అందించని సమాచారాన్ని Superlog ఎలా అందిస్తుంది

Self-hosted మానిటరింగ్ టూల్స్ పైకి ఒకేలా కనిపిస్తాయి. కానీ అవి వేర్వేరు, తప్పు టూల్‌ను ఎంచుకోవడం వల్ల సర్వర్ వనరులు వృథా అవుతాయి.

Uptime Kuma మీ ఎండ్‌పాయింట్‌లను బయటి నుంచి పరిశీలిస్తుంది మరియు అది పనిచేస్తుందా లేదా అనే ఒకే ప్రశ్నకు సమాధానమిస్తుంది.
Zabbix మీ Ubuntu 24.04 హోస్ట్‌లు మరియు సర్వీసులను పర్యవేక్షిస్తుంది, మీరు సెట్ చేసిన పరిమితులకు అనుగుణంగా CPU, మెమరీ, డిస్క్ మరియు సర్వీస్ స్థితిని తనిఖీ చేస్తుంది.
Langfuse LLM కాల్‌లను ట్రేస్ చేస్తుంది, ప్రతి కాల్‌కు సంబంధించిన ప్రాంప్ట్, మోడల్, టోకెన్లు, లేటెన్సీ మరియు ఖర్చును రికార్డ్ చేస్తుంది.
Superlog మీ సాధారణ సర్వీసులు ఇప్పటికే పంపే టెలిమెట్రీని తీసుకుని, పదేపదే జరిగే వైఫల్యాలను ఇన్సిడెంట్స్‌గా మారుస్తుంది.

Superlog ఒక ప్రత్యేకమైన ప్రశ్నకు సమాధానమిస్తుంది: ఏదో విఫలమైంది, అది ఏమిటి మరియు ఎందుకు విఫలమైంది. దీనికి LLM కాల్‌లపై ఎటువంటి అభిప్రాయం లేదు మరియు ఇది బయటి నుంచి మిమ్మల్ని ప్రోబ్ చేయదు. ఇది మీ అప్లికేషన్ కోడ్ నుండి OTLPని స్వీకరిస్తుంది మరియు ట్రయాజ్ దశలో ఒక ఏజెంట్‌ను ఉంచుతుంది, ఇది ఆన్-కాల్‌లో ఉన్న వ్యక్తి చేసే మొదటి పని.

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 మరియు OTLP over HTTP కోసం 4318 పోర్టులలో

Superlog అప్లికేషన్లు హోస్ట్ మెషీన్ మీద, సోర్స్ కోడ్ నుండి, pnpm dev ద్వారా ప్రారంభించబడతాయి. ఆగస్టు 2026 నాటికి రిపోజిటరీలో ఎటువంటి ప్రొడక్షన్ compose ఫైల్ లేదు, కాబట్టి దీర్ఘకాలిక ఇన్‌స్టాలేషన్ కోసం మీరు ప్రతి యాప్ యొక్క start స్క్రిప్ట్ చుట్టూ మీ స్వంత systemd యూనిట్లను రూపొందించుకోవాలి, లేదా ట్రీలో అందించబడిన ప్రతి యాప్ యొక్క Dockerfiles ను ఉపయోగించాలి.

ఒక డేటా ప్యాకెట్ ప్రయాణించే మార్గాన్ని గుర్తుంచుకోండి, ఎందుకంటే కింద పేర్కొన్న ప్రతి వైఫల్యం ఆ మార్గంలోని ఏదో ఒక దశలో ఏర్పడే అంతరాయమే. మీ యాప్ OTLP డేటాను Superlog ఇన్‌టేక్ ప్రాక్సీకి పంపుతుంది. ఆ ప్రాక్సీ మీ ఇన్‌జెస్ట్ కీతో అభ్యర్థనను ప్రామాణీకరిస్తుంది (authenticate), దానికి ప్రాజెక్ట్ ఐడిని జోడిస్తుంది, మరియు దానిని కలెక్టర్‌కు ఫార్వర్డ్ చేస్తుంది. కలెక్టర్ క్లయింట్ సెట్ చేయడానికి ప్రయత్నించిన ఏవైనా superlog.* అట్రిబ్యూట్‌లను తొలగిస్తుంది, ప్రాక్సీ అందించిన హెడర్ నుండి superlog.project_id ను జోడిస్తుంది, బ్యాచ్ చేస్తుంది, మరియు ClickHouse లోకి రాస్తుంది. వెబ్ యాప్ మరియు API లు ClickHouse నుండి టెలిమెట్రీని, మిగిలిన డేటాను Postgres నుండి చదువుతాయి.

ఆ అట్రిబ్యూట్ తొలగింపు అనేది కేవలం అలంకారం కాదు, అది ఒక నిజమైన మల్టీ-టెనెన్సీ నియంత్రణ. అది లేకపోతే, ఒక చెల్లుబాటు అయ్యే ఇన్‌జెస్ట్ కీ ఉన్న ఎవరైనా స్వయంగా superlog.project_id ను సెట్ చేసి, మరొక ప్రాజెక్ట్ డేటాలోకి రాయగలరు.

VPS పరిమాణం ఎంత ఉండాలి?

తక్కువ ingest volume ఉన్న సింగిల్ నోడ్ ఇన్‌స్టాలేషన్ కోసం 4 vCPU, 8 GB RAM మరియు 40 GB SSD ఉండేలా ప్లాన్ చేసుకోండి. ఇది కేవలం ప్రాథమిక అంచనా మాత్రమే, కాబట్టి దీనిని ప్రారంభ పరిమాణంగా పరిగణించి, మీ ట్రాఫిక్ అవసరాలకు అనుగుణంగా సరిచూసుకోండి.

మెమరీ నాలుగు ప్రధాన భాగాలకు అవసరమవుతుంది. ClickHouse ఎక్కువ RAM ఉన్న మెషీన్ల కోసం రూపొందించబడింది, దాని డిఫాల్ట్ సెట్టింగ్‌లు కూడా అలాగే ఉంటాయి. Postgres 16 ఇక్కడ తక్కువ మెమరీని తీసుకుంటుంది, ఎందుకంటే ఇది టెలిమెట్రీ కంటే మెటాడేటాను మాత్రమే నిల్వ చేస్తుంది. కలెక్టర్ కూడా తక్కువ మెమరీనే వాడుతుంది. కానీ నాలుగు Node ప్రాసెస్‌లు అలా కాదు: ఒక Vite డెవలప్‌మెంట్ సర్వర్ మరియు మూడు tsx watch ప్రాసెస్‌లు ఒక్కొక్కటి వందల మెగాబైట్ల మెమరీని ఆక్రమిస్తాయి. అందుకే 2 GB RAM ఉన్న బాక్సులో pnpm dev రన్ చేయడం చాలా కష్టతరమైన పని.

డిస్క్ వినియోగం మరొక ముఖ్యమైన అంశం. ఈ monorepo లోని pnpm install, మీరు ఒక్క span ను కూడా ingest చేయకముందే AWS SDK, ClickHouse client, OpenTelemetry SDK మరియు React toolchain వంటి వాటిని డౌన్‌లోడ్ చేస్తుంది. ఆ తర్వాత మీ ట్రాఫిక్‌ను బట్టి 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 మాత్రం ప్రతి రోను (row) డేటాబేస్‌లో రాస్తూనే ఉంటుంది.

Retention పీరియడ్‌ను మీరే నిర్ణయించుకోవాలి. కలెక్టర్ యొక్క ClickHouse ఎక్స్‌పోర్టర్ టేబుళ్లను, otel_traces, otel_logs మరియు ప్రతి మెట్రిక్ రకానికి ఒక టేబుల్‌ను సృష్టిస్తుంది. infra/collector/config.yaml లోని కాన్ఫిగరేషన్‌లో సెట్ చేస్తే తప్ప, ఇది ఏ డేటాకు కూడా time to live (TTL) ను వర్తింపజేయదు. ఏదీ ఆటోమేటిక్‌గా డిలీట్ అవ్వదు కాబట్టి, మీరు ముందుగా ప్లాన్ చేసుకోకపోతే బిజీగా ఉండే నెలలో డిస్క్ నిండిపోయే అవకాశం ఉంది.

పిన్ చేసిన కమిట్ (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

పోర్ట్ గమనించండి: 5432 కాదు, 5434. హోస్ట్‌లో ఇప్పటికే ఇన్‌స్టాల్ అయి ఉన్న Postgres తో ఘర్షణ పడకుండా ఉండటానికి, compose ఫైల్ Postgres ను 5434 పోర్ట్‌పై ప్రచురిస్తుంది. అప్లికేషన్ .env.example ఫైళ్లు DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlogతో సరిపోలుతాయి. ఇప్పటికే Postgres నడుస్తున్న సర్వర్‌లో మైగ్రేషన్‌ను 5432 పోర్ట్‌కు పాయింట్ చేస్తే, కనెక్షన్ తిరస్కరించబడుతుంది లేదా తప్పు డేటాబేస్‌కు మైగ్రేషన్ వర్తించబడుతుంది.

pnpm dev, రిపోజిటరీ యొక్క Procfileలో జాబితా చేయబడిన నాలుగు ప్రాసెస్‌లను ప్రారంభిస్తుంది: api, web, worker మరియు proxy. ప్రతి ప్రాసెస్ దాని అవుట్‌పుట్‌ను tmp/logs/లోకి పంపుతుంది, కాబట్టి ఇన్‌జెస్ట్ (ingest) ప్రక్రియను పర్యవేక్షించడానికి tail -f tmp/logs/proxy.logని చూడాలి. README ప్రకారం వెబ్ యాప్ http://localhost:5173లో, API http://localhost:4100లో మరియు OTLP ఇన్‌టేక్ http://localhost:4101లో ఉంటాయి.

దేనినైనా పాయింట్ చేసే ముందు ఏది బౌండ్ (bound) అయిందో నిర్ధారించుకోండి:

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

ఇది తర్వాత ముఖ్యమైనది. ప్రాక్సీ తన స్వంత పోర్ట్‌ను PORT ఎన్విరాన్‌మెంట్ వేరియబుల్ నుండి చదువుతుంది మరియు PORT సెట్ చేయనప్పుడు 4000 పోర్ట్‌ను ఉపయోగిస్తుంది. డెవలప్‌మెంట్ స్టాక్ దీన్ని మీ కోసం సెట్ చేస్తుంది. మీరు స్వయంగా రాసే systemd యూనిట్ దీన్ని సెట్ చేయదు, కాబట్టి 4000 పోర్ట్‌పై వింటున్న ప్రాక్సీకి వ్యతిరేకంగా 4101 పోర్ట్‌ను లక్ష్యంగా చేసుకున్న ఎక్స్‌పోర్టర్, connection refused తో విఫలమవుతుంది మరియు ఎటువంటి ఇతర సూచనను ఇవ్వదు.

ఒక trace పంపండి, ఒక error ను సృష్టించండి, ఒక incident ను చూడండి

వెబ్ యాప్‌లో ఒక ప్రాజెక్ట్‌ను సృష్టించి, దాని ingest key ని కాపీ చేయండి. intake ప్రతి అభ్యర్థనను ఆ key తో ప్రామాణీకరిస్తుంది, కాబట్టి ఆ key లేకుండా పంపిన telemetry ఏదీ ClickHouse కు చేరదు.

ఏదైనా OpenTelemetry SDK ని కింది standard environment variables ఉపయోగించి 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 ఈ key ని x-api-key header నుండి చదువుతుంది, ఒకవేళ మీ exporter ను ఆ విధంగా కాన్ఫిగర్ చేయడం సులభమైతే authorization: bearer YOUR_INGEST_KEY ని కూడా అంగీకరిస్తుంది. ఇది మూడు standard OTLP paths, అంటే /v1/traces, /v1/logs మరియు /v1/metrics, అలాగే /health లపై సేవలను అందిస్తుంది.

ఒక ముఖ్యమైన పొరపాటును గమనించాలి. OTEL_EXPORTER_OTLP_ENDPOINT అనేది ఒక base URL, SDK దీనికి signal path ని కలుపుతుంది. OTEL_EXPORTER_OTLP_TRACES_ENDPOINT వంటి signal-specific variables ను ఎటువంటి path కలపకుండా, ఉన్నది ఉన్నట్లుగా ఉపయోగించాలి. ఒకవేళ signal-specific variable ను http://127.0.0.1:4101 కి సెట్ చేస్తే, ప్రతి export / కి పంపబడుతుంది. ఇది సరైన route కాదు, కాబట్టి ఏ డేటా చేరదు మరియు మీ యాప్ ఆరోగ్యంగా ఉన్నట్లు కనిపించినప్పటికీ, SDK లో export failure కనిపిస్తుంది.

Node సర్వీస్ కోసం, pipeline ని పరీక్షించడానికి zero code path సరిపోతుంది:

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

ఇప్పుడు ఉద్దేశపూర్వకంగా ఏదైనా తప్పు చేయండి. error ని ఇచ్చే ఏదైనా route సరిపోతుంది:

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

hops ను వరుసగా తనిఖీ చేయండి, ఎందుకంటే మొదటి gap ఎక్కడ ఏర్పడిందో అదే విఫలమైన భాగాన్ని సూచిస్తుంది:

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

వెబ్ యాప్‌లో ఏమీ లేనప్పుడు otel_traces లో count పెరుగుతుంటే, అది project mismatch అని అర్థం, కాబట్టి ingest key ఏ ప్రాజెక్ట్‌కు చెందినదో తనిఖీ చేయండి. proxy log లో activity ఉండి, count పెరగకపోతే, అది collector లేదా ClickHouse write లో సమస్య అని అర్థం, కాబట్టి docker compose logs collector ని చదవండి. proxy log లో ఎటువంటి activity లేకపోతే, exporter అసలు intake ని చేరుకోలేదని అర్థం: అంటే తప్పు port, తప్పు path, లేదా తిరస్కరించబడిన key కారణం కావచ్చు.

వెబ్ యాప్‌లో, ఆ పదేపదే వచ్చే failures ప్రతి అభ్యర్థనకు ఒక row లా కాకుండా, ఒకే incident గా కనిపిస్తాయి. Superlog ఇన్‌కమింగ్ సిగ్నల్స్‌ను fingerprint చేసి, సరిపోలే వాటిని గ్రూప్ చేస్తుంది. దీనివల్ల 4,000 ఒకే రకమైన errors తో inbox నిండిపోకుండా, ఒకే పేజీలో incident కనిపిస్తుంది. ఆ తర్వాత agent ఆ గ్రూప్ పైన తన విశ్లేషణను రాస్తుంది.

విశ్లేషణ దశ ఒక model ని పిలుస్తుంది, కాబట్టి worker కి ఒక model provider కాన్ఫిగర్ చేయబడి ఉండాలి. ఆ variable పేర్లను మీరు pin చేసిన commit లోని ప్రతి app directory లో ఉన్న .env.example ఫైల్ నుండి తీసుకోండి, బయట ఉన్న డాక్యుమెంటేషన్ నుండి కాదు, ఎందుకంటే అవి main తో పాటు మారుతుంటాయి. GitHub మరియు Sentry integrations కు కూడా ఇదే వర్తిస్తుంది; వాటికి సంబంధించిన setup పత్రాలు docs/github-app-setup.md మరియు docs/sentry-app-setup.md లలో ఉంటాయి, మరియు webhook payloads వివరాలు docs/webhooks.md లో డాక్యుమెంట్ చేయబడ్డాయి.

ఇన్‌టేక్‌ను ప్రైవేట్‌గా ఉంచండి మరియు ఏజెంట్‌ను రీడ్-ఓన్లీగా మార్చండి

Docker డిఫాల్ట్‌గా కంటైనర్ పోర్ట్‌లను 0.0.0.0 పై ప్రచురిస్తుంది. Docker తన సొంత రూల్స్‌ను DOCKER-USER చైన్‌లో రాస్తుంది కాబట్టి, ఈ ప్రచురించిన పోర్ట్‌లు ufw ను దాటవేస్తాయి; 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 కనిపించకూడదు. ports ని రీ-డిక్లేర్ చేసే compose ఓవర్‌రైడ్ ఫైల్‌తో దీన్ని సరిచేయడానికి ప్రయత్నించకండి, ఎందుకంటే Compose ఫైళ్లలోని పోర్ట్ జాబితాలను రీప్లేస్ చేయకుండా కన్‌కాటెనేట్ (concatenate) చేస్తుంది. దీనివల్ల పాత పబ్లిక్ బైండింగ్ మరియు కొత్త బైండింగ్ రెండూ ఓపెన్‌గా ఉంటాయి.

ఇన్‌టేక్‌కు కూడా ఇదే జాగ్రత్త అవసరం. మీ ఇన్‌జెస్ట్ కీ హెడర్‌లో ప్రయాణిస్తుంది, కాబట్టి దానికి ముందు TLS (transport layer security) అవసరం: ప్రాక్సీకి ముందు nginx లేదా Caddy లో TLSని టెర్మినేట్ చేయండి, లేదా ఇన్‌జెస్ట్‌ను ప్రైవేట్ నెట్‌వర్క్ లేదా WireGuard టన్నెల్ లోపల ఉంచండి. 5173 పోర్ట్ మీద ఉన్న వెబ్ యాప్ ఒక Vite డెవలప్‌మెంట్ సర్వర్, దీనికి ఇంటర్నెట్‌తో ఎటువంటి సంబంధం ఉండకూడదు.

ఇక ఏజెంట్ విషయానికి వస్తే, Superlog యొక్క ప్రధాన ఉద్దేశ్యం ఏజెంట్ సమస్యను పరిశీలించి పరిష్కారాన్ని ప్రతిపాదించడం, ఇక్కడ 'ప్రతిపాదించడం' అనేది ముఖ్యమైన పదం. మీరు కొన్ని నిజమైన సంఘటనలపై అది ఎలా పనిచేస్తుందో గమనించే వరకు, ప్రొడక్షన్ సిస్టమ్స్‌పై దానికి రీడ్-ఓన్లీ అనుమతులను మాత్రమే ఇవ్వండి. GitHub App కి రీడ్ స్కోప్‌లను ఇచ్చి, అది క్రియేట్ చేసే పుల్ రిక్వెస్ట్‌లను మీరు రివ్యూ చేయండి. టెలిమెట్రీని చదివి ప్యాచ్‌ను రాసే ఏజెంట్ ఉపయోగకరంగా ఉంటుంది. మీ సర్వీసులను రీస్టార్ట్ చేయగల ఏజెంట్ ప్రమాదకరమైనది, కాబట్టి అటువంటి నిర్ణయాన్ని మీరు ఉద్దేశపూర్వకంగా తీసుకోవాలి, అంతే తప్ప డిఫాల్ట్‌గా వచ్చే అనుమతులను అలాగే ఉంచకూడదు. ఖర్చు విషయంలో కూడా ఇదే జాగ్రత్త అవసరం, ఎందుకంటే ప్రతి పరిశోధన ఒక మోడల్ కాల్‌తో కూడుకున్నది: మీరు ఒక బిజీగా ఉండే ప్రొడక్షన్ సిస్టమ్‌పై ఏజెంట్‌ను ఉపయోగించే ముందు VPSలో ఏజెంట్ ఖర్చు కోసం బడ్జెట్ నిర్ణయించుకోండి, మరియు ఏజెంట్ వాస్తవానికి ఏమి చేసిందో రికార్డు ఉంచండి, తద్వారా ఏదైనా ఆశ్చర్యకరమైన పుల్ రిక్వెస్ట్ వచ్చినప్పుడు దానికి తగిన ఆడిట్ ట్రయల్ అందుబాటులో ఉంటుంది.

మీరు ఎదుర్కొనే వైఫల్యాలు మరియు వాటిని సూచించే స్ట్రింగ్‌లు

pnpm install సమయంలో వచ్చే ERR_PNPM_UNSUPPORTED_ENGINE అంటే 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 కి పడిపోయిందని (fallback) అర్థం. యూనిట్ ఫైల్‌లో PORT ను స్పష్టంగా సెట్ చేయండి.
0.0.0.0:8123 చూపిస్తున్న docker compose ps అంటే మీ లూప్‌బ్యాక్ బైండింగ్‌లు అమలులో లేవని అర్థం. docker compose config రన్ చేసి, రిజాల్వ్ అయిన పోర్ట్‌లను చదవండి.

Flawless, HyperProbe, మరియు Superlog స్థానం

ఈ విభాగం కొత్తది, మరియు ఏ ఏజెంట్‌కు దేనిని తాకే అనుమతి ఉందనే విషయంలో సాధనాలు భిన్నంగా ఉంటాయి. Flawless అనేది Kubernetes కోసం రూపొందించబడిన ఒక open source AI SRE (site reliability engineering) సాధనం. ఇది పైప్‌లైన్‌ను తన ఆధీనంలో ఉంచుకోకుండా, ఇప్పటికే ఉన్న Prometheus, Loki మరియు Grafana stack నుండి సమాచారాన్ని చదువుతుంది. HyperProbe దీనికి భిన్నంగా పనిచేస్తుంది: ఇది ఒక hosted product. ఆగస్టు 2026 నాటికి ఇది closed source గా ఉంది. ఇది రన్ అవుతున్న process లోపల read-only probes ను ఉంచి, variable state ను సేకరిస్తుంది మరియు ఆ సమాచారాన్ని MCP (model context protocol) ద్వారా ఒక assistant కు అందిస్తుంది.

Superlog ఈ రెండింటి మధ్య ఉంటుంది. ఇది OTLP intake నుండి ClickHouse storage వరకు పైప్‌లైన్ మొత్తాన్ని తన ఆధీనంలో ఉంచుకుంటుంది. ఇది ఏజెంట్‌ను fix చేసే దశలో కాకుండా, triage చేసే దశలో ఉంచుతుంది. ఆ డిజైన్ కారణంగానే, దీన్ని self-host చేయడం అనేది ఒక మౌలిక సదుపాయాల (infrastructure) నిర్ణయం అవుతుంది, అంతే కానీ ఇది కేవలం మనం మర్చిపోయే ఒక container కాదు. మీరు Superlog ను రన్ చేస్తున్నారంటే, మీరు ఒక column store ను రన్ చేస్తున్నారని అర్థం. మీరు నిర్వహించే ఇతర database లకు ఇచ్చే జాగ్రత్తే దీనికి కూడా అవసరం.

FAQ

ఒక self-hosted Superlog కు ఎంత RAM అవసరం?

తక్కువ ingest volume ఉన్న సింగిల్ నోడ్ కోసం 8 GB RAM, 4 vCPU మరియు 40 GB డిస్క్ స్థలాన్ని ప్లాన్ చేసుకోండి. ఈ stack లో 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 కు పంపాలి?

README లో పేర్కొన్న విధంగా Superlog intake proxy ని http://localhost:4101 వద్ద ఉంచండి. ఇది /v1/traces, /v1/logs మరియు /v1/metrics లను అందిస్తుంది, మరియు ఇది x-api-key header లేదా authorization: bearer header నుండి తీసుకున్న మీ ప్రాజెక్ట్ ingest key తో authentication చేస్తుంది. Port 4318 అనేది లోపల ఉన్న OpenTelemetry collector, అక్కడికి నేరుగా export చేస్తే proxy ని దాటవేస్తుంది; కానీ మీ ప్రాజెక్ట్ id ని డేటాపై ముద్రించేది ఈ proxy మాత్రమే. PORT సెట్ చేయనప్పుడు proxy పోర్ట్ 4000 కు మారుతుంది, కాబట్టి 4101 అని అనుకునే ముందు ss -lntp రన్ చేసి అది దేనికి bound అయిందో నిర్ధారించుకోండి.

Superlog, Uptime Kuma లేదా Zabbix కు ప్రత్యామ్నాయమా?

కాదు. మీ నెట్‌వర్క్ వెలుపల నుండి ఒక endpoint స్పందిస్తుందో లేదో Uptime Kuma చెబుతుంది, మరియు మీరు సెట్ చేసిన పరిమితులకు అనుగుణంగా host మరియు service metrics ను Zabbix పర్యవేక్షిస్తుంది. మీ అప్లికేషన్లు పంపే traces, logs మరియు metrics ను Superlog స్వీకరించి, పదేపదే వచ్చే వైఫల్యాలను incidents గా సమూహపరుస్తుంది. దీనితో పాటు ఒక external uptime probe ను ఉంచండి, ఎందుకంటే మీ telemetry pipeline ఉన్న సర్వర్ డౌన్ అయినప్పుడు, బయట నడుస్తున్న probe మాత్రమే ఆ విషయాన్ని తెలియజేస్తుంది.

Superlog agent నా production సిస్టమ్స్‌ను మార్చగలదా?

మీరు ఇచ్చే అనుమతుల ద్వారా మాత్రమే అది సాధ్యం. దీని అవుట్‌పుట్ ఒక విశ్లేషణ మరియు మానవ సమీక్షకు పంపే ప్రతిపాదిత మార్పు మాత్రమే. మొదట్లో GitHub App కు read scopes మరియు pull requests అనుమతులు మాత్రమే ఇవ్వండి, మరియు worker కు ఉండే credentials ను కేవలం reading కే పరిమితం చేయండి. Production కు write access ఇవ్వడం అనేది ఒక ప్రత్యేక నిర్ణయం; ఎందుకంటే telemetry చదివి patch రాసే agent కంటే, సేవలను restart చేయగల agent కు ఎక్కువ బాధ్యత ఉంటుంది.

నేను commit ను pin చేయాలా లేక main ను track చేయాలా?

Commit ను pin చేయండి. ఆగస్టు 2026 నాటికి repository లో ఎటువంటి release tags లేవు, కాబట్టి main మాత్రమే అందుబాటులో ఉన్న ఏకైక మార్పు, ఇది వారానికి అనేక commits పొందుతుంది. మీరు పరీక్షించిన SHA ను నమోదు చేసుకోండి, దానినే deploy చేయండి, మరియు ముందుకు వెళ్లే ముందు diff ను చదవండి. git log --oneline <old-sha>..main అనేది సమీక్ష, మరియు ఏదైనా మార్పు తర్వాత కొత్తగా అవసరమైన variables కోసం ప్రతి అప్లికేషన్ యొక్క .env.example ఫైళ్లను మొదట చూడండి.

#superlog#observability #opentelemetry#clickhouse#ai-sre