inferwatch

ローカルで提供されるLLM（Ollama と vLLM）のリアルタイムおよび履歴メトリクス。ブラウザダッシュボード、設定画面、そしてエージェントが同じデータを照会できるMCPサーバーを備えています。

1つのPythonプロセス、1つのSQLiteファイル。DockerもNodeもPrometheusも外部サービスも不要です。リクエストパスには一切関与しないため、推論を遅くしたり壊したりすることはありません。

┌── Ollama ──────────────┐        ┌── vLLM ────────────────┐
│ journald / file /      │        │ GET /metrics           │
│ docker logs            │        │ (native Prometheus)    │
└──────────┬─────────────┘        └──────────┬─────────────┘
           │ per-request rows                │ pre-aggregated
           ▼                                 ▼
        ┌──────────────── SQLite (WAL) ────────────────┐
        │  requests · rollups · vllm_samples/hist      │
        └───────┬──────────────────────────┬───────────┘
                ▼                          ▼
         dashboard :7070            MCP server (stdio)

2つのエンジンは対称ではなく、このツールはそれを偽らない

これが中心的な設計上の事実なので、明確に述べる価値があります。

両方のタブでGPU使用率、VRAM、温度、消費電力を表示します。これらはどちらのエンジンでもなくnvidia-smiによって測定されるためです。温度と消費電力は軸を共有せずに別々のチャートになり、それぞれの単位に応じて集約されます。使用率はカード全体で平均、VRAMとワットは合計、温度は最も高温のカードを報告します。温度はゼロからプロットされない唯一の系列です。0から始まる33〜68°Cの範囲では、プロットの大部分が無駄になります。

したがって、これらは別々のダッシュボードタブ、別々のテーブル、別々のMCPツールを取得します。カウンターの差分によってvLLMのリクエストごとの行を再構築する試みは行われません。どのTTFTがどのリクエストに属していたかを復元することはできず、偽造すると実際の行の隣に発明された行が置かれることになります。

Ollama: 数値の出所

Ollamaは/metricsエンドポイントを公開していません（確認済み — このルートはバイナリに存在しません）。OLLAMA_DEBUG=1を使用すると、組み込みのllama.cppがリクエストごとにタイミングブロックを出力し、それがアクセス行とスケジューラー行と結合されます。

slot print_timing: id 0 | task 6763 | prompt eval time = 1254.52 ms /  55 tokens
slot print_timing: id 0 | task 6763 |        eval time = 14591.31 ms / 416 tokens
[GIN] ... | 200 | 16.862061865s | 192.0.2.10 | POST "/v1/chat/completions"
time=... msg="context for request finished" runner.name=.../llama3.2:3b

これにより、TTFT、プリフィル/デコード分割、トークン数、デコードレート、ステータス、クライアント、エンドポイント、モデルが、すべてのクライアントからのすべてのリクエストについて、リクエストパスに触れることなく得られます。どちらのソースにも単独では存在しない2つの数値が、この組み合わせから得られます。

• キュー待ち時間 = ウォールレイテンシ − ランナー時間: 生成ではなく待機に費やされた時間。プロキシはこれらを分離できません。

• プロンプトキャッシュ再利用 = 完全なプロンプト長 − 実際に評価されたトークン数。

OLLAMA_DEBUG=1 が必要です。 これがないと、llama.cppはタイミング行を出力しません。リクエストレート、ステータス、GPUメトリクスは引き続き機能しますが、TTFTとトークン数は空のままです。ダッシュボードはゼロを表示する代わりに、バナーでその旨を通知します。

# /etc/systemd/system/ollama.service.d/override.conf
[Service]
Environment="OLLAMA_DEBUG=1"

vLLM: 数値の出所

vLLMのネイティブPrometheusエンドポイントは、collection.scrape_interval_s（デフォルト10秒）ごとにスクレイピングされます。累積カウンターは差分され、ヒストグラムバケットはバケットごとに差分され、両方とも1分ごとに集約されて書き込まれます。すべてのスクレイピングを保存すると、どのチャートも使用しない解像度で月に数百万行が追加されるためです。

知っておく価値のある3つの詳細:

• vLLM独自のバケット境界はカウントとともに保存されます。 その境界は1ms/20ms/250ms/2.5s/40s/640sのステップです。Ollamaのステップは25ms/200ms/1.5s/15s/60sです。どちらも他方の改良版ではないため、一方を他方に再バケット化するには境界間の補間、つまり数値の発明が必要になります。パーセンタイルは各ソースの独自の境界に対して計算され、バケット上限値として報告されます。

• _sum と _count は正確であるため、平均は正確です。vLLMのバケットは秒単位の範囲では粗いため、ダッシュボードとMCPツールは平均を先頭に表示し、パーセンタイルを「最大」とラベル付けします。

• 再起動は process_start_time_seconds によって（そしてカウンターが逆方向に進むことによって）検出されます。再起動にまたがる間隔は、偽のデルタとして出力されるのではなく、破棄されます。

トークン間レイテンシは、vLLMのリリースによってtime_per_output_token_seconds、inter_token_latency_seconds、request_time_per_output_token_secondsと綴られてきました。すべてが収集され、データがある方が使用されるため、これは古いサーバーと新しいサーバーの両方で設定なしで機能します。

Related MCP server: System Monitor MCP Server

インストール

Python 3.10以降が必要です。これはこのコード（3.9でクリーン）のためではなく、fastapi、uvicorn、starlette、mcpがすべてそれを必要とするためです。

pip install git+https://github.com/floatsmyboat/inferwatch     # or:
git clone https://github.com/floatsmyboat/inferwatch && cd inferwatch
python3 -m venv --upgrade-deps .venv && .venv/bin/pip install -e ".[dev]"

インストールすると、2つのコマンドが得られます:

まだPyPIにはありません。今のところgitからインストールしてください。

既に持っているジャーナルからバックフィルし、データベースを確認します:

inferwatch ingest --since 2d      # or: python -m inferwatch.main ingest
inferwatch stats

実行します:

inferwatch serve                  # http://127.0.0.1:7070

サービスとして — ユニットは現在のユーザー、チェックアウトパス、インタープリター用にsystemd/inferwatch.service.inからレンダリングされるため、ハードコードされたものはありません:

./scripts/install-systemd.sh          # system service (uses sudo)
sudo systemctl enable --now inferwatch

./scripts/install-systemd.sh --user   # or per-user, no sudo
systemctl --user enable --now inferwatch

HOST=0.0.0.0 PORT=7070 DATADIR=... ./scripts/install-systemd.shでオーバーライドします。

ネットワーク上での公開

認証はありません。 ダッシュボードは読み取り専用（GETのみ）で、プロンプトや応答テキストは保存されません。カウント、タイミング、モデル名、クライアントアドレスのみです。ファイアウォールで制限してください:

sudo ufw allow from 192.168.1.0/24 to any port 7070 proto tcp comment "inferwatch"

監視対象の設定

すべてダッシュボードの設定タブ、またはCLIから編集できます:

python -m inferwatch.main sources                       # list
python -m inferwatch.main sources add --kind vllm --name qwen \
    --set url=http://127.0.0.1:8000
python -m inferwatch.main sources add --kind ollama --name box \
    --set reader=file --set path=~/.ollama/logs/server.log
python -m inferwatch.main sources disable qwen

Ollamaログリーダー。 誰もがsystemdでOllamaを実行しているわけではありません:

fileリーダーはtail -Fのように追従し、ローテーション（inode変更）と切り詰めを生き延び、オフセットを永続化するため、再起動しても再生されません。OllamaのGo行にはtime=が含まれますが、トークン数を保持するllama.cppのslot行にはタイムスタンプが含まれないため、最後に見られたものが繰り越されます。結合が依存する順序は常に保持されます。絶対的な精度はjournaldよりも低く、秒解像度の[GIN]行は時間が逆方向に進むように見えないように前方にクランプされます。

設定の優先順位

spec default  <  database (Settings tab)  <  environment  <  command line

環境またはフラグによって提供されたキーは、その発信元とともに設定タブに読み取り専用で表示されます。プロセスはそれを使用するように指示されており、ブラウザがそれを静かにオーバーライドしてはならないためです。保存は全か無かであるため、1つのフィールドのタイプミスで半分適用された構成が残ることはありません。ソース、間隔、保持期間の変更は再起動なしで適用されます。server.hostとserver.portは再起動が必要としてマークされ、APIは保存後にその旨を通知します。

設定リファレンス

以下のすべての設定は、設定タブで編集可能で、環境変数として設定可能であり、一部はフラグで固定できます。テーブルはコードから生成されるため（scripts/gen-config-docs.py）、プログラムが実際に受け入れるものから逸脱することはありません。

scripts/gen-config-docs.pyによって生成 — 手動で編集しないでください。

収集

保持

ダッシュボード

サーバー

ソースフィールド

--set key=value を sources add で指定するか、設定タブで指定する。

Ollama (--kind ollama)

vLLM (--kind vllm)

コマンドラインフラグ

設定を固定するフラグは、環境変数や設定タブよりも優先される。設定タブでは、そのキーは読み取り専用で表示され、由来が示される。

スコープ: Ollamaソース1つ、vLLMソースは複数

vLLMの行はソースごとにキー付けされるため、vLLMインスタンスはいくつでも並行して監視できる。Ollamaのテーブル（requests、events、ps_samples）はソースで分割されないため、Ollamaソースは同時に1つだけ実行される。2つ目を有効にすると、2つのインスタンスの数値を暗黙的に1つの集合に混ぜるのではなく、警告をログに記録して無視する。テーブルの分割はスキーマ変更を伴うため、意図的に行う価値がある。

ダッシュボード

http://127.0.0.1:7070 — 3つのタブ: Ollama、vLLM、設定。

どのGPUがどのエンジンに属するか

1つのホストで複数のエンジンが動作することはよくあるため、インスタンスのペインにすべてのカードをプロットすると、そのインスタンスがすべてのカードを使用しているかのように見えてしまう。各vLLMインスタンスのGPUは、プロセスの追跡によって解決される — サービスが待ち受けるポート → リッスンしているpid → その子プロセス → nvidia-smi のコンピュートプロセスとの交差 → それらのプロセスが使用するカード。インスタンスのカードには系列の色が付けられ、そのVRAMタイルはそのカードのみをカウントする。ホストの他のカードはグレーで表示され、「other engine」とラベル付けされる。

属性の特定には ss、ローカルインスタンス、およびnvidia-smiのプロセス可視性（コンテナ内ではしばしば欠落）が必要。そのいずれかが欠けている場合、ペインはその旨を表示し、推測する代わりに強調なしですべてのカードを表示する。

1つのフィルタ行がその下のすべてをスコープする。各チャートにはテーブルトグルがあり、同じ系列を数値として表示するため、ホバーだけでしか値を確認できないということはない。ライブSSEフィードがリクエストティッカーと現在のレート表示を駆動する。

URLパラメータ: ?tab=vllm、?window=6h、?model=llama3.2:3b、?source=name、?nostream=1（ライブフィードを無効化 — キオスク表示やスクリーンショットツールで、開いたままのストリームを無期限に待つのを避けるのに便利）。

API

/api/sources/probe は定義を保存する前にチェックするため、タイポはチャートが沈黙するのではなく、そこで表面化する。

MCPサーバー

./scripts/install-mcp.sh      # writes .mcp.json for this checkout (gitignored)

または claude mcp add inferwatch -- /path/to/.venv/bin/python -m inferwatch.mcp_server。

同じSQLiteファイルを読み取り専用（mode=ro に加えて PRAGMA query_only）で開き、ダッシュボードと同じクエリレイヤーを通じて応答するため、報告される数値は常に画面上の数値と一致する。

保持期間

• 生のリクエストごとの行（Ollama）: 7日間 (retention.raw_days)。

• GPUサンプル、イベント、vLLM行: 30日間 (retention.sample_days)。

• rollup_1m と rollup_1h: 無期限に保持。

ロールアップは、事前計算されたパーセンタイルではなく、TTFTとレイテンシの固定バケットヒストグラムを格納する。ヒストグラムは加算できるため、任意の範囲に対するパーセンタイルは、バケットを合計して目標の順位まで歩くことで計算される。パーセンタイルのパーセンタイルは無意味になる。これはそうではない。

生のウィンドウ内のクエリは正確なパーセンタイルを返します。それを超えるとヒストグラムから算出され、それを含むバケットの上限として報告されます。すべてのレスポンスには exact: true|false が付与されます。

再起動とリブート

再開状態はソースごとに管理されます（journald カーソル、ファイルの inode+オフセット、または docker タイムスタンプ）が、SIGTERM でフラッシュされます。これを「単なる可能性」ではなく「安全」にする理由は2つあります。

書き込みは冪等です。 すべてのリクエスト行とイベント行には UNIQUE インデックスの下に dedupe_key が付与され、挿入は INSERT OR IGNORE です。すでに保存済みの行を再読み取りしても何も起きないため、ingest は繰り返し実行でき、再開が安全に重複することもありません。

使用できないカーソルは信頼されません。 カーソルが指すジャーナルがローテーションで消えていた場合、journalctl はカーソルに埋め込まれたタイムスタンプを使って静かに位置を再調整し、正しく再開します。しかし、未来のタイムスタンプが刻まれたカーソル（クロックスキュー、復元されたデータベース）は、journalctl が到着しないエントリを待ち続け、収集が静かに停止します。そのようなカーソルは起動時に拒否されます。フォロー試行が2回連続で何も返さなかった場合も同様です。

systemctl stop は1秒未満で完了します。systemd は Result=success とともに ExecMainStatus=15 を記録します。uvicorn はシャットダウン後に意図的にシグナルを再送出するため、SIGTERM による終了はクラッシュではなく想定内の動作です。

正直な制限事項

並列実行時の帰属（Ollama）。 llama.cpp のタイミング行のタスク ID とアクセス行のステータスは決して同時に現れないため、到着順で結合されます。処理中のリクエストが1つの場合は正確です。2つがアクセス行の出力前に完了した場合、ログにはそれらを区別する情報がなく、推測ではなく attribution='ambiguous' として保存されます。値は exact、ambiguous、none（ランナーに到達する前に失敗 — モデルも推測されません）、orphan（アクセス行のないタイミング）です。開発ホストでの2日間のバックフィルでは、OLLAMA_NUM_PARALLEL=1 の下で exact 174件、ambiguous 9件、orphan 4件でした。並行リクエストが多いほど ambiguous の割合が高くなると予想されます。

vLLM のトークンカウンタとリクエストカウンタはリクエスト単位で整合していません。 generation_tokens_total はトークンがストリーミングされるにつれて進み、request_success_total はリクエストが完了したときだけ進みます。したがって、短いウィンドウではこれらは重複するが異なるリクエストの集合を表しており、一方を他方で割ってもリクエストあたりのトークン数にはなりません。API はこれを counters_aligned: false で示し、ダッシュボードも vLLM タブでその旨を表示します。

vLLM のリクエスト単位の情報はありません。 上記で説明済みです。vLLM からリクエスト単位の詳細が必要な場合、リクエストレベルのログが唯一の情報源ですが、そこにはプロンプトテキストが記録されます — このツールは意図的にそれを保存しません。

ログは供給源であり、アーカイブではありません。 ジャーナルは journald.conf によっては1〜2日分しか保持しない場合があります。SQLite ファイルが履歴の保管庫です。ログが inferwatch の実行より速くローテーションした場合、そのギャップは回復できません。

同じマイクロ秒内のバイト単位で同一の2つのイベントは1つにまとめられます。 イベントの dedupe キーはその値から構築されるため、同一の警告がマイクロ秒以内に2回記録されても行は1つだけ残ります。これは保証された冪等性のための意図的なトレードオフです — 繰り返された警告を落とすことは、履歴を重複させることより優れています。

ヘルスチェックトラフィックは分離され、カウントされません。 HEAD / と GET /api/ps は開発ホストでのリクエストの96%を占めていました。これらは class='health' として保存され、dashboard.include_health がオンの場合を除き推論レートから除外されます。requests_all には常に含まれます。

ログ形式とメトリクス名に依存します。 Ollama のタイミング行はデバッグ出力であり、契約ではありません。また vLLM はリリース間でメトリクス名を変更します。tests/test_parse.py には逐語的なフィクスチャ行が、tests/test_vllm.py には実際の /metrics 抜粋が保持されています。アップグレードでパースが壊れた場合、それらのテストが失敗し、何が変わったかを示します。

テスト

python -m unittest discover -s tests -t .

CI は Python 3.10 から 3.14 で実行され、さらにホイールをビルドし、ダッシュボードの HTML がその中に含まれていることを検証し、空のディレクトリからクリーンな環境にインストールしてソースツリーがパッケージングのミスを隠せないようにするパッケージングジョブも実行します。ネットワーク、GPU、エンジンは不要です。パーサーフィクスチャは実際のログ行と実際の /metrics 抜粋を逐語的に使用します。カバレッジには、コリレータの結合とその ambiguous/orphan/failed ケース、ヒストグラムのパーセンタイルとロールアップの冪等性、スキーママイグレーション、シグナルセーフなコミット、カーソル検証、ファイルのローテーションと切り詰め、タイムスタンプの単調性、カウンタリセット検出、設定の優先順位とロックが含まれます。このファイル内の設定リファレンスはスペックから生成され、逸脱した場合はテストが失敗します。ダッシュボードの JavaScript は純 Python パーサーで構文チェックされ、そのフォーマッタは実際の JS エンジンで実行されます（どちらもオプション — Node は不要です）。

.venv/bin/python scripts/gen-config-docs.py --check   # docs match the code?

レイアウト

inferwatch/parse.py        ollama log line parsers (pure, fixture-tested)
inferwatch/readers.py      journald / file / docker log readers
inferwatch/collect.py      correlator, GPU + model pollers, maintainer
inferwatch/vllm.py         Prometheus scraper, delta and reset handling
inferwatch/gpuproc.py      maps GPUs to the process tree holding them
inferwatch/vllm_metrics.py vLLM query layer
inferwatch/metrics.py      ollama query layer (shared by API and MCP)
inferwatch/store.py        SQLite schema, rollups, histograms, retention
inferwatch/config.py       typed settings spec, precedence, source validation
inferwatch/supervisor.py   builds and rebuilds collectors from the sources table
inferwatch/api.py          FastAPI endpoints + SSE
inferwatch/web/index.html  dashboard (single file, no CDN, no build step)
inferwatch/mcp_server.py   MCP server (read-only)
inferwatch/main.py         serve / ingest / stats / sources

コントリビューション

Issue とプルリクエストを歓迎します。変更を受け入れやすくする2つのポイント:

• python -m unittest discover -s tests -t . が通ること。

• inferwatch/config.py に触れた場合は、python scripts/gen-config-docs.py を実行して README の設定リファレンスがコードと一致するようにすること — テストで強制されます。

パーサーの変更には、既存のテストと同様に、実際のエンジン出力から逐語的にコピーしたフィクスチャ行を添付してください。ログ形式とメトリクス名は契約ではなく、実際のフィクスチャがあれば将来の破損が明確になります。

ライセンス

Apache License 2.0 — LICENSE と NOTICE を参照してください。