Superlog 自架:資源需求與實際限制
了解 Superlog 自架會安裝的 Postgres、ClickHouse、OpenTelemetry collector 與 4 個 Node 服務,並先掌握 VPS 資源需求、儲存成本與無 release tags 的版本風險。
Superlog 自架實際會安裝的內容
若要自架 Superlog,請先複製儲存庫,使用 Docker Compose 啟動 Postgres、ClickHouse 和 OpenTelemetry collector,執行一次資料庫 migration,然後從原始碼啟動 4 個 Node 服務。您的應用程式會將 OTLP (OpenTelemetry protocol) traces、logs 和 metrics 傳送到 intake port。Superlog 會為這些資料建立指紋,將重複項目歸併為單一 incident,而預設的 community agent runner 會記錄本機 incident summary。安裝約需一個下午。開始前,最值得閱讀的是其資源需求與實際限制。
Superlog 採用 Apache 2.0 授權,儲存庫位於 github.com/superloglabs/superlog。截至 13 October 2026,該專案約有 1.5k 個 stars,在 main 上約有 490 次 commits,且完全沒有 release tags。請自行固定某個 commit,不要直接執行您複製儲存庫當天早上 main 所指向的內容。
Superlog 能回答 Uptime Kuma 和 Langfuse 無法回答的問題
從外部觀察時,自架監控工具看起來似乎可以互相替代。實際上並非如此,選錯工具只會浪費伺服器資源,卻得不到任何好處。
- Uptime Kuma 從外部探測端點,只能回答一個問題:服務是否正常。
- Zabbix 在 Ubuntu 24.04 上監看主機與服務,並依據你設定的閾值檢查 CPU、記憶體、磁碟與服務狀態。
- Langfuse 追蹤 LLM 呼叫,記錄每次呼叫的提示、模型、token 數量、延遲與成本。
- Superlog 會接收一般服務已經產生的遙測資料,並將重複發生的失敗轉換為事件。
Superlog 處理的是另一個問題:哪個部分發生故障、故障原因是什麼,以及為什麼會發生。它不處理 LLM 呼叫,也不會從外部探測你的服務。它會接收一般應用程式程式碼產生的 OTLP,並在分類處理步驟中加入 agent;這正是值班人員通常會先執行的初步檢查。
對 VPS 預算而言,真正重要的差異在於儲存層。Superlog 使用 column store,因為遙測資料只會寫入一次,之後再依時間範圍查詢數百萬筆資料。這正是 ClickHouse 的用途,而不是 Postgres 的用途。Postgres 仍然位於整體架構中,用來儲存少量的關聯式資料:專案、使用者、事件與 ingest key。
docker compose up -d 實際啟動了什麼?
會啟動 3 個容器,但其中沒有 Superlog。原本以為執行一個指令就能完成安裝的人,通常會對此感到意外。
postgres:16,發布至主機的 5434 埠clickhouse/clickhouse-server:26.1,使用 8123 提供 HTTP,並使用 9000 提供原生通訊協定otel/opentelemetry-collector-contrib:0.150.1,使用 4317 提供 gRPC,並使用 4318 提供透過 HTTP 的 OTLP
Superlog 應用程式會直接從原始碼在主機上執行,由 pnpm dev 啟動。截至 13 October 2026,該 repository 中沒有 production compose 檔案。因此,若要長期執行,必須自行建立 systemd units,或使用 tree 中各應用程式附帶的 Dockerfiles。api、worker 和 proxy 應用程式各有一個 start script,可用來包裝成 unit。web 應用程式沒有這類 script:它是 Vite 應用程式,因此可使用其 build script 建置,再由 nginx 或 Caddy 將輸出作為靜態檔案提供;也可以執行其 preview script,而該 script 是 vite preview。
請記住一個 span 經過的路徑,因為以下每個故障,都是其中一個 hop 中斷所造成。你的應用程式會將 OTLP 發送至 Superlog intake proxy。proxy 使用你的 ingest key 驗證請求,在請求上標記 project id,然後將其轉送至 collector。collector 會移除 client 嘗試設定的任何 superlog.* attributes,從 proxy 提供的 header 加入 superlog.project_id,再進行批次處理並寫入 ClickHouse。web 應用程式與 API 會從 ClickHouse 讀回 telemetry,其他資料則從 Postgres 讀取。
移除這些 attributes 是實際的多租戶控制措施,不是裝飾功能。若沒有這項控制,任何持有有效 ingest key 的人,都能自行設定 superlog.project_id,並將資料寫入其他 project。
VPS 需要多大的規模?
若要在低資料攝取量下安裝單一節點,請規劃 4 vCPU、8 GB RAM 與 40 GB SSD。這是規劃下限,不是測量結果,因此應將其視為起始規模,並根據自身的網路流量進行驗證。
記憶體會用在 4 個部分。ClickHouse 是為擁有充足 RAM 的機器而設計,其預設值也以此為前提。Postgres 16 在這裡的需求不高,因為它儲存的是中繼資料,而不是遙測資料。collector 的需求也不高。4 個 Node process 包含 Vite development server,以及 3 個 tsx watch process;請在自己的主機上測量其記憶體用量。
磁碟是較不明顯的問題。這個 monorepo 中的 pnpm install 會在你攝取第一個 span 之前,先拉取 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"真正造成壓力的是突發流量:一次有問題的部署可能在 1 分鐘內產生數千個相同錯誤。指紋識別會將這些錯誤彙整為讀者看到的單一事件,但 ClickHouse 仍會在底層寫入每一筆資料列。
資料保留期限由你設定。collector 的 ClickHouse exporter 會建立資料表、otel_traces、otel_logs,以及每種 metric type 各自的資料表;只有在 infra/collector/config.yaml 中的設定指定 time to live 時,才會套用期限。資料不會自行過期,因此如果沒有事先規劃,繁忙使用 1 個月後可能會占滿整個磁碟。
從固定 commit 安裝
git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'git tag -l 截至 13 October 2026 沒有輸出才是預期結果。選擇你測試過的 commit,並固定使用該版本:
git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e接著處理工具鏈:
node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -vpackage.json 將 engines.node 宣告為 >=20.0.0,並將 packageManager 宣告為 pnpm@9.12.0。不相容的 Node 版本不一定會自動停止安裝:是否強制執行 engine 取決於設定,而 pnpm 9.12.0 在停用 engineStrict 時會走警告流程。Ubuntu 24.04 套件庫中的 nodejs 套件早於 20,因此請從 NodeSource 或 nvm 安裝 Node 20 或更新版本。儲存庫包含 .nvmrc,因此若已安裝 nvm,nvm use 會選擇指定的版本。
pnpm install
docker compose up -d
docker compose ps請等待健康檢查,不要只因為 up -d 顯示 ready 就認定服務已準備完成。Postgres 與 ClickHouse 都在 compose 檔案中宣告健康檢查:
curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgresClickHouse 回應 Ok.,而 pg_isready 回應 accepting connections。若 8123 拒絕連線,表示容器仍在啟動,或容器已停止。docker compose logs clickhouse 可顯示是哪一種情況,docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled 則會在 kernel 因記憶體不足將其終止時回報 true。這表示主機容量太小,而不是設定錯誤。
接著執行 migration 並啟動應用程式:
pnpm --filter @superlog/db db:migrate
pnpm dev請注意連接埠是 5434,不是 5432。compose 檔案會將 Postgres 發布到 5434,避免與主機上已安裝的 Postgres 發生衝突;應用程式的 .env.example 檔案也使用相同設定,並包含 DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog。如果在已執行 Postgres 的主機上,將 migration 指向 5432,可能會得到拒絕連線的結果;更嚴重時,migration 會套用到錯誤的資料庫。
pnpm dev 會執行 turbo run dev,透過 Turborepo 啟動各應用程式的 dev script,包括 api、web、worker 與 proxy,並將輸出混合在同一個終端機中。儲存庫的 Procfile 列出相同的 4 個程序,並將每個程序的輸出分別寫入 tmp/logs/。如果希望在 tail -f tmp/logs/proxy.log 中監看 ingest,請使用 overmind 或 foreman 等 Procfile runner 啟動,而不要使用 pnpm dev。README 將 web app 放在 http://localhost:5173,API 放在 http://localhost:4100,OTLP intake 放在 http://localhost:4101。
在將任何內容指向這些服務前,先確認實際綁定的連接埠:
ss -lntp | grep -E '4000|4100|4101|5173'
curl -sS http://127.0.0.1:4101/health這項資訊之後很重要。proxy 會從 PORT 環境變數讀取自己的連接埠;若未設定 PORT,則會使用 4000。它載入的 apps/proxy/.env.example 也會設定 PORT=4000,即使 README 列出的 intake 連接埠是 4101(兩者均於 13 October 2026 查核)。請使用 ss 顯示的連接埠。以下範例使用 4101;如果實際綁定的是 4000,請替換為 4000。你自行撰寫的 systemd unit 不會自動設定任何內容,除非在其中加入 PORT。因此,若 exporter 指向 4101,而 proxy 正在監聽 4000,連線會遭拒絕,且不會提供其他線索。
傳送一次 trace、產生一個錯誤、查看一個事件
在 web app 中建立專案,並複製其 ingest key。intake 會使用該 key 驗證每個請求,因此未附帶 key 的 telemetry 不會抵達 ClickHouse。
使用標準環境變數,將任何 OpenTelemetry SDK 指向 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 會從 x-api-key 標頭讀取 key。如果 exporter 使用這種設定方式較方便,也接受 authorization: bearer YOUR_INGEST_KEY。它提供 3 個標準 OTLP 路徑:/v1/traces、/v1/logs 和 /v1/metrics,以及 /health。
有一個容易踩到的問題需要特別說明。OTEL_EXPORTER_OTLP_ENDPOINT 是 base URL,SDK 會將 signal 路徑附加到該 URL。OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 等 signal 專用變數則會完全依照原值使用,不會附加路徑。若將 signal 專用變數設為 http://127.0.0.1:4101,每次 export 都會送到 /。這不是有效路由,因此不會有資料抵達;SDK 會記錄 export 失敗,但應用程式本身看起來仍然正常。
對於 Node 服務,不需修改程式碼即可驗證整個 pipeline:
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js現在刻意製造問題。任何會拋出例外的路由都可以:
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom依序檢查各個環節,因為第一個中斷的位置會指出失敗的環節:
tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'如果 otel_traces 的計數持續增加,但 web app 沒有資料,表示 project 不一致。請確認 ingest key 所屬的專案。如果計數沒有增加,但 proxy log 有活動,問題可能出在 collector 或 ClickHouse 寫入。請查看 docker compose logs collector。如果 proxy log 完全沒有活動,表示 exporter 從未抵達 intake:可能是連接埠錯誤、路徑錯誤或 key 被拒絕。
在 web app 中,這些重複失敗會合併成一個事件,而不是每個請求各顯示一列。Superlog 會為傳入的 signals 建立 fingerprint,並將相符的 signals 分組。這使收件匣從包含 4,000 筆相同錯誤,變成只顯示一個事件。預設的 community agent runner 會為該群組記錄本機事件摘要。
若要進行由模型支援的調查,必須設定 model provider 和相容的 agent runner;預設的 community runner 會記錄本機摘要。請從你所固定版本的 commit 中,每個 app 目錄內的 .env.example 檔案取得這些變數名稱,不要參考外部文章,因為它們會隨 main 一起變更。GitHub 和 Sentry integrations 也是如此;它們各自在 docs/github-app-setup.md 和 docs/sentry-app-setup.md 提供設定文件,webhook payload 則記載於 docs/webhooks.md。
維持接收端私有,並讓 agent 僅具讀取權限
Docker 預設會將容器埠發布到 0.0.0.0,而且這些已發布的埠會繞過 ufw。Docker 會在 nat table 中路由容器流量,因此,目的地是已發布埠的封包會在抵達 ufw 規則所在的 INPUT 與 OUTPUT chains 前先被轉送,ufw 完全無法介入。在具有公開 IP 的 VPS 上,隨附的 compose file 會將 ClickHouse HTTP 放在 8123,並將 Postgres 放在 5434,讓網際網路可以連入。該檔案中的憑證是開發環境預設值:ClickHouse user 為 default,密碼為空;Postgres 則以 postgres 同時作為 user 和 password。
將它們繫結至 loopback。compose file 中的每個 published port 都會從環境變數取得主機端設定,因此只要在 repository root 建立 .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信任設定前先驗證結果,然後重新建立 containers:
docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'docker compose config 會列印解析後的 file,讓你能直接讀取 127.0.0.1:5434:5432,不必猜測。接著,ss 應顯示 127.0.0.1:5434,且絕不應顯示 0.0.0.0:5434。如果主機 IP 不同,只在 Compose override file 中重新宣告 ports,會保留兩個 bindings;Compose 2.24.4 及更新版本支援 ports: !override,可用來取代整個 list。
接收端同樣需要謹慎處理。你的 ingest key 會隨 header 傳送,因此前方必須使用 TLS(transport layer security):在 proxy 前方以 nginx 或 Caddy 終止 TLS,或將 ingest 保留在 private network 或 WireGuard tunnel 中。位於 5173 的 web app 是 Vite development server,完全不應直接面向網際網路。
接著是 agent 本身。Superlog 的主張是 agent 會調查問題並提出修正,而關鍵在於「提出」。在觀察它處理幾個真實事件之前,先讓它對 production 維持 read only。read-only GitHub App 無法推送修正 branch 或開啟 pull requests;設定指南要求該工作流程具備 Contents 和 Pull requests 的 write permissions,並且需要 Issues 的 write permission 以發表 comments。能讀取 telemetry 並寫入 patch 的 agent 很有用。能重新啟動服務的 agent 則代表不同等級的風險;這應是你刻意做出的決定,而不是沿用預設設定。設定 model-backed runner 時,成本也需要同樣重視:在讓它處理吵雜的 production system 前,先規劃 VPS 上的 agent 支出,並保留agent 實際執行內容的紀錄,讓出現意外的 pull request 時,背後仍有 audit trail 可供追查。
會遇到的錯誤,以及用來識別這些錯誤的字串
- 在
pnpm install期間出現ERR_PNPM_UNSUPPORTED_ENGINE,表示引擎需求不相容。pnpm 9.12.0 會檢查 Node 和 pnpm 的需求;請查看錯誤訊息中的需求版本與目前版本,然後檢查node -v和pnpm -v。 - 遷移期間出現
ECONNREFUSED 127.0.0.1:5434,表示 compose stack 尚未啟動,或DATABASE_URL指定了錯誤的連接埠。 - 使用
docker compose logs clickhouse檢查 ClickHouse 是否重新啟動,然後檢查容器中的OOMKilled是否為true。 - exporter 回報成功,但 Web 應用程式仍沒有資料,通常表示資料直接送往 4318 上的 collector,略過了 proxy 所執行的 project stamping。
- 4101 上的連線遭拒通常表示 proxy 正在 4000 上監聽。4000 是程式的 fallback port,也是
.env.example設定的連接埠。請在 unit file 或應用程式的.env中明確設定PORT。 docker compose ps顯示0.0.0.0:8123,表示 loopback binding 未生效。執行docker compose config,然後查看解析後的連接埠。
Flawless、HyperProbe,以及 Superlog 的定位
這個類別仍在發展初期,而各工具對 agent 可接觸範圍的設計不同。Flawless repository 目前以 PolyForm Noncommercial 授權呈現 CISRE。CISRE 是用於 Kubernetes 與 cloud infrastructure 的 AI SRE(site reliability engineering)平台。HyperProbe 會將 probes 置於執行中的 process 內,以擷取變數狀態,並透過 MCP(model context protocol)將這些狀態提供給 assistant。它也記錄了使用 Docker Compose 與 license key 進行 self-hosting 的方式。
Superlog 位於兩者之間。它負責從 OTLP intake 到 ClickHouse storage 的完整 pipeline,並將 agent 放在 triage 階段,而不是 fix 階段。正因如此,self-hosting Superlog 是 infrastructure decision,而不是啟動後就能置之不理的 container。執行 Superlog 時,也是在執行 column store;它需要與其他由你管理的 database 一樣受到妥善維護。
FAQ
自架 Superlog 需要多少 RAM?
對於低資料攝取量的單一節點,請準備 8 GB RAM、4 vCPU 與 40 GB 磁碟空間。此堆疊包含 Postgres、ClickHouse、OpenTelemetry collector 及 4 個 Node 程序,而 ClickHouse 需要預留足夠的資源。請使用 docker stats --no-stream 與 free -m 測量實際數值,不要盲目採信任何已發布的數據,包括這個數值。
OTLP exporter 應指向哪個連接埠?
請指向 Superlog intake proxy;README 將其設定在 http://localhost:4101。它提供 /v1/traces、/v1/logs 與 /v1/metrics,並使用從 x-api-key 標頭或 authorization: bearer 標頭取得的專案 ingest key 進行驗證。4318 是底層 OpenTelemetry collector 的連接埠;直接匯出到該連接埠會略過 proxy,而 proxy 才是將專案 ID 標記到資料上的元件。PORT 未設定時,proxy 會回退到連接埠 4000;其 .env.example 也會將連接埠設為 4000。因此,請執行 ss -lntp,確認實際繫結的連接埠後,再假設使用 4101。
Superlog 能取代 Uptime Kuma 或 Zabbix 嗎?
不能。Uptime Kuma 用來確認從網路外部是否能收到端點回應;Zabbix 則依據你設定的門檻監控主機與服務的指標。Superlog 會接收應用程式產生的 traces、logs 與 metrics,並將重複發生的故障整理成 incidents。請同時保留外部 uptime probe,因為當承載 telemetry pipeline 的主機故障時,部署在其他位置的 probe 仍能回報該問題。
Superlog agent 能變更我的 production 系統嗎?
只能在你授予權限的範圍內變更。預設的 community runner 會記錄本機 incident 摘要;其他 investigation runtime 則取決於你設定的 runner。請將 production 憑證權限限制為讀取;若要開啟 pull request,則需要另外授予 GitHub 對 branches 與 pull requests 的寫入權限。請將 production 的寫入權限視為需要審慎決定的獨立事項,因為能重新啟動服務的 agent,所涉及的承諾遠高於只讀取 telemetry 並撰寫 patch 供審查的 agent。
應固定 commit,還是追蹤 main?
請固定 commit。截至 13 October 2026,repository 中沒有 release tags。記錄已測試的 SHA,部署該版本,並在升級前閱讀 diff。git log --oneline <old-sha>..main 是審查內容;任何升級後新增的必要變數,首先應查看各應用程式的 .env.example 檔案。