Superlogをセルフホストする方法と必要リソース

Superlog のセルフホストで実際にインストールされるもの

Superlog をセルフホストするには、リポジトリを clone し、Docker Compose で Postgres、ClickHouse、OpenTelemetry collector を起動します。次にデータベースの migration を 1 回実行し、ソースから 4 つの Node サービスを起動します。アプリケーションは OTLP（OpenTelemetry protocol）の trace、log、metric を intake port に送信します。Superlog はこれらに fingerprint を付け、繰り返し発生するものを 1 つの incident にまとめます。その後、agent が triage の初回案を作成します。インストールには半日かかります。開始前に確認すべきなのは、必要なリソースと、現実的な制約です。

Superlog は Apache 2.0 ライセンスで提供され、github.com/superloglabs/superlog にあります。2026 年 8 月時点で、star は約 1.2k、main の commit はおよそ 460 件です。ただし、release tag は 1 つもありません。この点がインストール方法に影響します。git checkout v1.0.0 には checkout できるものがないため、自分で commit を固定するか、clone した時点で main に存在した内容をそのまま実行することになります。

Uptime Kuma と Langfuse では得られない Superlog の回答

セルフホスト型の監視ツールは、外から見ると同じように見えます。しかし実際は異なり、適切でないツールを使うと、メリットがないままサーバーのリソースを消費します。

• Uptime Kuma は外部からエンドポイントを監視します。答えるのは「稼働しているか」という 1 つの質問です。
• Zabbix は Ubuntu 24.04 上のホストとサービスを監視します。CPU、メモリ、ディスク、サービスの状態を、設定したしきい値と照合します。
• Langfuse は LLM の呼び出しをトレースします。各呼び出しのプロンプト、モデル、トークン数、レイテンシ、コストを記録します。
• Superlog は、通常のサービスがすでに出力しているテレメトリを取り込み、繰り返し発生する失敗をインシデントに変換します。

Superlog が扱う質問は異なります。「何かが壊れた。何が壊れ、なぜ壊れたのか」です。LLM の呼び出し自体には関与せず、外部から監視することもありません。通常のアプリケーションコードから OTLP を取り込み、トリアージの工程にエージェントを配置します。これは、オンコール担当者が最初に手作業で行う切り分けを支援するものです。

VPS の予算に関係する重要な違いは、ストレージです。Uptime Kuma は、数千件のチェック結果を保存するだけなので、1 GB の RAM でも問題なく動作します。一方、Superlog はカラム型ストアを使用します。テレメトリは 1 回書き込まれ、その後、数百万行を対象に時間範囲で検索されるためです。これが ClickHouse の用途であり、Postgres では適しません。Postgres も構成には残り、プロジェクト、ユーザー、インシデント、取り込みキーなどの小規模なリレーショナルデータを保持します。

docker compose up -d で実際に起動するもの

3 つのコンテナが起動しますが、Superlog は含まれません。1 つのコマンドでインストールが完了すると考えていると、この点に驚くことがあります。

• postgres:16。ホストの 5434 番ポートに公開されます
• clickhouse/clickhouse-server:26.1。HTTP は 8123 番ポート、ネイティブプロトコルは 9000 番ポートを使用します
• otel/opentelemetry-collector-contrib:0.150.1。gRPC は 4317 番ポート、HTTP over OTLP は 4318 番ポートを使用します

Superlog のアプリケーションはホスト上でソースから実行され、pnpm dev によって起動されます。2026 年 8 月時点では、リポジトリに本番用の compose ファイルはありません。そのため、長期運用するには、各アプリの start スクリプトを実行する独自の systemd unit、またはツリー内に用意されたアプリごとの Dockerfile が必要です。

span がたどる経路を頭に入れておいてください。以下で説明する各障害は、その経路上のいずれか 1 つの中継点で発生します。アプリは OTLP を Superlog の取り込みプロキシに送信します。プロキシは ingest key でリクエストを認証し、project id を付与してから collector に転送します。collector はクライアントが設定しようとした superlog.* 属性を削除し、プロキシから提供されたヘッダーの値に基づいて superlog.project_id を追加し、データをバッチ処理して ClickHouse に書き込みます。Web アプリと API は ClickHouse からテレメトリを読み取り、それ以外のデータは Postgres から読み取ります。

この属性削除は、単なる表示上の処理ではなく、実際のマルチテナンシー制御です。これがなければ、有効な ingest key を 1 つ持っているだけで、誰でも superlog.project_id を自分で設定し、別のプロジェクトのデータに書き込めてしまいます。

VPS の規模はどの程度必要ですか？

低い取り込み量で単一ノード構成をインストールする場合は、4 vCPU、8 GB の RAM、40 GB の SSD を計画してください。これは測定値ではなく、計画上の最低ラインです。まずこのサイズから始め、自身のトラフィックに対して十分か確認してください。

メモリは主に 4 か所で使用されます。ClickHouse は RAM が十分にあるマシン向けに設計されており、デフォルト値もそれを前提としています。この構成では、Postgres 16 の使用量は控えめです。テレメトリではなくメタデータを保持するためです。collector の使用量も控えめです。一方、4 つの Node プロセスはそうではありません。Vite の開発サーバーと 3 つの tsx watch プロセスは、それぞれ数百 MB を使用します。そのため、2 GB のマシンで pnpm dev を実行すると負荷が高くなります。

ディスクは見落としやすい問題です。この monorepo で pnpm install を実行すると、1 つも span を取り込む前に AWS SDK、ClickHouse クライアント、OpenTelemetry SDK、React ツールチェーンが取得されます。その後、ClickHouse はトラフィックに応じて増加します。次の 2 つを測定してください。

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"

少量のトラフィックで、数個のサービスが毎分数百 span を送信する程度なら、マシンの負荷は低く、ClickHouse もほとんどの時間アイドル状態です。問題になるのはバーストです。たとえば、問題のあるデプロイによって、同一のエラーが毎分数千件発生する場合です。フィンガープリント処理により、閲覧者にはそれらが 1 件のインシデントとしてまとめられますが、ClickHouse は内部で各行を書き込みます。

保持期間は自分で設定します。collector の ClickHouse exporter はテーブル、otel_traces、otel_logs、およびメトリクス種別ごとのテーブルを 1 つずつ作成します。保持期間を設定するのは、infra/collector/config.yaml の設定で time to live を指定した場合だけです。データは自動的には期限切れにならないため、対策を計画しなければ、トラフィックの多い 1 か月でディスクが一杯になります。

コミットを固定してインストールする

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

git tag -l は、2026 年 8 月時点では何も出力しないのが想定される結果です。テストしたコミットを選び、そのコミットを使い続けてください。

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

次に、ツールチェーンを確認します。

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

package.json は、engines.node を >=20.0.0 として宣言し、packageManager を pnpm@9.12.0 として宣言しています。古い Node でインストールを実行すると、pnpm は ERR_PNPM_UNSUPPORTED_ENGINE で停止し、必要なバージョンを示します。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 postgres

ClickHouse は Ok. を返し、pg_isready は accepting connections を返します。8123 への接続が拒否される場合、コンテナの起動中か、停止した可能性があります。docker compose logs clickhouse でどちらかを確認でき、docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled は、カーネルがメモリ不足でプロセスを強制終了した場合に true を報告します。これは、設定ではなくサーバーのリソース不足を示します。

次に、マイグレーションとアプリケーションを起動します。

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

ポートに注意してください。5432 ではなく 5434 です。compose ファイルは、ホストに既にインストールされている Postgres と競合しないよう、Postgres を 5434 で公開します。アプリの .env.example ファイルも DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog と一致しています。Postgres が既に動作しているサーバーでマイグレーションの接続先を 5432 にすると、接続拒否になるか、さらに悪い場合は誤ったデータベースにマイグレーションが適用されます。

pnpm dev は、リポジトリの Procfile に記載された 4 つのプロセス（api、web、worker、proxy）を起動します。各プロセスは出力を tmp/logs/ にも書き込むため、ingest の監視先は tail -f tmp/logs/proxy.log です。README では、Web アプリを http://localhost:5173、API を http://localhost:4100、OTLP intake を http://localhost:4101 で公開しています。

接続先を指定する前に、実際にどのポートで待ち受けているかを確認してください。

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

これは後で重要になります。proxy は PORT 環境変数から自身のポートを読み取り、PORT が未設定の場合は 4000 にフォールバックします。開発用スタックでは、この変数が設定されます。一方、自分で作成した systemd unit では設定されません。そのため、4000 で待ち受けている proxy に対して exporter を 4101 に接続しようとすると、接続拒否になり、他の手掛かりも得られません。

1 件のトレースを送信し、1 件のエラーを発生させ、1 件のインシデントを確認する

Web アプリでプロジェクトを作成し、その ingest key をコピーします。受け付け側はすべてのリクエストをこのキーで認証するため、キーなしで送信されたテレメトリは ClickHouse に到達しません。

標準の環境変数を使用して、任意の OpenTelemetry SDK を受け付け側に向けます。

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'

受け付け側は x-api-key ヘッダーからキーを読み取ります。exporter の設定上都合がよければ、authorization: bearer YOUR_INGEST_KEY も使用できます。標準の OTLP パスである /v1/traces、/v1/logs、/v1/metrics に加えて、/health も提供します。

注意すべき落とし穴があります。OTEL_EXPORTER_OTLP_ENDPOINT はベース URL であり、SDK はこれにシグナルのパスを追加します。OTEL_EXPORTER_OTLP_TRACES_ENDPOINT などのシグナル固有の変数は、パスを追加せず、記述した値をそのまま使用します。シグナル固有の変数を http://127.0.0.1:4101 に設定すると、すべての export が / に POST されます。これはルートではないため、何も到達しません。SDK は export の失敗をログに記録しますが、アプリケーション自体は正常に見えます。

Node サービスでは、コードを変更しない構成だけでパイプラインを検証できます。

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 アプリが空の場合は、プロジェクトが一致していません。ingest key がどのプロジェクトに属しているかを確認します。プロキシログに記録があるのに件数が増えない場合は、collector または ClickHouse への書き込みに問題があります。docker compose logs collector を確認してください。プロキシログに記録がまったくない場合、exporter は受け付け側に到達していません。ポート、パス、または拒否されたキーを確認します。

Web アプリでは、これらの繰り返し発生する失敗は、リクエストごとに 1 行としてではなく、1 件のインシデントとして表示されます。Superlog は受信したシグナルのフィンガープリントを作成し、一致するものをグループ化します。そのため、同一エラー 4,000 件で埋まった受信トレイではなく、1 件のページとして扱えます。エージェントは、そのグループに対して調査結果を記録します。

調査の処理ではモデルを呼び出すため、worker にモデルプロバイダーを設定する必要があります。変数名は外部の解説記事ではなく、固定した commit の各アプリディレクトリ内にある .env.example ファイルから取得してください。これらの変数名は main に伴って変わるためです。GitHub と Sentry の統合も同様です。各統合には docs/github-app-setup.md と docs/sentry-app-setup.md に独自の設定ドキュメントがあり、webhook payload は docs/webhooks.md に記載されています。

受信経路を非公開にし、agent は読み取り専用にする

Docker はデフォルトでコンテナのポートを 0.0.0.0 に公開します。公開ポートは ufw を迂回します。Docker が独自のルールを DOCKER-USER chain に書き込み、ufw がパケットを確認する前に評価されるためです。パブリック IP を持つ VPS では、出荷時の compose file により ClickHouse HTTP は 8123、Postgres は 5434 で公開され、インターネットから到達可能になります。この file の認証情報は開発用のデフォルト値です。ClickHouse の user は default で password は空です。Postgres では postgres が user と password の両方に設定されています。

これらを loopback に bind します。compose file で公開する各ポートの host 側は環境変数から取得されるため、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

信頼する前に結果を確認し、その後でコンテナを再作成します。

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 は決して表示されないはずです。ports を再定義する compose override file でこの問題を修正しようとしてはいけません。Compose は複数の file 間で port list を置き換えずに連結するため、両方の bind が残り、公開側も開いたままになるからです。

ingest にも同じ注意が必要です。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 のままにしてください。GitHub App には read scope を付与し、レビューする pull request の作成だけを許可します。telemetry を読み取り、patch を作成する agent は有用です。サービスを再起動できる agent は、別のレベルのリスクになります。これはデフォルトで継承するのではなく、意図的に決定すべき権限です。コストにも同じ注意が必要です。調査のたびに model call が発生するため、ノイズの多い production system に向ける前に VPS で agent にかける費用を予算化する とともに、agent が実際に行った操作を記録する ようにしてください。これにより、予期しない pull request にも監査証跡が残ります。

発生する障害と、その原因を示す文字列

• ERR_PNPM_UNSUPPORTED_ENGINE が pnpm install の実行中に発生する場合、Node が 20 より古いことを意味します。node -v で 1 行で確認できます。
• 移行中に ECONNREFUSED 127.0.0.1:5434 が発生する場合、compose スタックが起動していないか、DATABASE_URL で誤ったポートを指定しています。
• ClickHouse がループして再起動する場合、通常はメモリが原因です。docker compose logs clickhouse を読み、コンテナで OOMKilled が true になっていないか確認します。
• Web アプリケーションが空のままなのに exporter が成功を報告する場合、データが 4318 の collector に直接送られた可能性があります。この経路では、プロキシが付与するプロジェクト情報が付かないためです。
• 本番環境へのインストールで 4101 が connection refused になる場合、プロキシが PORT=4000 にフォールバックしています。unit ファイルで PORT を明示的に設定します。
• docker compose ps に 0.0.0.0:8123 と表示される場合、loopback バインドが有効になっていません。docker compose config を実行し、解決されたポートを確認します。

Flawless、HyperProbe、そして Superlog の位置付け

この分野はまだ新しく、エージェントが操作できる範囲によってツールの設計が分かれています。Flawless は Kubernetes を対象とするオープンソースの AI SRE（サイト信頼性エンジニアリング）ツールです。既存の Prometheus、Loki、Grafana のスタックからデータを読み取り、パイプライン自体は管理しません。HyperProbe は反対の方式を取ります。2026 年 8 月時点ではクローズドソースのホステッド製品で、実行中のプロセス内に読み取り専用のプローブを配置し、変数の状態を取得します。そして、その状態を MCP（model context protocol）経由でアシスタントに公開します。

Superlog はこの 2 つの中間に位置します。OTLP の取り込みから ClickHouse への保存まで、パイプライン全体を管理します。一方で、エージェントを修正の段階ではなく、トリアージの段階に配置します。この設計だからこそ、Superlog のセルフホスティングは、単に放置できるコンテナを配置する作業ではなく、インフラストラクチャ上の判断になります。Superlog を運用すると、カラムストアも運用することになります。自分で管理する他のデータベースと同じように、適切な保守が必要です。

FAQ

自己ホスト型 Superlog にはどの程度の RAM が必要ですか？

取り込み量が少ない単一ノードでは、RAM 8 GB、4 vCPU、ディスク 40 GB を確保してください。この構成は Postgres、ClickHouse、OpenTelemetry collector、4 つの Node プロセスで構成され、ClickHouse には余裕が必要です。1 GB または 2 GB の VPS では不十分です。pnpm install だけでも負荷が大きく、負荷がかかると ClickHouse はカーネルの OOM killer によって強制終了されます。公開されている数値（この数値を含む）をそのまま信頼せず、docker stats --no-stream と free -m で実際の環境の数値を測定してください。

OTLP exporter はどのポートに向ければよいですか？

README で http://localhost:4101 に設定されている Superlog intake proxy に向けてください。これは /v1/traces、/v1/logs、/v1/metrics を提供し、x-api-key ヘッダーまたは authorization: bearer ヘッダーから取得したプロジェクトの ingest key で認証します。ポート 4318 は下層の OpenTelemetry collector です。そこへ直接送信すると、データに project id を付与する proxy を経由しません。PORT が未設定の場合、proxy はポート 4000 にフォールバックします。そのため、4101 だと決めつける前に ss -lntp を実行し、実際にどのポートで待ち受けているか確認してください。

Superlog は Uptime Kuma または Zabbix の代わりになりますか？

いいえ。Uptime Kuma はネットワーク外部からエンドポイントが応答するかを確認し、Zabbix は設定したしきい値に対してホストとサービスのメトリクスを監視します。Superlog はアプリケーションが出力するトレース、ログ、メトリクスを取り込み、繰り返し発生する障害をインシデントとしてまとめます。外部の uptime probe も併用してください。別の場所で動作する probe なら、テレメトリパイプラインを保持するホスト自体が停止した場合でも報告できるためです。

Superlog agent は本番システムを変更できますか？

付与した権限の範囲でのみ変更できます。agent の出力は調査結果と変更案であり、人間が確認します。最初は GitHub App を read scope に限定し、pull request を使用してください。worker が保持する資格情報も、読み取り専用の範囲に限定してください。本番環境への write access は、意図的に別途判断する事項として扱う必要があります。サービスを再起動できる agent は、テレメトリを読み取り、レビュー用のパッチを書くだけの agent よりも、はるかに大きな権限委任となるためです。

commit を固定すべきですか、それとも main を追跡すべきですか？

commit を固定してください。2026 年 8 月時点でリポジトリに release tag はないため、main が唯一の変動対象であり、週に数回 commit が追加されます。テストした SHA を記録し、その SHA をデプロイしてください。更新する前に diff を確認してください。git log --oneline <old-sha>..main がレビュー対象であり、更新後に新たに必要となった変数を確認する最初の場所は、アプリごとの .env.example ファイルです。