Cara Self-host Superlog untuk AI-triaged Logs

Perkara yang sebenarnya dipasang oleh Superlog untuk self-hosting

Untuk melakukan self-hosting Superlog, anda perlu mengklon repositori, menjalankan Postgres, ClickHouse dan pengumpul OpenTelemetry menggunakan Docker Compose, melaksanakan satu migrasi pangkalan data, kemudian memulakan empat servis Node daripada kod sumber. Aplikasi anda menghantar trace, log dan metrik OTLP (OpenTelemetry protocol) ke port penerimaan, Superlog melakukan fingerprint terhadap data tersebut, mengumpulkan data yang berulang menjadi satu insiden, dan ejen akan menulis penilaian awal (triage). Pemasangan ini mengambil masa satu petang. Jejak penggunaan dan had sebenar adalah bahagian yang perlu dibaca sebelum anda bermula.

Superlog dilesenkan di bawah Apache 2.0 dan boleh didapati di github.com/superloglabs/superlog. Sehingga Ogos 2026, ia mempunyai kira-kira 1.2k bintang, lebih kurang 460 komit pada main, dan tiada tag keluaran (release tags) langsung. Perkara terakhir ini mempengaruhi proses pemasangan: git checkout v1.0.0 tidak mempunyai apa-apa untuk disemak keluar (check out), jadi anda perlu menetapkan (pin) komit sendiri atau menjalankan apa sahaja main yang ada pada pagi anda mengklonnya.

Apakah yang dijawab oleh Superlog yang tidak dijawab oleh Uptime Kuma dan Langfuse

Alat pemantauan yang dihoskan sendiri kelihatan boleh ditukar ganti dari luar. Hakikatnya tidak, dan menjalankan alat yang salah akan memakan sumber pelayan anda tanpa sebarang manfaat.

• Uptime Kuma menguji endpoint anda dari luar dan menjawab satu soalan: adakah ia aktif.
• Zabbix memantau hos dan servis pada Ubuntu 24.04, dengan CPU, memori, cakera dan status servis berdasarkan ambang yang anda tetapkan.
• Langfuse menjejak panggilan LLM, merekodkan prompt, model, token, latensi dan kos bagi setiap satu.
• Superlog mengambil telemetri yang sudah pun dikeluarkan oleh servis biasa anda dan menukarkan kegagalan berulang menjadi insiden.

Superlog menjawab soalan yang berbeza: sesuatu telah rosak, apa yang rosak, dan mengapa. Ia tidak mempunyai pendapat tentang panggilan LLM dan ia tidak menguji anda dari luar. Ia menyerap OTLP daripada kod aplikasi biasa anda dan meletakkan ejen pada langkah triaj, iaitu langkah pertama yang akan dilakukan oleh manusia yang bertugas (on-call) walau apa pun.

Perbezaan yang penting bagi bajet VPS ialah storan. Uptime Kuma berjalan dengan lancar pada 1 GB RAM kerana ia hanya menyimpan beberapa ribu hasil semakan. Superlog membawa storan lajur (column store), kerana telemetri ditulis sekali dan kemudian disoal mengikut julat masa merentasi berjuta-juta baris. Itulah tujuan ClickHouse dan bukan tujuan Postgres. Postgres masih berada dalam tindanan (stack), menyimpan data hubungan yang kecil: projek, pengguna, insiden dan kunci serapan (ingest keys).

Apakah yang sebenarnya dimulakan oleh docker compose up -d?

Tiga kontena, dan tiada satu pun daripadanya ialah Superlog. Ini mengejutkan mereka yang menjangkakan pemasangan satu arahan.

• postgres:16, diterbitkan pada port hos 5434
• clickhouse/clickhouse-server:26.1, pada 8123 untuk HTTP dan 9000 untuk protokol asli
• otel/opentelemetry-collector-contrib:0.150.1, pada 4317 untuk gRPC dan 4318 untuk OTLP melalui HTTP

Aplikasi Superlog berjalan pada hos, daripada kod sumber, dimulakan oleh pnpm dev. Tiada fail compose pengeluaran dalam repositori setakat Ogos 2026, jadi pemasangan jangka panjang bermakna anda perlu menyediakan unit systemd sendiri di sekeliling skrip start setiap aplikasi, atau menggunakan Dockerfile bagi setiap aplikasi yang disertakan dalam pepohon direktori.

Ingat laluan yang diambil oleh span, kerana setiap kegagalan di bawah merupakan gangguan pada satu peringkat laluan tersebut. Aplikasi anda menghantar OTLP ke proksi pengambilan Superlog. Proksi mengesahkan permintaan dengan kunci pengambilan anda, meletakkan id projek padanya, dan memajukannya ke pengumpul. Pengumpul membuang sebarang atribut superlog.* yang cuba ditetapkan oleh klien, menambah superlog.project_id daripada pengepala yang disediakan oleh proksi, melakukan pemprosesan kelompok, dan menulis ke ClickHouse. Aplikasi web dan API kemudian membaca telemetri semula daripada ClickHouse dan segala yang lain daripada Postgres.

Pembuangan atribut tersebut merupakan kawalan berbilang penyewa (multi-tenancy) yang sebenar, bukan sekadar hiasan. Tanpanya, sesiapa yang memegang satu kunci pengambilan yang sah boleh menetapkan superlog.project_id sendiri dan menulis ke dalam data projek lain.

Berapa besarkah saiz VPS yang diperlukan?

Rancang untuk menggunakan 4 vCPU, 8 GB RAM dan 40 GB SSD bagi pemasangan nod tunggal dengan volum kemasukan data yang rendah. Ini adalah tahap minimum perancangan, bukan ukuran mutlak, jadi anggap ia sebagai saiz permulaan dan semak semula berdasarkan trafik anda sendiri.

Memori digunakan untuk empat bahagian. ClickHouse dibina untuk mesin dengan RAM yang banyak dan tetapan lalainya mengandaikan perkara tersebut. Postgres 16 pula lebih sederhana di sini, kerana ia menyimpan metadata dan bukannya telemetri. Pengumpul (collector) juga bersifat sederhana. Empat proses Node tidak begitu: pelayan pembangunan Vite berserta tiga proses tsx watch masing-masing menyimpan ratusan megabait, itulah sebabnya pnpm dev pada mesin 2 GB akan menjadi perlahan.

Cakera merupakan masalah yang kurang ketara. pnpm install pada monorepo ini menarik AWS SDK, klien ClickHouse, OpenTelemetry SDK dan rantaian alat React sebelum anda memasukkan satu pun span. ClickHouse kemudiannya akan berkembang mengikut trafik anda. Ukur kedua-duanya:

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"

Pada volum rendah, dengan segelintir servis menghantar beberapa ratus span seminit, mesin tersebut kekal tenang dan ClickHouse kebanyakannya melahu. Beban yang memudaratkan ialah lonjakan trafik: satu deployment yang bermasalah menghasilkan beribu-ribu ralat serupa seminit. Fingerprinting akan menggabungkan ralat tersebut menjadi satu insiden untuk pembaca, namun ClickHouse tetap menulis setiap baris data di latar belakang.

Tempoh pengekalan data terpulang kepada anda untuk menetapkannya. Pengeksport ClickHouse bagi pengumpul tersebut mencipta jadual, otel_traces, otel_logs dan satu jadual bagi setiap jenis metrik, dan ia hanya akan menggunakan tempoh hayat (time to live) jika konfigurasi dalam infra/collector/config.yaml menetapkannya. Tiada data yang akan luput dengan sendirinya, jadi bulan yang sibuk akan menyebabkan cakera penuh melainkan anda merancang untuknya.

Memasang daripada commit yang disemat (pinned)

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

git tag -l tidak mencetak apa-apa adalah hasil yang dijangkakan setakat Ogos 2026. Pilih commit yang telah anda uji dan kekal pada commit tersebut:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Seterusnya, toolchain:

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

package.json mengisytiharkan engines.node sebagai >=20.0.0 dan packageManager sebagai pnpm@9.12.0. Jalankan pemasangan pada Node yang lebih lama dan pnpm akan berhenti dengan ERR_PNPM_UNSUPPORTED_ENGINE, yang menamakan versi yang diperlukan. Pakej nodejs dalam arkib Ubuntu 24.04 adalah lebih lama daripada versi 20, jadi pasang Node 20 atau lebih baharu daripada NodeSource atau nvm. Repositori tersebut membekalkan .nvmrc, jadi nvm use akan memilih versi yang dimaksudkan jika anda mempunyai nvm.

pnpm install
docker compose up -d
docker compose ps

Tunggu pemeriksaan kesihatan (health checks) selesai dan jangan hanya mempercayai up -d sebagai tanda ia sudah sedia. Postgres dan ClickHouse masing-masing mengisytiharkannya dalam fail compose:

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

ClickHouse menjawab Ok. dan pg_isready menjawab accepting connections. Ralat connection refused pada port 8123 bermakna kontena masih dalam proses memulakan atau telah mati. docker compose logs clickhouse menunjukkan statusnya, dan docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled melaporkan true apabila kernel mematikannya kerana masalah memori, yang menunjukkan pelayan anda terlalu kecil dan bukannya masalah pada konfigurasi anda.

Kemudian migrasi dan aplikasi:

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

Perhatikan port: 5434, bukan 5432. Fail compose menerbitkan Postgres pada 5434 supaya ia tidak bertembung dengan Postgres yang sudah dipasang pada hos, dan fail .env.example aplikasi sepadan dengan DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Jika anda menghalakan migrasi ke 5432 pada mesin yang sudah menjalankan Postgres, anda akan mendapat ralat connection refused atau lebih buruk lagi, migrasi akan digunakan pada pangkalan data yang salah.

pnpm dev memulakan empat proses yang disenaraikan dalam Procfile repositori: api, web, worker dan proxy. Setiap satu menyalurkan outputnya ke tmp/logs/, jadi tail -f tmp/logs/proxy.log ialah tempat anda memantau proses ingest. README meletakkan aplikasi web pada http://localhost:5173, API pada http://localhost:4100 dan intake OTLP pada http://localhost:4101.

Sahkan apa yang sebenarnya terikat (bound) sebelum anda menghalakan apa-apa kepadanya:

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

Ini penting untuk langkah seterusnya. Proksi membaca portnya sendiri daripada pemboleh ubah persekitaran PORT dan kembali kepada 4000 apabila PORT tidak ditetapkan. Stack pembangunan menetapkannya untuk anda. Unit systemd yang anda tulis sendiri tidak melakukannya, jadi pengeksport yang disasarkan ke 4101 terhadap proksi yang mendengar pada 4000 akan gagal dengan ralat connection refused tanpa memberikan petunjuk lain.

Send one trace, produce one error, see one incident

Create a project in the web app and copy its ingest key. The intake authenticates every request against that key, so telemetry sent without one never reaches ClickHouse.

Point any OpenTelemetry SDK at the intake using 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 reads the key from the x-api-key header, and also accepts authorization: bearer YOUR_INGEST_KEY if your exporter is easier to configure that way. It serves the three standard OTLP paths, /v1/traces, /v1/logs and /v1/metrics, plus /health.

One trap is worth naming. OTEL_EXPORTER_OTLP_ENDPOINT is a base URL and the SDK appends the signal path to it. The signal specific variables such as OTEL_EXPORTER_OTLP_TRACES_ENDPOINT are used exactly as written, with no path appended. Set the signal specific variable to http://127.0.0.1:4101 and every export posts to /, which is not a route, so nothing arrives and the SDK logs an export failure while your app looks healthy.

For a Node service the zero code path is enough to prove the pipeline:

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

Now break something on purpose. Any route that throws will do:

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

Check the hops in order, because the first gap tells you which one failed:

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

A rising count in otel_traces with an empty web app is a project mismatch, so check which project the ingest key belongs to. A flat count with activity in the proxy log points at the collector or the ClickHouse write, so read docker compose logs collector. No activity in the proxy log at all means the exporter never reached the intake: wrong port, wrong path, or a rejected key.

In the web app those repeated failures arrive as one incident rather than one row per request. Superlog fingerprints incoming signals and groups the matching ones, which is the difference between an inbox holding 4,000 identical errors and a page holding one. The agent then writes its investigation on top of that group.

The investigation step calls a model, so the worker needs a model provider configured. Take those variable names from the .env.example file inside each app directory of the commit you pinned rather than from any external write-up, because they move with main. The same applies to the GitHub and Sentry integrations, which carry their own setup documents at docs/github-app-setup.md and docs/sentry-app-setup.md, with webhook payloads documented in docs/webhooks.md.

Pastikan input peribadi dan ejen dalam mod baca sahaja

Docker menerbitkan port kontena pada 0.0.0.0 secara lalai, dan port yang diterbitkan itu memintas ufw kerana Docker menulis peraturannya sendiri ke dalam rantaian DOCKER-USER yang dinilai sebelum ufw melihat paket tersebut. Pada VPS dengan IP awam, fail compose yang dibekalkan meletakkan HTTP ClickHouse pada 8123 dan Postgres pada 5434 di mana internet boleh mencapainya. Kelayakan dalam fail tersebut adalah lalai pembangunan: pengguna ClickHouse default dengan kata laluan kosong, Postgres dengan postgres sebagai pengguna dan kata laluan.

Ikat port tersebut pada loopback. Setiap port yang diterbitkan dalam fail compose mengambil bahagian hos daripada pemboleh ubah persekitaran, jadi .env dalam root repositori sudah memadai:

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

Sahkan hasil sebelum anda mempercayainya, kemudian cipta semula kontena:

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

docker compose config mencetak fail yang telah diselesaikan, jadi anda boleh membaca 127.0.0.1:5434:5432 dan bukannya meneka. ss sepatutnya menunjukkan 127.0.0.1:5434 dan tidak sekali-kali 0.0.0.0:5434. Jangan cuba membaiki perkara ini dengan fail compose override yang mengisytiharkan semula ports, kerana Compose menggabungkan senarai port merentas fail dan bukannya menggantikannya, jadi anda akan berakhir dengan kedua-dua ikatan dan yang awam masih terbuka.

Input memerlukan penjagaan yang sama. Kunci ingest anda bergerak dalam header, jadi ia memerlukan TLS (transport layer security) di hadapannya: tamatkan TLS dalam nginx atau Caddy sebelum proksi, atau simpan ingest di dalam rangkaian peribadi atau terowong WireGuard. Aplikasi web pada 5173 adalah pelayan pembangunan Vite dan tidak sepatutnya menghadap internet sama sekali.

Kemudian ejen itu sendiri. Tawaran Superlog ialah ejen menyiasat dan mencadangkan pembaikan, dan perkataan penting di sini ialah mencadangkan. Pastikan ia dalam mod baca sahaja terhadap pengeluaran sehingga anda telah melihatnya berfungsi pada beberapa insiden sebenar. Berikan skop baca kepada GitHub App dan biarkan ia membuka pull request yang anda semak. Ejen yang membaca telemetri dan menulis patch adalah berguna. Ejen yang boleh memulakan semula servis anda adalah tahap risiko yang berbeza, dan itu harus menjadi keputusan yang anda buat dengan sengaja dan bukannya lalai yang anda warisi. Kos juga memerlukan perhatian yang sama, kerana setiap penyiasatan adalah panggilan model: belanjawan untuk perbelanjaan ejen pada VPS sebelum anda menghalakannya ke sistem pengeluaran yang sibuk, dan simpan rekod tentang apa yang sebenarnya dilakukan oleh ejen supaya pull request yang mengejutkan mempunyai jejak audit di belakangnya.

Kegagalan yang akan anda temui, dan rentetan yang menamakannya

• ERR_PNPM_UNSUPPORTED_ENGINE semasa pnpm install bermaksud Node lebih lama daripada 20. node -v mengesahkannya dalam satu baris.
• ECONNREFUSED 127.0.0.1:5434 semasa migrasi bermaksud tindanan compose tidak aktif, atau DATABASE_URL menamakan port yang salah.
• ClickHouse yang dimulakan semula secara berulang biasanya disebabkan oleh memori. Baca docker compose logs clickhouse, kemudian periksa bekas untuk OOMKilled yang bernilai true.
• Pengeksport yang melaporkan kejayaan sementara aplikasi web kekal kosong biasanya bermaksud data terus dihantar ke pengumpul pada 4318, yang melangkau pengecapan projek yang dilakukan oleh proksi.
• Connection refused pada 4101 dalam pemasangan pengeluaran bermaksud proksi kembali kepada PORT=4000. Tetapkan PORT secara eksplisit dalam fail unit.
• docker compose ps yang menunjukkan 0.0.0.0:8123 bermaksud ikatan loopback anda tidak berkesan. Jalankan docker compose config dan baca port yang diselesaikan.

Flawless, HyperProbe, dan kedudukan Superlog

Kategori ini masih baharu, dan alatan di dalamnya terbahagi berdasarkan perkara yang boleh dicapai oleh ejen. Flawless ialah alat AI SRE (site reliability engineering) sumber terbuka yang disasarkan untuk Kubernetes, yang membaca daripada tindanan Prometheus, Loki dan Grafana sedia ada dan bukannya memiliki talian paip (pipeline) tersebut. HyperProbe mengambil pendekatan sebaliknya: ia merupakan produk terhos, sumber tertutup setakat Ogos 2026, yang meletakkan probe baca sahaja di dalam proses yang sedang berjalan untuk menangkap keadaan pemboleh ubah dan mendedahkan keadaan tersebut kepada pembantu melalui MCP (model context protocol).

Superlog berada di antara kedua-duanya. Ia memiliki talian paip dari hujung ke hujung, bermula daripada pengambilan OTLP sehingga storan ClickHouse, dan ia meletakkan ejen pada langkah triaj dan bukannya pada langkah pembaikan. Reka bentuk itulah sebabnya mengapa pengehosan kendiri (self-hosting) alat ini merupakan keputusan infrastruktur dan bukannya sekadar kontena yang boleh dilupakan. Apabila anda menjalankan Superlog, anda menjalankan storan lajur (column store), dan ia memerlukan penjagaan yang sama seperti mana-mana pangkalan data lain yang anda miliki.

FAQ

Berapakah RAM yang diperlukan oleh Superlog yang dihoskan sendiri?

Rancang untuk 8 GB RAM, 4 vCPU dan 40 GB cakera bagi satu nod pada volum kemasukan rendah. Stak ini terdiri daripada Postgres, ClickHouse, pengumpul OpenTelemetry dan empat proses Node, dan ClickHouse memerlukan ruang kepala (headroom). VPS 1 GB atau 2 GB tidak mencukupi: pnpm install sahaja sudah berat, dan ClickHouse akan dimatikan oleh kernel (out of memory killer) di bawah beban. Ukur angka anda sendiri dengan docker stats --no-stream dan free -m daripada mempercayai mana-mana angka yang diterbitkan, termasuk angka ini.

Port manakah yang perlu saya halakan pengeksport OTLP saya?

Proksi kemasukan Superlog, yang diletakkan oleh README pada http://localhost:4101. Ia menyediakan /v1/traces, /v1/logs dan /v1/metrics, serta mengesahkan dengan kunci kemasukan projek anda yang diambil daripada pengepala x-api-key atau daripada pengepala authorization: bearer. Port 4318 ialah pengumpul OpenTelemetry di bawahnya, dan mengeksport ke sana secara terus akan melangkau proksi, iaitu komponen yang mencap ID projek anda pada data tersebut. Proksi akan kembali ke port 4000 apabila PORT tidak ditetapkan, jadi jalankan ss -lntp dan sahkan port yang diikat sebelum menganggap ia adalah 4101.

Adakah Superlog menggantikan Uptime Kuma atau Zabbix?

Tidak. Uptime Kuma menjawab sama ada titik akhir (endpoint) bertindak balas dari luar rangkaian anda, dan Zabbix memantau metrik hos dan servis berdasarkan ambang yang anda tetapkan. Superlog menggunakan trace, log dan metrik yang dikeluarkan oleh aplikasi anda serta mengumpulkan kegagalan berulang menjadi insiden. Kekalkan probe uptime luaran di sampingnya, kerana probe yang berjalan di tempat lain masih melaporkan apabila kotak yang menempatkan talian paip telemetri anda adalah perkara yang mati.

Bolehkah ejen Superlog mengubah sistem pengeluaran saya?

Hanya melalui kebenaran yang anda berikan. Outputnya ialah penyiasatan dan cadangan perubahan yang disemak oleh manusia. Kekalkan GitHub App pada skop bacaan dengan pull request pada mulanya, dan pastikan sebarang kelayakan yang dipegang oleh pekerja dihadkan kepada bacaan sahaja. Anggap akses tulis ke pengeluaran sebagai keputusan berasingan yang dibuat secara sengaja, kerana ejen yang boleh memulakan semula servis adalah komitmen yang jauh lebih besar daripada ejen yang membaca telemetri dan menulis patch untuk semakan.

Patutkah saya menyematkan (pin) commit atau menjejaki main?

Sematkan commit. Tiada tag keluaran dalam repositori setakat Ogos 2026, jadi main adalah satu-satunya sasaran bergerak yang ditawarkan dan ia mengambil beberapa commit seminggu. Rekodkan SHA yang anda uji, gunakan versi tersebut, dan baca diff sebelum anda bergerak ke hadapan. git log --oneline <old-sha>..main ialah semakan, dan fail .env.example bagi setiap aplikasi adalah tempat pertama untuk mencari pemboleh ubah yang baru diperlukan selepas sebarang peningkatan.