Paano i-self-host ang Superlog para sa AI triage

Mga aktuwal na ini-install ng self-hosting sa Superlog

Para mag-self-host ng Superlog, i-clone ang repository, paandarin ang Postgres, ClickHouse, at isang OpenTelemetry collector gamit ang Docker Compose, magpatakbo ng isang database migration, at pagkatapos ay simulan mula sa source ang apat na Node service. Nagpapadala ang mga application mo ng OTLP (OpenTelemetry protocol) traces, logs, at metrics sa isang intake port. Tinutukoy ng Superlog ang fingerprint ng mga ito, pinapangkat ang mga nauulit sa iisang incident, at nagsusulat ang isang agent ng unang bersyon ng triage. Isang hapon ang kailangan para sa installation. Ang footprint at ang mga limitasyong dapat asahan ang pinakamahalagang basahin bago magsimula.

May Apache 2.0 license ang Superlog at nasa github.com/superloglabs/superlog. Noong August 2026, mayroon itong humigit-kumulang 1.2k stars, tinatayang 460 commits sa main, at wala talagang release tags. Dahil dito, may epekto ito sa installation: walang maaaring i-check out sa git checkout v1.0.0, kaya ikaw mismo ang magpi-pin ng commit o gagamitin mo ang anumang bersyon na nasa main noong umagang nag-clone ka.

Mga tanong na sinasagot ng Superlog na hindi sinasagot ng Uptime Kuma at Langfuse

Magkakapareho ang hitsura ng mga self-hosted monitoring tool. Hindi sila magkakapareho, at kapag maling tool ang pinatakbo mo, masasayang ang isang server nang walang pakinabang.

• Sinusuri ng Uptime Kuma ang iyong mga endpoint mula sa labas at isang tanong lang ang sinasagot nito: gumagana ba ito.
• Minomonitor ng Zabbix ang mga host at serbisyo sa Ubuntu 24.04, kasama ang CPU, memory, disk, at status ng serbisyo batay sa mga threshold na itinakda mo.
• Tinitrasyahan ng Langfuse ang mga LLM call, at itinatala ang prompt, model, token, latency, at cost ng bawat isa.
• Kinukuha ng Superlog ang telemetry na inilalabas na ng iyong mga ordinaryong serbisyo at ginagawang incident ang mga paulit-ulit na failure.

Iba ang tanong na sinasagot ng Superlog: may nasira, ano ang nasira, at bakit. Wala itong partikular na gamit para sa mga LLM call, at hindi ka nito sinusuri mula sa labas. Tumatanggap ito ng OTLP mula sa karaniwang application code mo at naglalagay ng agent sa triage step, na siya ring unang pagsusuri na karaniwang ginagawa ng naka-duty na tao.

Ang mahalagang pagkakaiba para sa budget ng VPS ay ang storage. Maayos na tumatakbo ang Uptime Kuma sa 1 GB ng RAM dahil ilang libong check result lang ang iniimbak nito. Gumagamit ang Superlog ng column store dahil isinusulat ang telemetry nang isang beses at saka kino-query ayon sa time range sa milyun-milyong row. Iyan ang gamit ng ClickHouse at hindi ng Postgres. Kasama pa rin ang Postgres sa stack para sa maliit na relational data: projects, users, incidents, at ingest keys.

Ano talaga ang sinisimulan ng docker compose up -d?

Tatlong container, at wala sa mga ito ang Superlog. Nakakagulat ito para sa mga umaasang isang command lang ang kailangan para sa installation.

• postgres:16, na naka-publish sa host port 5434
• clickhouse/clickhouse-server:26.1, sa port 8123 para sa HTTP at 9000 para sa native protocol
• otel/opentelemetry-collector-contrib:0.150.1, sa port 4317 para sa gRPC at 4318 para sa OTLP over HTTP

Tumatakbo ang mga application ng Superlog sa host, mula sa source, at sinisimulan ng pnpm dev. Wala pang production compose file sa repository noong August 2026. Kaya para sa matagalang installation, kailangan mong gumawa ng sarili mong systemd units para sa bawat app na gagamit ng start script nito, o gamitin ang mga Dockerfile para sa bawat app na kasama sa tree.

Tandaan ang path na tinatahak ng isang span. Ang bawat failure sa ibaba ay pagkaputol sa isang hop nito. Nagpapadala ang app mo ng OTLP sa Superlog intake proxy. Ina-authenticate ng proxy ang request gamit ang ingest key mo, inilalagay dito ang project id, at ipinapasa ito sa collector. Tinatanggal ng collector ang anumang superlog.* attribute na sinubukang itakda ng client, idinadagdag ang superlog.project_id mula sa header na ibinigay ng proxy, bina-batch ito, at isinusulat sa ClickHouse. Binabasa naman ng web app at ng API ang telemetry mula sa ClickHouse, habang ang lahat ng iba pa ay binabasa mula sa Postgres.

Totoong multi-tenancy control ang pagtanggal sa attribute na iyon, hindi lamang dekorasyon. Kung wala ito, maaaring itakda mismo ng sinumang may valid na ingest key ang superlog.project_id at magsulat sa data ng ibang project.

Gaano kalaki dapat ang VPS?

Maglaan ng 4 vCPU, 8 GB ng RAM, at 40 GB ng SSD para sa single-node install na mababa ang ingest volume. Panimulang batayan lamang ito, hindi eksaktong sukat, kaya gamitin ito bilang starting size at ikumpara sa sarili mong traffic.

Napupunta ang memory sa apat na bahagi. Ang ClickHouse ay ginawa para sa mga machine na maraming RAM, at ipinapalagay iyon ng mga default nito. Katamtaman lamang ang gamit ng Postgres 16 dito dahil metadata, hindi telemetry, ang iniimbak nito. Katamtaman din ang gamit ng collector. Hindi ganoon ang apat na Node process: bawat Vite development server at tatlong tsx watch process ay maaaring gumamit ng tig-iilang daang megabytes. Dahil dito, mahirap gamitin ang pnpm dev sa isang 2 GB na machine.

Mas tahimik na problema ang disk. Sa pnpm install sa monorepo na ito, dina-download ang AWS SDK, isang ClickHouse client, ang OpenTelemetry SDK, at isang React toolchain bago ka pa makapag-ingest ng isang span. Pagkatapos, lumalaki ang ClickHouse kasabay ng traffic. Sukatin ang dalawang ito:

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"

Sa mababang volume, kung ilang serbisyo lamang ang nagpapadala ng ilang daang span bawat minuto, tahimik ang machine at kadalasang idle ang ClickHouse. Ang nakakapagpabigat ay ang burst: isang maling deploy na gumagawa ng libo-libong magkakaparehong error bawat minuto. Pinagsasama ng fingerprinting ang mga ito bilang isang incident para sa reader, pero isinusulat pa rin ng ClickHouse ang bawat row sa ilalim nito.

Ikaw ang magtatakda ng retention. Ginagawa ng ClickHouse exporter ng collector ang mga table, otel_traces, otel_logs, at tig-isang table para sa bawat metric type. Naglalapat lamang ito ng time to live kung nagtatakda ang config sa infra/collector/config.yaml nito. Walang awtomatikong nage-expire, kaya mapupuno ang disk sa isang abalang buwan kung hindi mo ito pagpaplanuhan.

Mag-install mula sa naka-pin na commit

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

git tag -l na walang inilalabas ay inaasahang resulta hanggang Agosto 2026. Piliin ang commit na sinubukan mo at manatili rito:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Sunod, ang toolchain:

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

Itinatakda ng package.json ang engines.node bilang >=20.0.0 at ang packageManager bilang pnpm@9.12.0. Kapag nagpatakbo ka ng install gamit ang mas lumang Node, hihinto ang pnpm at ipapakita ang ERR_PNPM_UNSUPPORTED_ENGINE, kasama ang bersyong kailangan nito. Mas luma sa 20 ang nodejs package sa Ubuntu 24.04 archive, kaya mag-install ng Node 20 o mas bago mula sa NodeSource o gamit ang nvm. May .nvmrc ang repository, kaya nvm use ang pipili ng itinakdang version kung mayroon kang nvm.

pnpm install
docker compose up -d
docker compose ps

Hintayin ang health checks sa halip na ituring na handa na ang system dahil lamang sa up -d. Parehong nagdedeklara ng health check ang Postgres at ClickHouse sa compose file:

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

Sumasagot ang ClickHouse sa Ok. at sumasagot ang pg_isready sa accepting connections. Ang connection refused sa 8123 ay nangangahulugang nagsisimula pa ang container o tumigil na ito dahil sa error. Ipinapakita ng docker compose logs clickhouse kung alin sa mga ito ang nangyari, at iniuulat ng docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled ang true kapag pinatay ito ng kernel dahil sa memory, na nagpapahiwatig na masyadong maliit ang server kaysa sa maling configuration.

Sunod ang migration at ang mga application:

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

Pansinin ang port: 5434, hindi 5432. Ipinapublish ng compose file ang Postgres sa 5434 upang hindi ito sumalungat sa Postgres na naka-install na sa host, at tugma rito ang mga .env.example file ng app, kasama ang DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Kapag itinuro mo ang migration sa 5432 sa server na may tumatakbo nang Postgres, maaaring makakuha ka ng refused connection o, mas masama, mailapat ang migration sa maling database.

Sinisimulan ng pnpm dev ang apat na process na nakalista sa Procfile ng repository: api, web, worker at proxy. Ipinapasa ng bawat isa ang output nito sa tmp/logs/, kaya tail -f tmp/logs/proxy.log ang dapat mong i-monitor para sa ingest. Inilalagay ng README ang web app sa http://localhost:5173, ang API sa http://localhost:4100, at ang OTLP intake sa http://localhost:4101.

Kumpirmahin muna kung ano talaga ang nag-bind bago mo ito pagturuan ng kahit ano:

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

Mahalaga ito sa mga susunod na hakbang. Binabasa ng proxy ang sarili nitong port mula sa environment variable na PORT at gumagamit ng 4000 kapag hindi naka-set ang PORT. Awtomatikong itinatakda ito ng development stack. Hindi ito itinatakda ng systemd unit na ikaw mismo ang gagawa, kaya mabibigo ang exporter na nakaturo sa 4101 laban sa proxy na nakikinig sa 4000 sa pamamagitan ng connection refused at wala itong ibang ibibigay na palatandaan.

Magpadala ng isang trace, gumawa ng isang error, at makakita ng isang incident

Gumawa ng project sa web app at kopyahin ang ingest key nito. Ina-authenticate ng intake ang bawat request gamit ang key na iyon, kaya hindi nakararating sa ClickHouse ang telemetry na ipinadala nang walang key.

Ituro ang anumang OpenTelemetry SDK sa intake gamit ang mga standard environment variable:

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'

Binabasa ng intake ang key mula sa x-api-key header. Tinatanggap din nito ang authorization: bearer YOUR_INGEST_KEY kung mas madali itong i-configure sa exporter. Ibinibigay nito ang tatlong standard na OTLP path na /v1/traces, /v1/logs, at /v1/metrics, pati ang /health.

May isang karaniwang pagkakamali na dapat tandaan. Ang OTEL_EXPORTER_OTLP_ENDPOINT ay base URL, at idinaragdag ng SDK ang signal path dito. Ginagamit ang mga signal-specific variable gaya ng OTEL_EXPORTER_OTLP_TRACES_ENDPOINT nang eksakto sa pagkakasulat, nang walang idinadagdag na path. Kung itatakda mo ang signal-specific variable sa http://127.0.0.1:4101, bawat export ay ipapadala sa /. Hindi ito route, kaya walang makararating at magla-log ang SDK ng export failure kahit mukhang maayos ang app.

Para sa Node service, sapat na ang zero-code path upang mapatunayan ang pipeline:

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

Ngayon, sadyang magpasira ng isang bahagi. Sapat na ang anumang route na nagta-throw ng error:

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

Suriin ang mga hop ayon sa pagkakasunod-sunod. Ipinapakita ng unang puwang kung aling bahagi ang nabigo:

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

Kung tumataas ang bilang sa otel_traces habang walang laman ang web app, project mismatch ito. Suriin kung saang project nauugnay ang ingest key. Kung hindi nagbabago ang bilang pero may activity sa proxy log, tingnan ang collector o ang pagsulat sa ClickHouse. Basahin ang docker compose logs collector. Kung walang anumang activity sa proxy log, hindi nakarating sa intake ang exporter: maaaring maling port, maling path, o tinanggihan ang key.

Sa web app, dumarating ang mga paulit-ulit na failure bilang isang incident sa halip na isang row para sa bawat request. Tinutukoy ng Superlog ang fingerprint ng mga papasok na signal at pinagsasama ang magkakatugma. Dahil dito, nagiging isang page ang 4,000 magkakaparehong error sa halip na isang inbox na may 4,000 row. Isinusulat naman ng agent ang imbestigasyon nito sa ibabaw ng grupong iyon.

Tumatawag ng model ang hakbang ng imbestigasyon, kaya kailangang may naka-configure na model provider ang worker. Kunin ang mga pangalan ng variable mula sa .env.example file sa loob ng bawat app directory ng commit na iyong ni-pin, sa halip na mula sa anumang external na write-up. Nagbabago ang mga ito kasabay ng main. Ganoon din para sa GitHub at Sentry integrations. May sarili silang setup document sa docs/github-app-setup.md at docs/sentry-app-setup.md, at nakadokumento ang webhook payload sa docs/webhooks.md.

Panatilihing pribado ang intake, at read-only ang agent

Bilang default, ipinapublish ng Docker ang container ports sa 0.0.0.0. Nalalampasan ng mga port na ito ang ufw dahil nagsusulat ang Docker ng sarili nitong rules sa DOCKER-USER chain, na sinusuri bago makita ng ufw ang packet. Sa isang VPS na may public IP, inilalagay ng compose file, ayon sa pagkaka-release nito, ang ClickHouse HTTP sa 8123 at ang Postgres sa 5434, kaya maaabot ang mga ito mula sa internet. Development defaults ang credentials sa file na iyon: ang ClickHouse user ay default na walang password, at ang Postgres ay gumagamit ng postgres bilang user at password.

I-bind ang mga ito sa loopback. Kinukuha ng bawat published port sa compose file ang host side nito mula sa environment variable, kaya sapat na ang isang .env sa repository root:

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

I-verify muna ang resulta bago mo ito pagkatiwalaan, saka i-recreate ang mga container:

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

Ipi-print ng docker compose config ang resolved file, kaya mababasa mo ang 127.0.0.1:5434:5432 sa halip na manghula. Dapat ipakita ng ss ang 127.0.0.1:5434 at hindi kailanman ang 0.0.0.0:5434. Huwag subukang ayusin ito gamit ang compose override file na muling nagde-declare ng ports. Pinagsasama ng Compose ang mga port list sa magkakaibang file sa halip na palitan ang mga ito, kaya mapupunta sa iyo ang parehong binding at mananatiling bukas ang public one.

Kailangan ding protektahan ang intake. Dumadaan sa header ang ingest key mo, kaya kailangan nito ng TLS (transport layer security) sa unahan: i-terminate ang TLS sa nginx o Caddy bago ang proxy, o panatilihin ang ingest sa isang private network o WireGuard tunnel. Ang web app sa 5173 ay Vite development server at hindi dapat nakaharap sa internet.

Sunod, ang agent mismo. Ang pangunahing gamit ng Superlog ay mag-imbestiga at magmungkahi ng fix ang agent, at ang mahalagang salita rito ay “magmungkahi.” Panatilihin itong read-only laban sa production hanggang mapanood mo itong gumana sa ilang aktuwal na insidente. Bigyan ang GitHub App ng read scopes at payagan itong magbukas ng pull requests na ikaw ang magre-review. Kapaki-pakinabang ang agent na nagbabasa ng telemetry at nagsusulat ng patch. Ibang antas ng panganib ang agent na kayang mag-restart ng mga serbisyo mo. Dapat itong sadyang pagpasiyahan, hindi maging default na minana mo. Kailangan ding bantayan ang gastos dahil model call ang bawat investigation: maglaan ng budget para sa gastos ng agent sa VPS bago mo ito itutok sa maingay na production system, at panatilihin ang tala ng aktuwal na ginawa ng agent upang may audit trail sa likod ng anumang nakakagulat na pull request.

Mga failure na mararanasan mo at mga string na tumutukoy sa mga ito

• Ang ERR_PNPM_UNSUPPORTED_ENGINE habang ginagawa ang pnpm install ay nangangahulugang mas luma sa 20 ang Node. Kinukumpirma ito ng node -v sa isang linya.
• Ang ECONNREFUSED 127.0.0.1:5434 habang ginagawa ang migration ay nangangahulugang hindi naka-up ang compose stack, o maling port ang tinutukoy ng DATABASE_URL.
• Karaniwang memory issue ang paulit-ulit na pag-restart ng ClickHouse. Basahin ang docker compose logs clickhouse, pagkatapos ay tingnan kung ang OOMKilled ng container ay true.
• Kapag nag-uulat ng tagumpay ang isang exporter pero nananatiling walang laman ang web app, karaniwang direktang napunta ang data sa collector sa 4318. Nalalaktawan nito ang project stamping na ginagawa ng proxy.
• Ang connection refused sa 4101 sa isang production install ay nangangahulugang nag-fallback ang proxy sa PORT=4000. Itakda nang tahasan ang PORT sa unit file.
• Kapag ipinapakita ng docker compose ps ang 0.0.0.0:8123, hindi ginagamit ang iyong loopback bindings. Patakbuhin ang docker compose config at basahin ang mga na-resolve na port.

Flawless, HyperProbe, at kung saan pumapagitna ang Superlog

Bago pa lamang ang kategoryang ito, at magkakaiba ang mga tool sa saklaw ng maaaring galawin ng agent. Ang Flawless ay isang open source AI SRE (site reliability engineering) tool para sa Kubernetes. Kumukuha ito ng data mula sa kasalukuyang Prometheus, Loki, at Grafana stack sa halip na ito ang mamahala sa pipeline. Kabaligtaran naman ang HyperProbe: isa itong hosted product na closed source noong August 2026. Naglalagay ito ng read-only probes sa loob ng tumatakbong process upang makuha ang kasalukuyang variable state, at inilalantad ang state na iyon sa isang assistant sa pamamagitan ng MCP (model context protocol).

Nasa pagitan ng dalawa ang Superlog. Ito ang namamahala sa buong pipeline, mula sa OTLP intake hanggang sa pag-store sa ClickHouse. Inilalagay nito ang agent sa triage step, hindi sa fix step. Ito mismo ang dahilan kung bakit ang self-hosting nito ay isang infrastructure decision, hindi lang container na maaari mong kalimutan. Kapag pinatakbo mo ang Superlog, nagpapatakbo ka rin ng column store. Kailangan nito ng kaparehong pag-aalaga gaya ng ibang database na ikaw ang namamahala.

FAQ

Ilang RAM ang kailangan ng self-hosted Superlog?

Maglaan ng 8 GB RAM, 4 vCPU, at 40 GB disk para sa isang node na may mababang ingest volume. Binubuo ang stack ng Postgres, ClickHouse, isang OpenTelemetry collector, at apat na Node process. Kailangan din ng ClickHouse ng sapat na headroom. Hindi sapat ang 1 GB o 2 GB VPS: mabigat mag-isa ang pnpm install, at kino-kill ng kernel out-of-memory killer ang ClickHouse kapag mataas ang load. Sukatin ang sarili mong values gamit ang docker stats --no-stream at free -m sa halip na umasa sa anumang published figure, kabilang na ang nasa seksyong ito.

Saang port ko ituturo ang OTLP exporter ko?

Ituro ito sa Superlog intake proxy, na inilalagay ng README sa http://localhost:4101. Nagsisilbi ito sa /v1/traces, /v1/logs, at /v1/metrics, at nag-a-authenticate gamit ang ingest key ng project mo na kinukuha mula sa x-api-key header o sa authorization: bearer header. Ang port 4318 ang OpenTelemetry collector sa ilalim nito. Kapag direkta kang nag-export doon, nilalampasan mo ang proxy, na siyang naglalagay ng project id sa data. Gumagamit ang proxy ng port 4000 kapag hindi naka-set ang PORT. Patakbuhin ang ss -lntp at kumpirmahin kung saan ito naka-bind bago ipagpalagay na 4101 ang port.

Pinapalitan ba ng Superlog ang Uptime Kuma o Zabbix?

Hindi. Sinasagot ng Uptime Kuma kung tumutugon ang isang endpoint mula sa labas ng network mo. Minomonitor naman ng Zabbix ang host at service metrics batay sa mga threshold na itinakda mo. Kinokonsumo ng Superlog ang traces, logs, at metrics na inilalabas ng mga application mo, at pinapangkat nito ang mga paulit-ulit na failure bilang incidents. Magpatakbo pa rin ng external uptime probe kasama nito. Kapag nasa ibang lugar ang probe, makakapag-ulat pa rin ito kapag ang server na nagpapatakbo ng telemetry pipeline mo ang bumagsak.

Maaari bang baguhin ng Superlog agent ang production systems ko?

Tanging sa pamamagitan ng permissions na ibinigay mo rito. Ang output nito ay isang imbestigasyon at iminungkahing pagbabago na sinusuri ng tao. Panatilihing read-only muna ang GitHub App scopes, kasama ang pull requests, at panatilihing limitado sa pagbabasa ang anumang credentials na hawak ng worker. Ituring na hiwalay at sinasadyang desisyon ang write access sa production. Mas malaking commitment ang agent na kayang mag-restart ng services kaysa agent na nagbabasa ng telemetry at gumagawa ng patch para sa review.

Dapat ba akong mag-pin ng commit o mag-track ng main?

Mag-pin ng commit. Walang release tags sa repository hanggang Agosto 2026. Dahil dito, ang main lamang ang moving target na available, at ilang commits bawat linggo ang nadaragdag dito. Itala ang SHA na sinubukan mo, i-deploy ang commit na iyon, at basahin ang diff bago mag-update. Ang git log --oneline <old-sha>..main ang review, at ang per-app na .env.example files ang unang dapat tingnan para sa mga bagong kailangang variable pagkatapos ng anumang bump.