loglens

loglens

loglens は、ローカルファイルに保存されたホームラボのログを調査します。ストアに何が保存されているか、直近で何が届いたか、何がエラーになったか、特定の用語を含むもの、時間経過に伴うボリュームの分布、ある時点の前後に何があったかを確認できます。1 つのバイナリで、コマンドラインインターフェースと、単一のアクションディスパッチ型ツール cortex を公開する stdio MCP サーバーの両方を提供します。

これは、ラベル付きのコアサブセットです。モデルにしたツールはカタログ内の 60 個のアクションをディスパッチしますが、loglens が実装しているのはそのうちの 7 個、つまり status、tail、errors、search、timeline、context、help です。残りの 53 個（フリートとトポロジーの表示、AI セッション分析、相関分析と異常分析、エラーの確認、通知、管理機能）は実装していません。help アクションは、実行時に実装済みのサブセットと未実装のアクションを一覧表示します。

ログファイル

レコードは JSONL ファイルに格納されます。各行は 1 つの JSON オブジェクトで、ts（ISO-8601 タイムスタンプ）、level、source、message を含みます。

{"ts":"2026-10-26T09:15:00.000Z","level":"info","source":"docker/web","message":"container started"}
{"ts":"2026-10-26T09:16:12.000Z","level":"error","source":"syslog","message":"disk almost full"}

パスは、CLI の --file、環境変数 LOGLENS_LOG_FILE、./loglens.jsonl の順に使用されます。不正な行（不正な JSON、フィールドの欠落、解析できないタイムスタンプ）はスキップして数に記録されますが、致命的なエラーにはなりません。ファイルが見つからない場合、データアクションでは明確なエラーになります。一方、status は exists: false としてストアの状態を報告し、help はストアを必要としません。すべての処理はローカルで決定論的に行われ、ネットワークには一切アクセスしません。

インストール

npx @reneturcios/loglens status

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/loglens

コンテナーはデフォルトで MCP サーバーを起動します（下記を参照）。CLI として使用するには、CLI 引数を渡してください。ログファイルをマウントし、LOGLENS_LOG_FILE にコンテナー内のパスを設定します。

CLI

export LOGLENS_LOG_FILE=/var/log/homelab.jsonl

loglens status
loglens tail --limit 5 --source docker/web
loglens errors --limit 10
loglens search "disk" --since 2026-10-26T00:00:00.000Z
loglens timeline --bucket day
loglens context 2026-10-26T09:16:12.000Z --window-minutes 5
loglens context 12 --limit 3
loglens help

loglens --version

コマンドは JSON の結果を出力します。tail、errors、search はレコードを新しい順に返し、context はファイル内の順序で返します。context は、タイムスタンプ（--window-minutes の範囲内にあるレコード、または最も近いレコードの前後にある --limit 件のレコード）か、単独のレコードインデックス（その位置の前後にある --limit 件のレコード）のどちらかを受け取ります。終了コードは、成功時が 0、操作の失敗時（ログファイルが見つからない場合を含む）が 1、使用方法のエラー時が 2 です。

MCP サーバー

1 つのバイナリで両方の機能を提供します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/loglens mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "loglens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/loglens", "mcp"],
      "env": { "LOGLENS_LOG_FILE": "/absolute/path/to/logs.jsonl" }
    }
  }
}

ツール

ツール	入力	返される内容
cortex	action（必須。status、tail、errors、search、timeline、context、help のいずれか）、および任意の query、source、level、limit、since、until、bucket（hour または day）、timestamp、window_minutes	アクションに応じて、ストアの概要、条件に一致する最新のレコード、時間別または日別のボリュームバケット、ある時点の前後のレコード、またはサブセットのヘルプテキストを返します。

最初の呼び出しには {"action":"status"} が便利です。その後、tail、errors、search、timeline、context で絞り込みます。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, real temp JSONL files, no network
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。