Self-Host Superlog untuk Triase Log dengan AI

Apa yang sebenarnya diinstal oleh self-hosting Superlog

Untuk melakukan self-hosting Superlog, clone repositori, jalankan Postgres, ClickHouse, dan collector OpenTelemetry dengan Docker Compose, jalankan satu migrasi database, lalu start empat service Node dari source code. Aplikasi Anda mengirim trace, log, dan metrik OTLP (protokol OpenTelemetry) ke port intake. Superlog membuat fingerprint, mengelompokkan item yang berulang menjadi satu incident, lalu agent menulis analisis awal untuk triage. Instalasi ini membutuhkan waktu satu sore. Footprint dan batasan sebenarnya adalah bagian yang perlu dibaca sebelum Anda mulai.

Superlog menggunakan lisensi Apache 2.0 dan tersedia di github.com/superloglabs/superlog. Per Agustus 2026, repositori ini memiliki sekitar 1.2k star, sekitar 460 commit pada main, dan sama sekali tidak memiliki release tag. Poin terakhir tersebut memengaruhi instalasi: git checkout v1.0.0 tidak memiliki apa pun untuk di-checkout, sehingga Anda harus menentukan commit sendiri atau menjalankan versi main yang kebetulan tersedia pada pagi saat Anda melakukan clone.

Jawaban Superlog yang tidak diberikan Uptime Kuma dan Langfuse

Dari luar, alat pemantauan self-hosted terlihat dapat saling menggantikan. Kenyataannya tidak demikian. Memilih alat yang salah hanya menghabiskan sumber daya server tanpa manfaat.

• Uptime Kuma memeriksa endpoint Anda dari luar dan menjawab satu pertanyaan: apakah layanan aktif.
• Zabbix memantau host dan service pada Ubuntu 24.04, termasuk CPU, memori, disk, dan status service berdasarkan ambang batas yang Anda tetapkan.
• Langfuse melacak panggilan LLM, lalu mencatat prompt, model, token, latensi, dan biaya setiap panggilan.
• Superlog mengambil telemetri yang sudah dihasilkan service biasa Anda, lalu mengubah kegagalan berulang menjadi insiden.

Superlog menjawab pertanyaan yang berbeda: sesuatu rusak, apa yang rusak, dan mengapa. Superlog tidak berfokus pada panggilan LLM dan tidak memeriksa sistem Anda dari luar. Superlog menerima OTLP dari kode aplikasi biasa Anda dan menempatkan agent pada tahap triage, yaitu pemeriksaan awal yang biasanya dilakukan oleh petugas on-call.

Perbedaan yang penting untuk anggaran VPS adalah penyimpanan. Uptime Kuma dapat berjalan dengan baik pada RAM 1 GB karena hanya menyimpan beberapa ribu hasil pemeriksaan. Superlog menggunakan column store karena telemetri ditulis sekali, lalu dikuerikan berdasarkan rentang waktu pada jutaan baris. Itulah fungsi ClickHouse dan alasan Postgres tidak digunakan untuk kebutuhan tersebut. Postgres tetap berada dalam stack untuk menyimpan data relasional berukuran kecil: project, pengguna, insiden, dan kunci ingest.

Apa yang sebenarnya dijalankan oleh docker compose up -d?

Tiga container, dan tidak satu pun di antaranya adalah Superlog. Hal ini mengejutkan orang yang mengharapkan instalasi dengan satu perintah.

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

Aplikasi Superlog berjalan pada host, dari source code, dan dimulai oleh pnpm dev. Hingga August 2026, repository ini tidak memiliki file compose untuk production. Jadi, instalasi jangka panjang memerlukan unit systemd Anda sendiri untuk setiap aplikasi yang menjalankan script start, atau Dockerfile per aplikasi yang tersedia di tree.

Perhatikan jalur yang ditempuh span, karena setiap kegagalan di bawah ini berarti satu hop pada jalur tersebut terputus. Aplikasi Anda mengirimkan OTLP ke proxy intake Superlog. Proxy mengautentikasi request menggunakan ingest key Anda, menambahkan project id ke dalamnya, lalu meneruskannya ke collector. Collector menghapus atribut superlog.* yang coba ditetapkan oleh client, menambahkan superlog.project_id dari header yang diberikan oleh proxy, mengelompokkan data, lalu menulisnya ke ClickHouse. Aplikasi web dan API kemudian membaca kembali telemetry dari ClickHouse, sedangkan data lainnya dibaca dari Postgres.

Penghapusan atribut tersebut merupakan kontrol multitenancy yang nyata, bukan sekadar hiasan. Tanpa kontrol ini, siapa pun yang memegang ingest key yang valid dapat menetapkan superlog.project_id sendiri dan menulis data ke project lain.

Seberapa besar VPS yang diperlukan?

Siapkan 4 vCPU, 8 GB RAM, dan 40 GB SSD untuk instalasi single-node dengan volume ingest rendah. Ini adalah batas minimum untuk perencanaan, bukan hasil pengukuran. Gunakan ukuran ini sebagai titik awal dan bandingkan dengan trafik Anda sendiri.

Memori digunakan oleh empat komponen. ClickHouse dirancang untuk mesin dengan RAM besar dan nilai default-nya mengasumsikan kondisi tersebut. Postgres 16 relatif ringan di sini karena menyimpan metadata, bukan telemetri. Collector juga relatif ringan. Namun, empat proses Node tidak ringan: server pengembangan Vite dan tiga proses tsx watch masing-masing dapat menggunakan ratusan megabyte. Karena itu, pnpm dev pada mesin dengan RAM 2 GB akan menimbulkan masalah.

Disk adalah masalah yang lebih sulit terlihat. pnpm install pada monorepo ini mengunduh AWS SDK, client ClickHouse, OpenTelemetry SDK, dan toolchain React sebelum Anda meng-ingest satu span pun. Setelah itu, ClickHouse terus bertambah sesuai trafik Anda. Ukur keduanya:

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 volume rendah, dengan beberapa service yang mengirim beberapa ratus span per menit, mesin tetap ringan dan ClickHouse hampir selalu idle. Beban yang menyebabkan masalah adalah lonjakan: satu deployment yang bermasalah dapat menghasilkan ribuan error identik per menit. Fingerprinting menggabungkan error tersebut menjadi satu incident bagi pembaca, tetapi ClickHouse tetap menulis setiap baris di balik layar.

Masa retensi ditentukan oleh Anda. ClickHouse exporter milik collector membuat tabel, otel_traces, otel_logs, dan satu tabel untuk setiap jenis metrik. Exporter hanya menerapkan time to live jika konfigurasi di infra/collector/config.yaml menetapkannya. Tidak ada data yang kedaluwarsa secara otomatis. Karena itu, satu bulan dengan trafik tinggi dapat memenuhi seluruh disk jika tidak direncanakan.

Instal dari commit yang dipatok

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 pun, dan itu merupakan hasil yang diharapkan per August 2026. Pilih commit yang sudah Anda uji, lalu gunakan commit tersebut:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Selanjutnya, toolchain:

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

package.json mendeklarasikan engines.node sebagai >=20.0.0 dan packageManager sebagai pnpm@9.12.0. Jika instalasi dijalankan pada Node versi lama, pnpm berhenti dengan ERR_PNPM_UNSUPPORTED_ENGINE dan menyebutkan versi yang diperlukan. Paket nodejs dalam arsip Ubuntu 24.04 lebih lama daripada versi 20. Karena itu, instal Node 20 atau yang lebih baru dari NodeSource atau nvm. Repository menyediakan .nvmrc, sehingga nvm use memilih versi yang sesuai jika Anda menggunakan nvm.

pnpm install
docker compose up -d
docker compose ps

Tunggu pemeriksaan kesehatan selesai. Jangan menganggap up -d berarti layanan sudah siap. Postgres dan ClickHouse sama-sama mendeklarasikan pemeriksaan tersebut dalam file compose:

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

ClickHouse merespons pada Ok., sedangkan pg_isready merespons pada accepting connections. Jika koneksi ke 8123 ditolak, container masih dalam proses start atau sudah berhenti. docker compose logs clickhouse menunjukkan penyebabnya, sedangkan docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled melaporkan true ketika kernel menghentikannya karena kekurangan memori. Ini menunjukkan bahwa server terlalu kecil, bukan bahwa konfigurasi Anda bermasalah.

Selanjutnya, jalankan migrasi dan aplikasi:

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

Perhatikan portnya: 5434, bukan 5432. File compose memublikasikan Postgres pada port 5434 agar tidak bertabrakan dengan Postgres yang sudah terpasang pada host. File .env.example aplikasi juga menggunakan port tersebut, dengan DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Jika migrasi diarahkan ke port 5432 pada server yang sudah menjalankan Postgres, koneksi dapat ditolak. Yang lebih buruk, migrasi dapat diterapkan ke database yang salah.

pnpm dev memulai empat proses yang tercantum dalam Procfile milik repository: api, web, worker, dan proxy. Setiap proses menyalurkan outputnya ke tmp/logs/, sehingga tail -f tmp/logs/proxy.log adalah lokasi untuk memantau ingest. README menempatkan aplikasi web pada http://localhost:5173, API pada http://localhost:4100, dan intake OTLP pada http://localhost:4101.

Pastikan terlebih dahulu proses apa yang benar-benar membuka port sebelum mengarahkannya ke sana:

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

Hal ini penting untuk langkah berikutnya. Proxy membaca portnya sendiri dari variabel lingkungan PORT dan menggunakan port 4000 jika PORT tidak disetel. Development stack mengaturnya secara otomatis. Unit systemd yang Anda tulis sendiri tidak melakukannya. Karena itu, exporter yang diarahkan ke 4101 ketika proxy mendengarkan pada 4000 akan gagal dengan koneksi ditolak tanpa memberikan petunjuk lain.

Kirim satu trace, hasilkan satu error, lihat satu insiden

Buat project di aplikasi web, lalu salin ingest key-nya. Intake mengautentikasi setiap request menggunakan key tersebut. Karena itu, telemetry yang dikirim tanpa key tidak pernah mencapai ClickHouse.

Arahkan OpenTelemetry SDK apa pun ke intake menggunakan environment variable standar:

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 membaca key dari header x-api-key. Intake juga menerima authorization: bearer YOUR_INGEST_KEY jika exporter lebih mudah dikonfigurasi dengan cara tersebut. Intake menyediakan tiga path OTLP standar, yaitu /v1/traces, /v1/logs, dan /v1/metrics, serta /health.

Ada satu kesalahan umum yang perlu diperhatikan. OTEL_EXPORTER_OTLP_ENDPOINT adalah base URL, dan SDK menambahkan signal path ke URL tersebut. Variable khusus signal seperti OTEL_EXPORTER_OTLP_TRACES_ENDPOINT digunakan persis seperti yang ditulis, tanpa penambahan path. Jika variable khusus signal diatur ke http://127.0.0.1:4101, setiap export dikirim ke /. Path tersebut bukan route, sehingga tidak ada data yang tiba. SDK mencatat kegagalan export, sementara aplikasi Anda terlihat sehat.

Untuk service Node, alur tanpa perubahan kode sudah cukup untuk membuktikan pipeline:

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

Sekarang buat satu komponen gagal dengan sengaja. Route apa pun yang menghasilkan exception dapat digunakan:

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

Periksa setiap tahap secara berurutan. Celah pertama menunjukkan tahap yang gagal:

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

Jumlah otel_traces yang terus meningkat saat aplikasi web kosong menunjukkan ketidaksesuaian project. Periksa project yang terkait dengan ingest key tersebut. Jumlah yang tetap saat ada aktivitas di log proxy mengarah ke collector atau penulisan ke ClickHouse. Karena itu, baca docker compose logs collector. Jika tidak ada aktivitas sama sekali di log proxy, exporter tidak pernah mencapai intake. Penyebabnya dapat berupa port yang salah, path yang salah, atau key yang ditolak.

Di aplikasi web, kegagalan berulang tersebut muncul sebagai satu insiden, bukan satu baris untuk setiap request. Superlog membuat fingerprint dari signal yang masuk dan mengelompokkan signal yang cocok. Perbedaannya adalah inbox berisi 4,000 error identik menjadi satu halaman yang berisi satu error. Agent kemudian menulis hasil investigasinya di atas grup tersebut.

Tahap investigasi memanggil model. Karena itu, worker memerlukan model provider yang telah dikonfigurasi. Ambil nama variable tersebut dari file .env.example di dalam setiap direktori aplikasi pada commit yang Anda pin, bukan dari tulisan eksternal mana pun. Nama variable tersebut berubah mengikuti main. Hal yang sama berlaku untuk integrasi GitHub dan Sentry. Keduanya memiliki dokumen konfigurasi sendiri di docs/github-app-setup.md dan docs/sentry-app-setup.md, sedangkan payload webhook didokumentasikan di docs/webhooks.md.

Jaga endpoint intake tetap privat, dan agen dalam mode hanya-baca

Docker memublikasikan port container pada 0.0.0.0 secara default. Port yang dipublikasikan tersebut melewati ufw karena Docker menulis aturannya sendiri ke dalam chain DOCKER-USER, yang dievaluasi sebelum ufw memeriksa paket. Pada VPS dengan IP publik, file compose saat dirilis memublikasikan ClickHouse HTTP pada 8123 dan Postgres pada 5434 sehingga dapat dijangkau dari Internet. Kredensial dalam file tersebut adalah default untuk pengembangan: pengguna ClickHouse default dengan kata sandi kosong, serta Postgres dengan postgres sebagai pengguna dan kata sandi.

Ikat port tersebut ke loopback. Setiap port yang dipublikasikan dalam file compose mengambil sisi host-nya dari variabel lingkungan. Jadi, file .env di root repositori sudah cukup:

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

Verifikasi hasilnya sebelum mempercayainya, lalu buat ulang container:

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

docker compose config mencetak file hasil resolusi. Dengan demikian, Anda dapat membaca 127.0.0.1:5434:5432, bukan menebak. ss seharusnya kemudian menampilkan 127.0.0.1:5434 dan tidak pernah 0.0.0.0:5434. Jangan mencoba memperbaikinya dengan file override compose yang mendeklarasikan ulang ports. Compose menggabungkan daftar port dari beberapa file, bukan menggantinya. Akibatnya, kedua binding tetap ada dan binding publik masih terbuka.

Endpoint intake memerlukan perlindungan yang sama. Kunci ingest dikirim dalam header, sehingga endpoint tersebut memerlukan TLS (transport layer security) di depannya. Hentikan TLS pada nginx atau Caddy di depan proxy, atau letakkan ingest di dalam jaringan privat atau tunnel WireGuard. Aplikasi web pada 5173 adalah server pengembangan Vite dan sama sekali tidak boleh menghadap Internet.

Berikutnya, agen itu sendiri. Klaim utama Superlog adalah bahwa agen menyelidiki masalah dan mengusulkan perbaikan. Kata pentingnya adalah mengusulkan. Pertahankan agen dalam mode hanya-baca terhadap production sampai Anda mengamati cara kerjanya pada beberapa insiden nyata. Berikan scope baca kepada GitHub App dan izinkan aplikasi tersebut membuat pull request untuk Anda tinjau. Agen yang membaca telemetri lalu menulis patch akan berguna. Agen yang dapat me-restart service Anda memiliki tingkat risiko yang berbeda. Keputusan tersebut harus dibuat secara sengaja, bukan diterima sebagai default. Biaya juga perlu diperhatikan karena setiap penyelidikan merupakan pemanggilan model: anggarkan biaya agen pada VPS sebelum mengarahkannya ke sistem production yang bising, dan simpan catatan tentang tindakan yang benar-benar dilakukan agen agar pull request yang tidak terduga memiliki jejak audit.

Kegagalan yang akan Anda temui dan string yang menamainya

• ERR_PNPM_UNSUPPORTED_ENGINE selama pnpm install berarti Node lebih lama daripada versi 20. node -v mengonfirmasinya dalam satu baris.
• ECONNREFUSED 127.0.0.1:5434 selama migrasi berarti compose stack belum berjalan, atau DATABASE_URL menetapkan port yang salah.
• ClickHouse yang terus-menerus melakukan restart biasanya mengalami masalah memori. Baca docker compose logs clickhouse, lalu periksa apakah container memiliki OOMKilled dengan status true.
• Exporter yang melaporkan keberhasilan sementara aplikasi web tetap kosong biasanya berarti data dikirim langsung ke collector pada port 4318. Jalur ini melewati pemberian penanda project yang dilakukan proxy.
• Connection refused pada port 4101 dalam instalasi production berarti proxy kembali menggunakan PORT=4000. Tetapkan PORT secara eksplisit dalam unit file.
• docker compose ps yang menampilkan 0.0.0.0:8123 berarti binding loopback Anda tidak diterapkan. Jalankan docker compose config dan baca port yang telah di-resolve.

Flawless, HyperProbe, dan posisi Superlog

Kategori ini masih baru, dan setiap alat berbeda dalam hal bagian yang boleh diakses oleh agent. Flawless adalah alat AI SRE (site reliability engineering) open source yang ditujukan untuk Kubernetes. Alat ini membaca data dari stack Prometheus, Loki, dan Grafana yang sudah ada, bukan mengelola pipeline tersebut. HyperProbe mengambil pendekatan sebaliknya. Produk ini di-hosting dan, per Agustus 2026, bersifat closed source. HyperProbe menempatkan probe read-only di dalam proses yang sedang berjalan untuk menangkap state variabel, lalu mengekspos state tersebut kepada assistant melalui MCP (model context protocol).

Superlog berada di antara keduanya. Superlog mengelola pipeline secara menyeluruh, mulai dari penerimaan OTLP hingga penyimpanan di ClickHouse. Agent ditempatkan pada tahap triage, bukan tahap perbaikan. Karena desain tersebut, self-hosting Superlog merupakan keputusan infrastruktur, bukan container yang dapat dibiarkan tanpa pengelolaan. Setelah menjalankan Superlog, Anda juga menjalankan column store. Komponen ini memerlukan pengelolaan yang sama seperti database lain yang Anda miliki.

FAQ

Berapa banyak RAM yang dibutuhkan Superlog yang di-host sendiri?

Siapkan 8 GB RAM, 4 vCPU, dan disk 40 GB untuk satu node dengan volume ingest rendah. Stack ini terdiri atas Postgres, ClickHouse, collector OpenTelemetry, dan empat proses Node, sementara ClickHouse memerlukan ruang sumber daya tambahan. VPS dengan RAM 1 GB atau 2 GB tidak cukup: pnpm install saja sudah berat, dan ClickHouse dapat dihentikan oleh kernel karena kehabisan memori saat beban tinggi. Ukur angka pada sistem Anda sendiri dengan docker stats --no-stream dan free -m, bukan dengan mengandalkan angka yang dipublikasikan, termasuk angka ini.

Ke port mana exporter OTLP harus diarahkan?

Arahkan ke proxy intake Superlog, yang menurut README berjalan pada http://localhost:4101. Proxy ini menyediakan /v1/traces, /v1/logs, dan /v1/metrics, serta melakukan autentikasi menggunakan ingest key proyek Anda yang diambil dari header x-api-key atau header authorization: bearer. Port 4318 adalah port collector OpenTelemetry di bawahnya. Mengekspor data langsung ke port tersebut melewati proxy, padahal proxy adalah komponen yang menambahkan project id ke data. Proxy menggunakan port 4000 sebagai fallback jika PORT tidak disetel. Jalankan ss -lntp dan pastikan port yang digunakan sebelum mengasumsikan portnya 4101.

Apakah Superlog menggantikan Uptime Kuma atau Zabbix?

Tidak. Uptime Kuma menjawab apakah endpoint merespons dari luar jaringan Anda, sedangkan Zabbix memantau metrik host dan service berdasarkan ambang batas yang Anda tetapkan. Superlog menerima trace, log, dan metrik yang dikirim aplikasi Anda, lalu mengelompokkan kegagalan berulang menjadi incident. Tetap gunakan probe uptime eksternal, karena probe yang berjalan di tempat lain tetap dapat melaporkan ketika server yang menjalankan pipeline telemetry Anda mengalami kegagalan.

Apakah agent Superlog dapat mengubah sistem production saya?

Hanya melalui permission yang Anda berikan. Output-nya berupa investigasi dan usulan perubahan yang ditinjau oleh manusia. Pada tahap awal, batasi GitHub App pada scope read dan izinkan pull request. Batasi juga setiap credential yang dimiliki worker pada akses baca. Perlakukan akses tulis ke production sebagai keputusan terpisah yang dibuat secara sengaja, karena agent yang dapat me-restart service merupakan tanggung jawab yang jauh lebih besar daripada agent yang membaca telemetry dan menulis patch untuk ditinjau.

Sebaiknya saya mengunci commit atau mengikuti main?

Kunci satu commit. Hingga August 2026, repository ini tidak memiliki release tag. Oleh karena itu, main adalah satu-satunya target yang terus berubah, dengan perubahan beberapa commit setiap minggu. Catat SHA yang telah Anda uji, deploy commit tersebut, lalu baca diff sebelum melanjutkan. git log --oneline <old-sha>..main adalah bagian yang perlu ditinjau, sedangkan file .env.example per aplikasi adalah tempat pertama yang harus diperiksa untuk menemukan variable baru yang diwajibkan setelah pembaruan.