オブザーバビリティ
Libre WebUI は、運用担当者向けに 2 つのオブザーバビリティ経路を提供します。
- ローカルの標準出力と標準エラーへ書き込む、構造化アプリケーションログ。
- HTTP リクエスト、永続ジョブ、カウンター、警告／エラーのログレコードを対象とする、任意の OpenTelemetry エクスポーター。
どちらの経路からも、Libre WebUI プロジェクトへテレメトリーが送信されることはありません。運用担当者がコレクターのエンドポイントを設定するまで、OpenTelemetry はオフです。管理者向けのシステムと使用状況ページは別の仕組みです。OpenTelemetry コレクターではなく、デプロイ自体から診断情報とモデル／プロバイダーの使用状況を読み取ります。
構造化ログ
デフォルトの LOG_FORMAT=text では、従来のスコープ付きコンソール出力が維持されます。LOG_FORMAT=json を設定すると、1 行につき 1 つの JSON オブジェクトが出力されます。
LOG_LEVEL=info
LOG_FORMAT=json
構造化された各行には、次の情報が含まれます。
- ISO タイムスタンプ。
- レベルとロガーのスコープ。
- メッセージ。
- 現在のリクエストまたは永続ジョブの相関 ID（存在する場合）。
- 呼び出し元が提供した、サイズ制限付きの構造化詳細。
すべての HTTP リクエストに X-Request-Id が割り当てられます。Libre が受け入れる受信 ID は、英字、数字、.、_、- で構成された 8～64 文字のものだけです。それ以外の場合は UUID を作成します。ID は応答で返され、ログコンテキストを通じて非同期処理にも引き継がれます。アクセスログには HTTP メソッド、パス、ステータス、所要時間を記録します。クエリパラメーターにはユーザーコンテンツや短時間だけ有効な資格情報が含まれる可能性があるため、クエリ文字列は削除されます。
LOG_LEVEL には silent、error、warn、info、debug を指定できます。デバッグログは、より多くの運用情報を露出する可能性があります。問題を診断するときだけ有効にし、生成されたログを他のデプロイデータと同じように保護してください。
秘匿化の境界
構造化された詳細とエクスポートするテレメトリーには、同じサイズ制限付きの秘匿化ヘルパーが適用されます。
- フィールド名がパスワード、シークレット、トークン、鍵、認証情報、Cookie、資格情報、Bearer 値、JWT に似ている場合は省略。
- 文字列は 512 文字まで。
- 配列、ネストの深さ、エクスポートする属性数には上限を適用。
- エラーオブジェクトでは、任意のオブジェクトグラフではなく、名前とサイズ制限付きのメッセージだけを保持。
これは多層防御であり、プロンプトやシークレットをログへ書き込む許可ではありません。シークレットらしいフィールド名を持たない短いユーザー入力文字列も、通常のログテキストとして現れる可能性があります。アプリケーション拡張では、リクエスト本文、プロンプト、ドキュメント本文、ツール結果、プロバイダーのペイロードではなく、識別子と処理結果をログに記録してください。ログへのアクセスを制限し、運用担当者が管理する保持ポリシーを適用してください。
OpenTelemetry を有効にする
Libre は OpenTelemetry SDK への依存関係を追加せず、OTLP/HTTP JSON を直接エクスポートします。標準のシグナルパスを受け付けるコレクターの HTTP ベース URL を指定します。
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
エクスポーターは、ベース URL に /v1/traces、/v1/metrics、/v1/logs を付加します。OTEL_EXPORTER_OTLP_HEADERS は、カンマ区切りの key=value ペアです。コレクターの資格情報はデプロイ用シークレットとして保存し、コミットしないでください。OTEL_SERVICE_NAME のデフォルトは libre-webui です。
エンドポイント変数がない場合、スパン、メトリクス、ログの記録は何もしない処理になり、プロセス外へ何も送信しません。チーム向けデプロイでは、アプリケーションプロセスと外部ワーカープロセスがそれぞれ独立してエクスポートします。各プロセスに、使用すべきコレクター設定を指定してください。ロールごとに異なるサービス名を使うと、ダッシュボードが読みやすくなります。
エクスポートされるシグナル
| シグナル | Libre が記録する内容 |
|---|---|
| HTTP サーバースパン | クエリ文字列を除いたメソッドとパス、応答ステータス、所要時間、成功／失敗ステータス、リクエスト ID |
| HTTP カウンター | メソッドと応答ステータスクラス別の単調増加リクエスト数 |
| 永続ジョブスパン | ジョブ種別、試行回数、所要時間、成功／失敗ステータス |
| 永続ジョブカウンター | ジョブ種別と結果別の単調増加実行回数 |
| ログレコード | 秘匿化した警告／エラーメッセージ、ロガースコープ、リクエスト／ジョブ相関 ID |
スパンは、ローカルで完了したスパンです。現在の Libre は、受信した OpenTelemetry のトレース親を伝播せず、サービス間に親子スパンツリーを作成せず、ブラウザのレンダリングやすべてのプロバイダー呼び出しを計装しません。モデルのトークンとメディアの使用状況は、代わりにローカルの使用状況分析とコストガバナンスの台帳へ記録されます。
配信動作
テレメトリーは、意図的にベストエフォートで扱われます。
- バッファには最大 2,048 件のスパンと 2,048 件のログレコードを保持し、負荷が高い場合は最も古い項目を破棄。
- 保持するカウンター系列は最大 512。
- エクスポーターは約 5 秒ごとにフラッシュ。
- 各 HTTP エクスポートのタイムアウトは 3 秒。
- コレクターエラーが発生したバッチは破棄し、アプリケーションリクエストや永続ジョブをブロックしたり失敗させたりしない。
したがって、エクスポーターは監査ログでも永続的な会計システムでもありません。セキュリティイベントには追記専用のセキュリティ監査ログ、コストには SQL 使用状況台帳、テレメトリーにはコレクター側の保持とアラートを使用してください。
トラブルシューティング
テレメトリーが届かない。 対象のアプリケーションまたはワーカープロセスの環境に OTEL_EXPORTER_OTLP_ENDPOINT が存在し、値がコレクターのベース URL だけであること、コレクターが 3 つの標準パスで OTLP/HTTP JSON を受け付けることを確認してください。
コレクターから未認証の応答が返る。 カンマ区切りのヘッダー構文と、コレクターが authorization=Bearer ... または別のヘッダーを求めているかを確認します。環境変数を変更した後は、プロセスを再起動してください。
コレクターの停止中もリクエストが成功する。 これは正常です。アプリケーションの可用性を保つため、エクスポート経路は失敗しても処理を継続し、失敗したバッチを再試行用に永続化しません。
ログフィールドがない、または短縮されている。 シークレットらしいキーは削除され、長い値や深くネストされた値には意図的に上限が適用されます。秘匿化の境界を弱めるのではなく、安全な識別子や要約を記録してください。