How to Self-host Superlog for AI Log Triage
See how Superlog turns OTLP logs, traces and metrics into incidents, plus the Docker Compose stack, four Node services, real footprint and no release tags.
Wetin self-hosting Superlog actually install
To self-host Superlog, you go clone the repository, bring up Postgres, ClickHouse and an OpenTelemetry collector with Docker Compose, run one database migration, then start four Node services from source. Your applications go send OTLP (OpenTelemetry protocol) traces, logs and metrics to an intake port. Superlog go fingerprint dem, group repeated ones into one incident, and the default community agent runner go record local incident summary. The installation fit take one afternoon. The footprint and the honest limits na the parts wey you suppose read before you start.
Superlog get Apache 2.0 license and e dey for github.com/superloglabs/superlog. As of 13 October 2026, e get around 1.5k stars, roughly 490 commits for main, and no release tags at all. Pin one commit by yourself instead of running whatever main happen to dey use the morning wey you clone am.
Wetin Superlog dey answer wey Uptime Kuma and Langfuse no dey answer
Self-hosted monitoring tools fit look like say dem dey do the same thing from outside. But dem no be the same, and if you run the wrong one, you go waste server resources without benefit.
- Uptime Kuma dey probe your endpoints from outside and e dey answer one question: e dey up?
- Zabbix dey watch hosts and services for Ubuntu 24.04, with CPU, memory, disk and service state against the thresholds wey you set.
- Langfuse dey trace LLM calls, recording the prompt, the model, the tokens, the latency and the cost of each call.
- Superlog dey collect the telemetry wey your normal services already dey emit, then e dey turn repeated failures into incidents.
Superlog get different question: something break, wetin break, and why. E no get opinion about LLM calls, and e no dey probe your service from outside. E dey ingest OTLP from your normal application code and put agent for the triage step. Triage na the first check wey the human on call go do anyway.
The difference wey matter for VPS budget na the storage. Superlog carry column store because telemetry dey write once, then system dey query am by time range across millions of rows. Na wetin ClickHouse dey do, and Postgres no dey do am. Postgres still dey inside the stack, where e dey hold small relational data: projects, users, incidents and ingest keys.
Wetin docker compose up -d actually dey start?
Three containers, and none of dem na Superlog. This fit surprise people wey expect say one command go install everything.
postgres:16, published for host port 5434clickhouse/clickhouse-server:26.1, for 8123 for HTTP and 9000 for the native protocolotel/opentelemetry-collector-contrib:0.150.1, for 4317 for gRPC and 4318 for OTLP over HTTP
Superlog applications dey run for the host from source, and pnpm dev dey start dem. As of 13 October 2026, repository no get production compose file. So, if you want installation wey go run long-term, you need your own systemd units, or use the per-app Dockerfiles wey dey inside the tree. The api, worker and proxy apps each get one start script wey unit fit wrap. The web app no get one: na Vite app, so build am with its build script, then serve the output as static files from nginx or Caddy. Another option na to run its preview script, wey be vite preview.
Keep the path wey one span dey take for mind, because every failure below mean say one hop for that path don break. Your app posts OTLP to the Superlog intake proxy. The proxy authenticates the request with your ingest key, puts the project id on top, then forwards am to the collector. The collector removes any superlog.* attributes wey client try set, adds superlog.project_id from the header wey proxy provide, batches the data, then writes am to ClickHouse. The web app and API read telemetry back from ClickHouse, and dem read everything else from Postgres.
That attribute removal na real multi-tenancy control; e no be decoration. If you no remove am, anybody wey get one valid ingest key fit set superlog.project_id by themselves and write data into another project's data.
How VPS size you need?
Plan for 4 vCPU, 8 GB RAM and 40 GB SSD for one single-node install when ingest volume low. This one na planning floor, no be measurement, so use am as starting size and check am against your own traffic.
Memory dey go four places. ClickHouse na software wey dem build for machines wey get plenty RAM, and the default settings assume say RAM plenty. Postgres 16 no too heavy for here, because e dey hold metadata instead of telemetry. The collector no too heavy too. The four Node processes include one Vite development server plus three tsx watch processes; measure how much memory dem dey use for your own machine.
Disk na the quieter problem. pnpm install for this monorepo dey pull AWS SDK, one ClickHouse client, OpenTelemetry SDK and React toolchain before you ingest even one span. ClickHouse go then grow as your traffic increase. Measure both:
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"Na burst load dey cause serious problem: one bad deploy fit produce thousands of identical errors every minute. Fingerprinting dey join dem into one incident for the reader, but ClickHouse still dey write every row underneath.
Na you go set retention. The collector's ClickHouse exporter dey create the tables, otel_traces, otel_logs and one table for each metric type, and e only apply time to live if the config for infra/collector/config.yaml set one. Nothing dey expire by itself, so one busy month fit fill the whole disk unless you plan for am.
Install from one 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 wey print nothing na the expected result as of 13 October 2026. Pick the commit wey you test and remain on am:
git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1eNow the toolchain:
node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -vpackage.json declare say engines.node na >=20.0.0 and packageManager na pnpm@9.12.0. Node version wey no compatible no dey automatically stop installation: configuration dey determine whether engine enforcement go happen, and pnpm 9.12.0 get warning path when engineStrict disable. The nodejs package for Ubuntu 24.04 archive old pass 20, so install Node 20 or newer from NodeSource or from nvm. The repository ship one .nvmrc, so nvm use go choose the intended version if you get nvm.
pnpm install
docker compose up -d
docker compose psWait for the health checks instead of assuming say up -d mean say service ready. Postgres and ClickHouse both declare one for the compose file:
curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgresClickHouse dey answer Ok. and pg_isready dey answer accepting connections. If connection to 8123 refuse, e mean say the container still dey start or e don die. docker compose logs clickhouse show which one, and docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled report true when kernel kill am because of memory. That one point to the box being too small, no be your config.
Then the migration and the applications:
pnpm --filter @superlog/db db:migrate
pnpm devPay attention to the port: 5434, no be 5432. The compose file publish Postgres on 5434 so e no go clash with Postgres wey already install for the host, and the app .env.example files match am, together with DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. If you point the migration at 5432 for a box wey already dey run Postgres, you fit get refused connection or, worse, apply migration to the wrong database.
pnpm dev run turbo run dev. This one start each app dev script through Turborepo, including api, web, worker and proxy, and mix their output for one terminal. The repository Procfile list the same four processes and tee each process output into tmp/logs/. Start am with a Procfile runner like overmind or foreman instead of pnpm dev if you want tail -f tmp/logs/proxy.log to be where you monitor ingest. The README put the web app on http://localhost:5173, the API on http://localhost:4100 and the OTLP intake on http://localhost:4101.
Confirm wetin actually bind before you point anything at am:
ss -lntp | grep -E '4000|4100|4101|5173'
curl -sS http://127.0.0.1:4101/healthThis one go matter later. The proxy read its own port from the PORT environment variable and fall back to 4000 when PORT unset. The apps/proxy/.env.example wey e load also set PORT=4000, even though the README list the intake on 4101 (both checked on 13 October 2026). Use the port wey ss show. The examples below use 4101, so replace am with 4000 if na that one bind. A systemd unit wey you write yourself no set anything unless you put PORT inside am. So, exporter wey target 4101 while proxy dey listen on 4000 go fail with connection refused, and e no go give you any other clue.
Send one trace, produce one error, see one incident
Create project for the web app and copy im ingest key. The intake dey authenticate every request against that key, so telemetry wey dem send without am no go reach ClickHouse.
Point any OpenTelemetry SDK to the intake with the standard 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'The intake dey read the key from the x-api-key header, and e also accept authorization: bearer YOUR_INGEST_KEY if your exporter easier to configure that way. E dey serve the three standard OTLP paths, /v1/traces, /v1/logs and /v1/metrics, plus /health.
One trap dey worth naming. OTEL_EXPORTER_OTLP_ENDPOINT na base URL and the SDK dey append the signal path to am. Signal-specific variables like OTEL_EXPORTER_OTLP_TRACES_ENDPOINT dey used exactly as dem dey written, without appending any path. Set the signal-specific variable to http://127.0.0.1:4101 and every export go post to /, wey no be route. So nothing go arrive, and the SDK go log export failure while your app still dey look healthy.
For one Node service, the zero-code path enough to prove the pipeline:
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.jsNow break something on purpose. Any route wey throws go work:
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boomCheck the hops one after another, because the first gap go tell you which one fail:
tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'If count for otel_traces dey rise while the web app empty, na project mismatch. Check which project the ingest key belong to. If the count flat but proxy log dey show activity, check the collector or the ClickHouse write, then read docker compose logs collector. If proxy log no get any activity at all, the exporter never reach the intake: port fit wrong, path fit wrong, or the key fit don reject.
For the web app, those repeated failures go arrive as one incident instead of one row for every request. Superlog dey fingerprint incoming signals and group the ones wey match, so inbox no go hold 4,000 identical errors; e go hold one page instead. The default community agent runner then dey record local incident summary for that group.
Model-backed investigation need model provider and compatible agent runner wey dem configure; the default community runner dey record local summary. Take those variable names from the .env.example file inside each app directory of the commit wey you pin, instead of any external write-up, because dem dey change together with main. The same thing apply to the GitHub and Sentry integrations. Dem get their own setup documents for docs/github-app-setup.md and docs/sentry-app-setup.md, while webhook payloads dey documented for docs/webhooks.md.
Make the intake private, and make the agent read only
Docker dey publish container ports for 0.0.0.0 by default, and those published ports dey bypass ufw. Docker dey route container traffic for the nat table, so packet wey dey go published port go divert before e reach the INPUT and OUTPUT chains where ufw rules dey, and ufw no go get any say. For VPS wey get public IP, the compose file as e come dey expose ClickHouse HTTP for 8123 and Postgres for 5434 to internet. The credentials for that file na development defaults: ClickHouse user default with empty password, and Postgres with postgres as both user and password.
Bind dem to loopback. Every published port for the compose file dey take the host side from environment variable, so one .env for repository root dey enough:
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:4318Verify the result before you trust am, then recreate the containers:
docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'docker compose config go print the resolved file, so you fit read 127.0.0.1:5434:5432 instead of guessing. ss suppose show 127.0.0.1:5434 and e no suppose ever show 0.0.0.0:5434. If you only re-declare ports for a Compose override file, both bindings go remain when the host IP dey different; Compose 2.24.4 and later support ports: !override to replace the list.
The intake need the same care. Your ingest key dey travel inside header, so e need TLS (transport layer security) in front: terminate TLS for nginx or Caddy before the proxy, or keep ingest inside private network or WireGuard tunnel. The web app for 5173 na Vite development server, and e no get any reason to face internet at all.
Now the agent itself. Superlog pitch be say the agent dey investigate and propose fix, and the important word na proposes. Keep am read only against production until you don watch how e work for some real incidents. Read-only GitHub App no fit push fix branch or open pull requests: the setup guide require Contents and Pull requests write permissions for that workflow, plus Issues write permission for comments. Agent wey dey read telemetry and write patch dey useful. Agent wey fit restart your services get different level of risk, and na decision wey you suppose make deliberately, instead of inheriting am as default. Cost deserve the same attention when you configure model-backed runner: plan budget for agent spending on VPS before you point am at noisy production system, and keep record of wetin the agent actually do so surprising pull request get audit trail behind am.
Wetin you go encounter for failure, and the strings wey name dem
ERR_PNPM_UNSUPPORTED_ENGINEduringpnpm installmean say one engine requirement no compatible. pnpm 9.12.0 dey check both Node and pnpm requirements; read the wanted and current versions wey error show, then checknode -vandpnpm -v.ECONNREFUSED 127.0.0.1:5434during the migration mean say compose stack no dey up, orDATABASE_URLdey name wrong port.- Check whether ClickHouse dey restart with
docker compose logs clickhouse, then check whether container getOOMKilledset totrue. - If exporter report success while web app still empty, e usually mean say data go directly to collector for 4318. This one bypass the project stamping wey proxy dey do.
- If connection refuse for 4101, e usually mean say proxy dey listen for 4000. Na the port wey the code fall back to and the one wey
.env.exampleset. SetPORTexplicitly inside the unit file or the app.env. - If
docker compose psdey show0.0.0.0:8123, e mean say your loopback bindings no dey apply. Rundocker compose configand read the resolved ports.
Flawless, HyperProbe, and where Superlog dey sit
This category still dey young, and the tools dey differ based on wetin agent fit touch. Flawless repository now dey present CISRE, an AI SRE (site reliability engineering) platform for Kubernetes and cloud infrastructure, under PolyForm Noncommercial license. HyperProbe dey place probes inside running process to capture variable state, then e expose that state to assistant through MCP (model context protocol); e also document how to self-host am with Docker Compose and license key.
Superlog dey between the two. E own the whole pipeline, from OTLP intake reach ClickHouse storage, and e place agent for triage step instead of fix step. Na this design make self-hosting am be infrastructure decision, no be container wey you fit forget. Once you run Superlog, you dey run column store, and e need the same care like any other database wey you own.
FAQ
How much RAM self-hosted Superlog need?
Plan for 8 GB RAM, 4 vCPU, and 40 GB disk for one node when ingest volume dey low. The stack na Postgres plus ClickHouse plus one OpenTelemetry collector plus four Node processes, and ClickHouse need extra headroom. Measure your own numbers with docker stats --no-stream and free -m instead of trusting any published figure, including this one.
Which port I go point my OTLP exporter to?
Na the Superlog intake proxy, wey the README put for http://localhost:4101. E dey serve /v1/traces, /v1/logs, and /v1/metrics, and e dey authenticate with your project's ingest key wey e take from x-api-key header or authorization: bearer header. Port 4318 na the OpenTelemetry collector underneath. If you export there directly, you dey bypass the proxy, wey be the component wey stamps your project id onto the data. The proxy go fall back to port 4000 when PORT no set, and its .env.example set 4000 too. So run ss -lntp and confirm the port wey e bind before you assume say na 4101.
Superlog fit replace Uptime Kuma or Zabbix?
No. Uptime Kuma answers whether endpoint dey respond from outside your network, while Zabbix dey monitor host and service metrics against the thresholds wey you set. Superlog dey consume the traces, logs, and metrics wey your applications emit, then e dey group repeated failures into incidents. Keep an external uptime probe alongside am, because a probe wey dey run for another place still go report when na the box wey dey hold your telemetry pipeline die.
Superlog agent fit change my production systems?
Only through the permissions wey you grant am. The default community runner dey record local incident summary; other investigation runtimes depend on the runner wey you configure. Keep production credentials limited to read access. Opening pull requests need separate GitHub write permissions for branches and pull requests. Treat write access to production as a separate decision wey you make deliberately, because agent wey fit restart services na much bigger commitment pass agent wey only reads telemetry and writes patch for review.
I suppose pin a commit or track main?
Pin a commit. As of 13 October 2026, the repository no get release tags. Record the SHA wey you test, deploy that one, and read the diff before you move forward. git log --oneline <old-sha>..main na the review, and the per-app .env.example files na the first place to check for newly required variables after any bump.