litestar-logging

ロギング

実行ワークフロー

1. まずロギングバックエンドを選択します。stdlib logging、picologging、Structlog、またはカスタム設定サブクラスから選びます。
2. アプリのセットアップ時に logging_config または Structlog プラグインを使って、一度だけロギングを設定します。
3. 具体的な理由がない限り、Litestar のノンブロッキング queue_listener ハンドラーを使用します。
4. 例外をログに記録するタイミングと、抑制するスタックトレースを決定します。
5. リクエストロガーとアプリロガーの使い方を標準化し、フィールド、レベル、マスキングルールに一貫性を持たせます。
6. 機密データを漏らすことなく、ログから適切な対応ができることを検証します。

基本ルール

• ロギング設定はアプリの構築時に一元管理します。
• 非同期アプリケーションでは、組み込みのノンブロッキング queue_listener ハンドラーを優先します。
• 例外ロギングの方針は明示的に決定します。Litestar はデバッグモード以外では、デフォルトで例外をログに記録しません。
• トレースが大量に出力されないよう、対象となる例外の型やステータスコードには disable_stack_trace を使用します。
• シークレット、認証情報、機密性の高いリクエストデータをログに含めないようにします。
• ミドルウェア、例外ハンドラー、ビジネスロジックで同じ内容を重複してログに記録しないようにします。
• ロギングはメトリクスやトレーシングと分けて扱います。

選択ガイド

• 標準ロギングまたは picologging ベースの構成には LoggingConfig を使用します。
• picologging をバックエンドとして使用する場合は、logging_module="picologging" を指定します。
• Structlog による構造化ロギングがプロジェクトの標準である場合は、StructlogPlugin を使用します。
• 本番環境のインシデントで、デバッグモード以外でも例外ログが必要な場合は、log_exceptions="always" を使用します。
• 404 やドメインレベルの検証エラーなど、よく発生する想定内のエラーには disable_stack_trace を使用します。
• 組み込み設定では必要な動作を表現できない場合に限り、BaseLoggingConfig をサブクラス化します。

参考ファイル

必要なセクションだけを読んでください。

• stdlib logging、picologging、ロガーへのアクセス、カスタム設定のサブクラス化については、references/configuration-patterns.md を読んでください。
• 例外ロギング、スタックトレースの抑制、Structlog、マスキングに関するガイダンスについては、references/exception-and-structlog-patterns.md を読んでください。

推奨されるデフォルト設定

• ルートレベル、ハンドラーの選択、フォーマッターの形式を明示します。
• リクエスト単位のログには request.logger を使用し、アプリレベルのイベントには共有のアプリロガーを1つ使用します。
• Litestar が自動でログを記録すると考えず、意図的に例外をログに記録します。
• 想定内で発生頻度の高い障害に限って、トレースを抑制します。
• 検索しやすいように、メッセージのフィールドとキー名を一定に保ちます。

アンチパターン

• queue_listener で十分な場合に、非同期リクエストの処理経路でブロッキングするログハンドラーを使うこと。
• シークレット、トークン、または機密性の高いペイロードをそのままログに記録すること。
• 新たなコンテキストを加えずに、複数のレイヤーで同じ障害をログに記録すること。
• 運用担当者がすでに把握している、発生頻度の高い想定内の障害に対してスタックトレースを有効にすること。
• 組み込みの選択肢を検討し尽くす前に、ロギング設定をサブクラス化すること。

検証チェックリスト

• ロギングが一度だけ設定されていることを確認します。
• リクエストロガーとアプリロガーが意図したレベルで出力することを確認します。
• log_exceptions と disable_stack_trace がインシデント対応方針に合っていることを確認します。
• シークレットや機密性の高いリクエストフィールドが出力されない、またはマスキングされていることを確認します。
• キューを使用するハンドラー、または同等のノンブロッキング動作が導入されていることを確認します。
• 構造化ロギングの出力が、後続のログ取り込み要件を満たしていることを確認します。

スキル間の連携

• 定量的な可観測性やスクレイピング／エクスポートに関する事項には、litestar-metrics を使用します。
• ロギング動作とは別に、クライアント向けのエラー仕様を定める場合は、litestar-exception-handling を使用します。
• インシデントに基づくトラブルシューティングのワークフローには、litestar-debugging を使用します。
• ロギング方針がシークレット、認証コンテキスト、またはマスキング要件に関わる場合は、litestar-security を使用します。

Litestar の参考資料

• https://docs.litestar.dev/latest/usage/logging.html