superlog を導入する前に確認したい、OTLP 取り込みとエージェント実行の境界

superlog が埋めようとしている穴は、収集ではなく仕分けにある

OpenTelemetry を導入したチームが次に困るのは、シグナルが来ないことではなく、来すぎることだ。traces、logs、metrics が同じ障害を別々の表現で何度も報告し、人間がそれを突き合わせる作業に時間が溶ける。superlog はこの仕分けを自動化の対象としており、README では「ingests traces, logs, and metrics, groups noisy signals into incidents」と説明されている。対象読者は、すでに OTLP でテレメトリを送れる状態にあり、その先の一次切り分けを仕組みに寄せたい開発チームである。監視製品をこれから選定する段階のチームというより、計装は終わっていて、その上に載る処理を自前でコントロールしたい層を想定していると読める。

リポジトリの分割が示す処理の流れ

構成は apps と packages に分かれ、役割がディレクトリ名でほぼ説明されている。apps/proxy が OTLP intake proxy として外部からのテレメトリを受け、apps/api が HTTP API、apps/worker が「background workers and agent orchestration」を担う。保存側は packages/db の Drizzle スキーマとマイグレーションで、README は Postgres schema と ClickHouse-backed telemetry queries という二段構えを明記している。つまり、メタデータやインシデントの状態は Postgres、量の多いテレメトリ本体のクエリは ClickHouse という分担だ。packages/fingerprint はテレメトリのフィンガープリンティング用ヘルパーで、ノイズを同一のインシデントにまとめる処理はここに関係する。フロントは apps/web の Vite/React である。データの流れとしては、proxy で受ける、fingerprint で同一性を判定する、worker がまとめてインシデント化する、web と api がそれを表示する、という順序が想定されている。

起動は 4 コマンドで、ポートは 3 つに固定されている

前提は Node.js 20 以上、pnpm 9 以上、Docker である。README の Quick Start では 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 と明記されている。既存のアプリケーションから superlog にテレメトリを送る場合、向き先は 4101 になる。型検査は pnpm typecheck で走る。設定キーについての詳細な説明は README には含まれておらず、環境変数の一覧や ClickHouse の接続先などはリポジトリ内の設定ファイルを確認する必要がある。ここは導入時に最初に読むべき場所が README の外にある、という点を覚えておきたい。

community エージェントランナーは何をしないのか

このリポジトリの目玉として README に挙がるのが「Agent runner interfaces for pluggable investigation runtimes」と「A default community agent runner that records a local incident summary」である。注意して読みたいのは後者の動詞で、records a local incident summary とある。つまり既定のランナーは調査結果の要約をローカルに記録するものであり、コードを書き換えて障害を修復する処理が既定で動くとは書かれていない。自動修復を期待して導入すると、最初に触る部分で期待が外れる。実際の調査ロジックを載せるには、用意されたインターフェースに自前のランタイムを実装して差し込む前提になる。ここは設計上のトレードオフで、拡張点を開けておく代わりに、既定の体験は控えめに留めている。リポジトリ名の「self-heal」という表現と、コミュニティ版で実際に動く範囲には隔たりがある。

ClickHouse を前提にした保存構成の重さ

Postgres と ClickHouse の併用は、テレメトリの量に対しては妥当だが、ローカル開発環境の再現性という観点では負担になる。docker compose up -d で両方が立ち上がるとしても、本番相当の構成を自前で運用するなら、バックアップ、スキーマ変更、ClickHouse 側のリソース配分まで利用側の責任範囲に入る。packages/db に Drizzle のマイグレーションがあるため、スキーマ変更の追従は pnpm --filter @superlog/db db:migrate の再実行で行う形になるが、ClickHouse 側の変更が同じ経路で管理されているかは README からは判断できない。観測対象のサービスが小規模で、テレメトリ量が Postgres だけで扱える範囲に収まるなら、この二層構成は過剰である。

代替としての Grafana LGTM スタックとの違い

同じ OTLP を取り込むセルフホスト構成として Grafana の LGTM スタック（Loki、Grafana、Tempo、Mimir）がある。決定的な違いは、集約と調査の扱いだ。LGTM はテレメトリを保存して可視化し、アラートを発火させるところまでで、その後の切り分けは人間がダッシュボード上で行う。superlog はその切り分け自体をインシデントという単位に畳み、エージェントに渡す入口を用意する。逆に言えば、LGTM は各コンポーネントが独立して成熟しており、保存とクエリの挙動を予測しやすい。superlog を選ぶ理由は可視化の品質ではなく、fingerprint による集約とエージェント実行の拡張点に価値を見出せるかどうかにかかっている。ダッシュボードを主目的にするなら、superlog を選ぶ意味は薄い。

Apache-2.0 とオープンコアの線引き

ライセンスは Apache License 2.0 で、これは自由に利用、改変、再配布できる許容型である。ただし README はこのリポジトリが「fully open-source, free community edition」であり、別に hosted Superlog Cloud edition が存在すると明記している。つまり、ここで公開されているのはコミュニティ版の範囲であり、ホスト版の機能が同じ条件で提供されるとは書かれていない。オープンコアの境界がどこに引かれているかは README からは特定できず、エージェント実行の高度な部分がどちらに属するかは不明である。ライセンス自体は採用の障壁にならないが、将来のアップグレード経路を考えるなら、コミュニティ版とホスト版の機能差をリポジトリとサイトの両方で確認しておきたい。法的な判断が必要な場合は専門家に相談すべきで、ここでは条件の所在を示すに留める。

採用を決める前に確かめる 3 点

第一に、community エージェントランナーが実際に生成するインシデント要約の形式と保存先を、apps/worker のコードで確認する。README の記述だけでは出力の粒度が分からない。第二に、Agent runner interfaces の実装にどれだけのコードが必要かを評価する。ここが薄ければ自前ランタイムの実装コストが上がる。第三に、ClickHouse を含む運用を自チームで回せるかを判断する。pnpm typecheck と pnpm --filter @superlog/db db:migrate が通ることは出発点にすぎず、テレメトリ量が増えたときのクエリ性能は ClickHouse の設計に依存する。これら 3 点を確認せずに導入すると、self-heal という語から期待する挙動と、コミュニティ版で実際に得られる挙動の差に後から気づくことになる。

編集部の結論

すでに OpenTelemetry で計装済みで、取り込んだテレメトリを Postgres と ClickHouse に自前で置きたいチームに向く。逆に、エージェントによる自動修復の完成度を今すぐ求める場合や、マネージドの SaaS で運用負荷をゼロにしたい場合は、このコミュニティ版は答えにならない。導入前に確認すべきは、community エージェントランナーが実際に何を出力するか、そして Agent runner interfaces に自前のランタイムを差し込む前提で動かせるかどうかである。

公式情報源

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. superloglabs/superlog on GitHub