SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor ・更新日 2026-11-06

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

SuperlogはOTLPのtraces、logs、metricsをincidentにまとめ、agentがトリアージします。Docker Compose構成、4つのNodeサービス、導入に半日かかる実態と必要リソースを確認できます。

Superlog のセルフホスティングで実際に導入されるもの

Superlog をセルフホスティングするには、リポジトリを clone し、Docker Compose で Postgres、ClickHouse、OpenTelemetry collector を起動します。次に、データベースの migration を 1 回実行し、ソースから 4 つの Node サービスを起動します。アプリケーションは OTLP (OpenTelemetry protocol) の traces、logs、metrics を intake port に送信します。Superlog はそれらに fingerprint を付け、繰り返し発生するものを 1 つの incident にまとめます。デフォルトの community agent runner は、ローカルに incident summary を記録します。インストールには半日かかります。開始前に確認しておくべきなのは、必要なリソースと、実際の制限です。

Superlog は Apache 2.0 ライセンスで提供され、github.com/superloglabs/superlog にあります。2026 年 10 月 13 日時点で、stars は約 1.5k、main 上の commits はおよそ 490 件です。release tags は 1 つもありません。clone した時点で main に存在していた内容をそのまま実行するのではなく、自分で commit を固定してください。

Uptime Kuma と Langfuse では答えられない、Superlog が答えること

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

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

VPS の予算に関係する重要な違いは、ストレージです。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 経由の OTLP は 4318 で待ち受けます

Superlog のアプリケーションはホスト上でソースから実行され、pnpm dev によって起動します。2026 年 10 月 13 日時点で、リポジトリには本番用の compose ファイルがありません。そのため、長期運用するには独自の systemd unit を用意するか、ツリー内にあるアプリごとの Dockerfile を使います。api、worker、proxy の各アプリには、unit から呼び出す start スクリプトがあります。web アプリにはありません。これは Vite アプリなので、build スクリプトでビルドし、出力を nginx または Caddy から静的ファイルとして配信します。または preview スクリプトを実行します。このスクリプトは vite preview です。

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

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

VPS はどの程度のスペックが必要ですか?

取り込み量が少ない単一ノード構成では、4 vCPU、8 GB の RAM、40 GB の SSD を計画上の基準にします。これは実測値ではなく、計画時の下限です。まずはこのサイズから始め、自分のトラフィックに照らして確認してください。

メモリは主に 4 つの用途で使用します。ClickHouse は RAM に余裕のあるマシン向けに設計されており、デフォルト値もそれを前提としています。Postgres 16 はテレメトリではなくメタデータを保持するため、この構成では使用量は控えめです。collector も同様です。4 つの Node プロセスには Vite 開発サーバーと 3 つの tsx watch プロセスが含まれます。実際のメモリ使用量は自分の環境で測定してください。

より見落としやすいのがディスクです。この 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"

負荷の原因になるのはバーストです。1 回の不適切なデプロイによって、1 分間に数千件の同一エラーが発生することがあります。フィンガープリント処理により、利用者からは 1 件のインシデントとしてまとめて表示されますが、ClickHouse はその下で各行を引き続き書き込みます。

保持期間は自分で設定します。collector の ClickHouse exporter はテーブル、otel_traces、otel_logs、およびメトリクス種別ごとのテーブルを作成します。保持期間が適用されるのは、infra/collector/config.yaml の設定で TTL を指定した場合だけです。自動的に期限切れになるデータはないため、計画しなければ、トラフィックの多い 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 年 10 月 13 日時点では何も出力しないのが想定される結果です。テストしたコミットを選び、そのコミットを使い続けます。

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 バージョンでも、インストールが自動的に停止するとは限りません。engine の強制適用は設定に依存し、pnpm 9.12.0 では engineStrict が無効な場合に警告経路が使用されます。Ubuntu 24.04 のアーカイブに含まれる nodejs パッケージは 20 より古いため、Node 20 以降を NodeSource または nvm からインストールします。リポジトリには .nvmrc が含まれているため、nvm を使用している場合は nvm use により意図したバージョンが選択されます。

pnpm install
docker compose up -d
docker compose ps

up -d が準備完了を示すとは限らないため、ヘルスチェックが完了するまで待ちます。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 は turbo run dev を実行します。これにより、Turborepo を介して各アプリの dev スクリプトが起動します。api、web、worker、proxy が対象となり、出力は 1 つのターミナルに混在します。リポジトリの Procfile には同じ 4 つのプロセスが記載され、それぞれの出力が tmp/logs/ に tee されます。tail -f tmp/logs/proxy.log を ingest の監視先にしたい場合は、pnpm dev の代わりに overmind や foreman などの Procfile runner で起動します。README では、web アプリを 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 と記載されています(いずれも 2026 年 10 月 13 日に確認)。ss に表示されたポートを使用します。以下の例では 4101 を使用しているため、実際に待ち受けているのが 4000 なら置き換えてください。自分で作成した systemd unit では、PORT を記述しない限り何も設定されません。そのため、4000 で待ち受ける proxy に対して 4101 を指定した exporter は接続拒否になり、他に手掛かりとなる情報も得られません。

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

Web アプリでプロジェクトを作成し、その ingest key をコピーします。intake はすべてのリクエストをこの key で認証するため、key なしで送信したテレメトリが 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 も使用できます。標準の OTLP パスである /v1/traces、/v1/logs、/v1/metrics の 3 つと、/health を提供します。

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

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 が intake に到達していません。ポート、パス、または拒否された key を確認します。

Web アプリでは、繰り返し発生した失敗はリクエストごとに 1 行ずつ表示されず、1 件のインシデントとしてまとめられます。Superlog は受信したシグナルの fingerprint を作成し、一致するものをグループ化します。これにより、同じエラー 4,000 件で埋まった受信トレイではなく、1 件のページとして確認できます。デフォルトの community agent runner は、そのグループについてローカルのインシデント概要を記録します。

モデルを使用した調査には、モデルプロバイダーと互換性のある agent runner の設定が必要です。デフォルトの community runner はローカルの概要を記録します。これらの変数名は外部の解説ではなく、固定した 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 はコンテナの通信を nat テーブルでルーティングします。そのため、公開ポート宛てのパケットは、ufw のルールがある INPUT および OUTPUT チェーンに到達する前に転送され、ufw は制御できません。パブリック IP を持つ VPS では、提供された compose file により ClickHouse HTTP が 8123、Postgres が 5434 で公開され、インターネットから到達可能になります。この file の認証情報は開発用のデフォルト値です。ClickHouse の user は default で password は空です。Postgres では postgres が user と password の両方に設定されています。

これらを loopback にバインドします。compose file の公開ポートはすべて、環境変数からホスト側のアドレスを取得します。そのため、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 は表示されないことを確認します。Compose の override file で ports を再定義するだけでは、ホストの IP が異なる場合も両方のバインドが残ります。Compose 2.24.4 以降では、ports: !override を使用してリストを置き換えられます。

取り込み口にも同じ注意が必要です。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 が調査して修正案を提示することを売りにしています。重要なのは「提示する」という点です。実際のインシデントをいくつか監視して動作を確認するまでは、本番環境に対して read only のままにします。read-only GitHub App では、修正用 branch の push や pull request の作成はできません。そのワークフローには、setup guide で Contents と Pull requests の write permission が必要です。コメントには Issues の write permission も必要です。telemetry を読み取り、patch を作成する agent は有用です。一方、service を再起動できる agent は、別のレベルのリスクを伴います。これはデフォルトで継承するのではなく、意図的に決定すべき事項です。model-backed runner を設定するときは、コストにも同じように注意を払います。ノイズの多い本番システムに向ける前に、VPS での agent の利用費を予算化することが重要です。また、予期しない pull request に監査証跡を残せるよう、agent が実際に実行した内容を記録することも重要です。

発生する障害と、それを示すメッセージ

  • ERR_PNPM_UNSUPPORTED_ENGINE が pnpm install 中に発生する場合、エンジンの要件に互換性がありません。pnpm 9.12.0 は Node と pnpm の要件を確認します。エラーに表示された要求バージョンと現在のバージョンを読み取り、node -v と pnpm -v を確認してください。
  • 移行中に ECONNREFUSED 127.0.0.1:5434 が発生する場合、compose スタックが起動していないか、DATABASE_URL に誤ったポートが指定されています。
  • docker compose logs clickhouse で ClickHouse の再起動を確認し、次にコンテナで OOMKilled が true になっているか確認してください。
  • Web アプリケーションが空のままなのに exporter が成功を報告する場合、通常はデータが 4318 の collector に直接送られています。この経路では、プロキシが付与するプロジェクト情報が付かないため、プロジェクトに記録されません。
  • 4101 への接続が拒否される場合、通常はプロキシが 4000 で待ち受けています。これはコードのフォールバック先であり、.env.example が設定するポートでもあります。unit ファイルまたはアプリケーションの .env で、PORT を明示的に設定してください。
  • docker compose ps に 0.0.0.0:8123 と表示される場合、loopback バインドが有効になっていません。docker compose config を実行し、解決されたポートを確認してください。

Flawless、HyperProbe、およびSuperlogの位置付け

このカテゴリはまだ新しく、エージェントが操作できる範囲によってツールの方向性が分かれています。Flawlessリポジトリでは現在、PolyForm Noncommercialライセンスの下で、Kubernetesおよびクラウドインフラストラクチャ向けのAI SRE(サイト信頼性エンジニアリング)プラットフォームであるCISREを提供しています。HyperProbeは実行中のプロセス内にプローブを配置し、変数の状態を取得して、その状態をMCP(model context protocol)経由でアシスタントに公開します。また、Docker Composeとライセンスキーを使用したセルフホスティングについても説明しています。

Superlogはこの2つの中間に位置します。OTLPの受信からClickHouseへの保存まで、パイプライン全体を管理します。また、エージェントを修正の段階ではなく、トリアージの段階に配置します。この設計により、Superlogのセルフホスティングは、放置できるコンテナの導入ではなく、インフラストラクチャ上の判断になります。Superlogを実行すると、カラムストアも運用することになります。これは、管理する他のデータベースと同じように保守する必要があります。

FAQ

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

取り込み量が少ない単一ノードでは、RAM 8 GB、4 vCPU、ディスク 40 GB を見込んでください。構成には Postgres、ClickHouse、OpenTelemetry collector、4 つの Node プロセスが含まれ、ClickHouse には余裕が必要です。公開されている数値も、この数値もそのまま信頼せず、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 です。そこへ直接送信すると、データにプロジェクト ID を付与するプロキシを経由しません。PORT が未設定の場合、プロキシはポート 4000 にフォールバックします。また、.env.example も 4000 を設定するため、4101 だと決めつける前に ss -lntp を実行し、実際にどのポートに bind したかを確認してください。

Superlog は Uptime Kuma や Zabbix の代わりになりますか?

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

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

付与した権限の範囲内でのみ変更できます。既定の community runner はローカルのインシデント概要を記録します。その他の調査ランタイムの動作は、設定した runner に依存します。本番の認証情報は読み取り専用に限定してください。pull request の作成には、ブランチと pull request に対する GitHub の個別の write 権限が必要です。本番環境への write アクセスは、意図的に別途判断してください。サービスを再起動できる agent は、テレメトリを読み取り、レビュー用のパッチを書くだけの agent よりも、はるかに大きな権限委譲になるためです。

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

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

この記事は役に立ちましたか?