Superlog 社群版：把 OTLP 訊號收斂成 incident 的自架觀測工作區
Open-source observability tool that uses AI agents to self-heal your software
秒懂
- 它是什麼？
- Superlog 是 Apache-2.0 授權的開源觀測工具，接收 traces、logs、metrics，把雜訊歸併成 incident，並提供可插拔的 agent runner 介面。本文只根據 README 與 repo 結構，說明它的機制、啟動方式與採用邊界。
- 適合誰用？
- 如果你已經在用 OpenTelemetry，而且想要一個能自己跑起來、能把訊號歸成 incident 的工作區，Superlog 社群版值得先在本機試一輪：pnpm install、docker compose up -d、pnpm --filter @superlog/db db:migrate、pnpm dev 四步就能看到 Web 與 API。若你需要的是成熟的告警路由、值班排班與長期儲存治理，這個 repo 目前沒有提供對應元件，預設 community agent runner 也只寫入本機 incident 摘要，不是自動修復。
- 可以商用嗎？
- 可以。Apache-2.0 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
Superlog 想解決的是訊號太多、事件太少
觀測資料的常見困境不是收不到東西，而是收得太多。OTLP 一旦接上，traces、logs、metrics 三條管線同時湧入，值班的人面對的是幾百條各自獨立的告警，而不是一個可以判斷的故障單位。Superlog 的定位寫得很直接：它接收這三類訊號，把吵雜的訊號歸併成 incident，讓團隊有個本地優先的介面去查生產環境的問題。
它鎖定的對象是已經採用 OpenTelemetry 的團隊。這一點從 repo 結構看得出來：apps/proxy 是專門的 OTLP 接收端，不是通用的日誌收集器；packages/fingerprint 提供指紋計算的輔助函式，而指紋正是把重複訊號收斂到同一個 incident 的關鍵。如果你的服務還沒上 OTel，Superlog 不會幫你補上 instrumentation，你得先自己把 SDK 接好。
授權是 Apache-2.0，repo 明確標示這是 fully open-source, free community edition，包含 Web app、API、OTLP ingest proxy、worker、Postgres schema 與 ClickHouse 查詢。同一個 README 也提到 hosted 的 Superlog Cloud 有免費方案與付費方案。開源核心與託管版本的邊界，是評估時第一個要問清楚的問題。
資料流：proxy 進、worker 歸併、ClickHouse 查
依照 repo 的說明，社群版的分工大致是四層。第一層是 apps/proxy，負責 OTLP intake，本地預設監聽 4101。第二層是 apps/api，提供 HTTP API，預設 4100。第三層是 apps/worker，跑背景任務與 incident grouping，README 用 agent orchestration 描述它的角色。第四層是儲存：Postgres 放 schema 與遷移，ClickHouse 承載 telemetry 查詢。
這個切分值得注意的地方在於，歸併邏輯不在接收端，而在 worker。也就是說，訊號進來之後會先落地，再由背景程序分批處理成群組。好處是接收路徑保持輕量，不會因為歸併演算法變慢而拖垮 ingest；代價是 incident 的出現會有延遲，而且 worker 的健康狀態直接決定你看到的事件是否即時。自架時這是一個要單獨監控的元件。
packages/fingerprint 的存在暗示歸併是靠指紋比對，而不是靠模型判斷。README 沒有說明指紋的計算方式，也沒有提供視窗大小或相似度門檻的設定範例，這部分在文件上是薄的。如果你需要調整歸併的靈敏度，得直接讀 packages/fingerprint 的原始碼，這對評估期的團隊是一道門檻。
Agent runner 則是另一個介面層。README 說明了 agent runner interfaces for pluggable investigation runtimes，並附帶一個預設的 community runner，行為是 records a local incident summary。換句話說，開源版附的是一個記錄器，不是調查器。真正會去追根因、跑指令、改設定的能力，落在可插拔的介面之後，由你自己或第三方實作。
啟動一輪本地堆疊的實際指令
前置條件寫得很明確：Node.js 20+、pnpm 9+、Docker。三個都要，缺一不可，因為資料庫與 ClickHouse 是走容器。
安裝依賴：
pnpm install
拉起本地堆疊並跑遷移：
pnpm install docker compose up -d pnpm --filter @superlog/db db:migrate pnpm dev
啟動後預設的三個入口是 Web 在 http://localhost:5173、API 在 http://localhost:4100、OTLP intake 在 http://localhost:4101。要把服務的 telemetry 送進來，OTLP exporter 的 endpoint 指向 4101。
repo 另外提供型別檢查指令 pnpm typecheck，以及一個 monorepo 的 filter 用法範例 pnpm --filter @superlog/db db:migrate，可以看出這是一個 pnpm workspace，套件以 @superlog/ 為命名空間。
README 給的安裝路徑還有一條，是透過 coding agent 的 skills：
Run npx skills add superloglabs/skills --all and use the skills to install Superlog in this project
這條路徑依賴另一個 repo superloglabs/skills，以及你使用的 coding agent 是否支援 skills 機制。它是一層便利包裝，底層仍然是上面那幾個指令。若你要在 CI 或正式環境重現部署，直接用 docker compose 與 pnpm 指令會比走 skills 可控。
預設 runner 只寫摘要，不是自動修復
專案描述用的是 self-heal 這個詞，但把 README 讀完會發現，開源版實際附帶的 community agent runner 只做一件事：記錄一份本機的 incident 摘要。它不會去重啟服務、回滾部署或改動設定。真正能執行調查動作的 runtime，是透過 agent runner 介面外掛進來的。
這個落差不是缺陷，而是授權與產品切分的結果。開源核心給你的是 ingest、歸併、儲存與查詢的完整鏈路，加上一個可擴充的掛載點；調查與處置的實作留給使用者或生態系。評估時應該把它當成一個觀測工作區來看待，而不是一個會自己動手的維運機器人。
另一個限制來自資料層。ClickHouse 負責 telemetry 查詢，這代表你除了 Postgres 之外還要維運一個 ClickHouse 實例。對已經有 ClickHouse 的團隊這是順水推舟，對只有 Postgres 的小團隊則是一項額外的維運負擔，包含磁碟用量、壓縮與備份策略。README 沒有提供保留期限或取樣相關的設定鍵，這部分得從 schema 與實際部署中自行確認。
還有一個更基本的邊界：這個 repo 沒有任何 release 資訊可查。README 也沒有提供版本相容性矩陣或升級指南。在這種情況下，追 main 分支的風險要由採用者自己承擔，特別是在 schema 遷移會動到 Postgres 的情況下。
與 Grafana 加 Alertmanager 這條路線的差異
最直接的替代方案是既有的開源組合：用 OpenTelemetry Collector 收訊號，送進 Prometheus 或 Loki，再用 Grafana 看圖、Alertmanager 發告警。這條路線成熟、元件多、社群大，幾乎所有雲端環境都有現成的託管選項。
差別在於聚合的單位。Alertmanager 的 group_by 是把告警分組，分組的依據是你事先寫好的標籤規則；事件本身仍然是從規則觸發出來的。Superlog 走的是另一條路：它先接收原始 telemetry，由 worker 依指紋把訊號歸成 incident，事件是資料驅動產生的，不依賴你先定義好每一條告警規則。對於規則寫不完、訊號種類又一直增加的系統，這個方向省下的是規則維護的人力。
代價是控制權的轉移。用 Alertmanager，你可以精確知道哪條規則在什麼閾值觸發；用指紋歸併，你得接受演算法幫你決定什麼算同一件事，而目前文件沒有揭露可調參數。反過來說，Alertmanager 不會幫你把 traces 和 logs 一起拉進同一個事件檢視，Superlog 的 Web 介面正是為此而存在。
兩者不是互斥的。把 OTLP 同時送給 Collector 與 Superlog 的 4101 埠在技術上可行，只是重複儲存的成本要自己算。
維護成本與授權的實際含義
自架 Superlog 社群版要養的元件包括：Node.js 執行環境、pnpm workspace 的建置流程、Postgres、ClickHouse、以及四個應用程式（web、api、proxy、worker）。其中 worker 是背景程序，故障時不會有使用者直接回報，需要獨立的健康檢查。
升級成本取決於兩件事：Postgres 的 schema 遷移，以及 ClickHouse 的資料表結構變更。README 只給了 pnpm --filter @superlog/db db:migrate 這一個指令，沒有提到回滾方式或遷移的破壞性。在沒有 release 紀錄可對照的情況下，升級前先在副本上跑一次遷移是合理的做法。
授權是 Apache License 2.0，檔案在 repo 根目錄的 LICENSE.md。這個授權允許商業使用、修改與再散布，並附帶專利授權條款，同時要求保留著作權聲明與變更說明。它不要求你開源自己的衍生作品，這與 copyleft 授權不同。README 沒有提到商標使用政策，所以把 Superlog 的名字用在你自己的託管服務上是否可行，不在這份文件能回答的範圍內。具體條款與你組織的合规要求，應該由法務確認。
專案有 Y Combinator P26 的標記，以及 Discord 與 X 帳號作為支援管道。這些是背景資訊，不構成對專案成熟度的判斷。
誰該先試，誰該再等
已經在用 OpenTelemetry、手上有一批吵雜訊號、而且願意自己維運 Postgres 加 ClickHouse 的團隊，是這個專案最合適的第一批使用者。他們能用 docker compose up -d 與 pnpm dev 在幾十分鐘內看到完整的 ingest 到 incident 鏈路，再決定要不要把 agent runner 介面接上自己的調查流程。
不合適的情況也很清楚。如果你的團隊沒有人能維護 ClickHouse，或者你需要的是值班排班、升級通知與跨團隊的告警路由，這個 repo 沒有提供這些元件。如果你期待的是開箱即用的自動修復，預設的 community runner 只寫摘要，會讓你失望。
動手之前，先確認三件事：packages/fingerprint 的歸併邏輯是否符合你對事件粒度的期待，agent runner 介面的邊界在哪裡、你能不能在其中執行實際的處置動作，以及 Postgres schema 的遷移路徑在版本之間是否安全。這三項都能在原始碼裡查到答案，不需要等官方文件補齊。
編輯結論
如果你已經在用 OpenTelemetry，而且想要一個能自己跑起來、能把訊號歸成 incident 的工作區，Superlog 社群版值得先在本機試一輪：pnpm install、docker compose up -d、pnpm --filter @superlog/db db:migrate、pnpm dev 四步就能看到 Web 與 API。若你需要的是成熟的告警路由、值班排班與長期儲存治理，這個 repo 目前沒有提供對應元件，預設 community agent runner 也只寫入本機 incident 摘要，不是自動修復。採用前先確認三件事：ClickHouse 與 Postgres 的實際儲存成本、agent runner 介面能否接上你自己的調查流程、以及 Apache-2.0 對你內部再散布的影響。
社群筆記