Rustのaxumでやってはいけないログ設計！運用を困難にするアンチパターンと正しい解決策

Rustのaxumは、非同期で型安全なWebアプリケーションを構築するための強力なフレームワークです。
しかし、その柔軟性ゆえに、ログ設計において致命的なアンチパターンに陥りやすいのも事実です。
特に、本番運用で「どのリクエストが失敗したのか」「どのトレースがどの処理に対応するのか」が追跡不能になった瞬間、そのシステムはすでに運用不可能なブラックボックスと化します。

多くの開発者が無意識に実装してしまうのが、tower_httpのTraceLayerに頼りすぎる手法です。
これは確かに手軽ですが、デフォルトのログ出力は構造化されておらず、エラーレベルも一律です。
たとえば、クライアントエラー（400系）とサーバーエラー（500系）が同じログレベルで出力されれば、アラート設定は無意味になり、障害検知が著しく遅延します。

さらに悪質なのは、ログ内に機密情報（ユーザーIDやメールアドレス、認証トークンの一部）を平文で出力してしまうケースです。
axumのextractorを使ってリクエストデータを簡単に取得できるため、ついデバッグ用にそのままログに含めてしまいがちですが、これはセキュリティインシデントの直結する重大な過失です。

では、どう設計すべきか。
解決策の核心は、構造化ログ（例えばtracingクレート）と、リクエスト単位の一意なトレースIDの付与にあります。
具体的には、以下の3つの原則を徹底します。

各リクエストの開始時にSpanを生成し、その中にトレースID、メソッド、パス、ステータスコードをフィールドとして保持する
エラーはカスタムエラー型で明確に区分し、tracing::error!とwarn!を状況に応じて使い分ける（クライアント起因はwarn、サーバー起因はerror）
機密情報は必ずマスキングまたはハッシュ化した上で、かつ開発環境でのみ詳細出力するフィーチャーフラグを導入する

下表に、アンチパターンと正しいアプローチの対比を示します。

観点	アンチパターン	正しい解決策
ログフォーマット	文字列連結による可変長メッセージ	JSONなどの構造化形式（`tracing-subscriber`の`json`層）
エラーレベル	全エラーを`error`で出力	ステータスコードやエラー種別に応じて`error`/`warn`/`info`を区分
トレース相関	個別のログエントリに相関IDなし	`Span`で一貫した`trace_id`を伝搬し、すべてのログに自動付与
機密データ	リクエストボディやヘッダーをそのまま出力	`Sensitive`ラッパー型で明示的にマスク、または出力自体を条件付きに

さらに、実装レベルでは、axum::middlewareを使って独自のログミドルウェアを実装することを推奨します。
これにより、リクエスト開始・終了・エラー発生の各フェーズで確実にトレースIDを記録し、かつ非同期タスク間でもコンテキストを継承できます。
tracingのinstrumentマクロをハンドラ関数に付与するだけで、自動的にスパン情報が付加される点も見逃せません。

最後に忘れてはならないのは、ログは「デバッグのため」ではなく「運用のための資産」 であるという視点です。
出力量が多すぎればストレージコストが膨らみ、少なすぎれば原因究明に多大な工数を要します。
適切なサンプリングレートや、重要度に応じた出力先の分離（例：エラーはCloudWatch Logs、デバッグ情報はローカルファイル）も、初期設計に組み込むべき重要な判断事項です。

あなたのaxumアプリケーションは、ログという名の「暗号」を出力していませんか。
今一度、出力される1行1行が、障害時の羅針盤として機能するかどうかを、冷静に評価してみてください。

はじめに：axumのログ設計が運用の成否を分ける理由
アンチパターン1：TraceLayerへの過度な依存が生む構造化されないログ
アンチパターン2：エラーレベルの乱用で障害検知が鈍る問題
アンチパターン3：ログへの機密情報混入が招くセキュリティリスク
アンチパターン4：トレースID不在で分散トレースが不可能な状態
正しい解決策1：tracingクレートと構造化ログの導入
正しい解決策2：エラー種別に応じたログレベルの適切な割り振り方
正しい解決策3：Sensitiveラッパーとマスキングで機密情報を保護する実装
正しい解決策4：独自ミドルウェアでトレースIDを自動伝搬させる仕組み
実践上の落とし穴：出力量とコストのトレードオフ
まとめ：運用し続けられるログ設計とは何か

はじめに：axumのログ設計が運用の成否を分ける理由

Webアプリケーションの運用において、ログは単なる「デバッグ出力」ではありません。
それはシステムの健康状態をリアルタイムに伝えるセンサーであり、障害発生時の唯一の頼りになる証拠です。
特に、Rustのaxumのような非同期で高性能なフレームワークを採用する場合、そのログ設計は従来の同期型フレームワークとは異なる次元の注意深さを要求されます。

なぜなら、axumはtowerエコシステムと密接に連携し、ミドルウェアスタックやレイヤー構造を持つため、ログの出力ポイントが分散しやすいからです。
加えて、非同期タスク間でコンテキストを引き継ぐには、単なるprintln!の置き換えでは不十分であり、スパンやトレースといった概念を設計の初期段階から組み込む必要があります。

ここで、多くの開発者が陥る誤謬は、「ログは後から追加すればよい」という楽観視です。
実際には、一度リリースされたシステムのログ出力箇所を事後的に網羅的に改修することは、コードベースの肥大化とテスト工数の観点から現実的ではありません。
特にaxumでは、ハンドラ関数、ミドルウェア、エラーハンドリング、さらにはデータベースアクセス層など、あらゆるレイヤーでログを取るべき機会が存在します。
これらを一貫性なく実装すれば、出力されるログは断片的で、あるイベントの前後関係を追跡することが絶望的になります。

また、ログ設計は運用コストにも直結します。
構造化されていないテキストログは、CloudWatch LogsやElasticsearchなどのログ集約システムでの検索効率を著しく損ないます。
たとえば、「特定のユーザーIDに関するリクエストだけを抽出したい」という単純なクエリに対しても、正規表現による力技が必要になり、結果として障害対応の平均時間（MTTR）が数倍に跳ね上がることは珍しくありません。

さらに見落とされがちなのが、ログの出力レベルと量のトレードオフです。
デバッグ情報を詳細に出力しすぎればストレージコストが膨らみ、逆に抑制しすぎれば障害時の切り分けに必要な情報が欠落します。
このバランスを誤ると、システムは「ログが多すぎて見る気がしない状態」か「ログが少なすぎて何もわからない状態」のどちらかに陥ります。
いずれも運用者にとっては悪夢以外の何物でもありません。

では、どうすれば「運用を支えるログ」をaxumで実現できるのか。
その答えは、設計段階での明確なポリシー策定と、tracingエコシステムの適切な活用に集約されます。
具体的には、ログの出力フォーマットをJSONなどの構造化形式に統一し、リクエストごとにユニークなトレースIDを付与し、エラーの深刻度に応じてログレベルを細分化し、機密情報を自動でマスクする仕組みを組み込みます。
これらの要素は、個別に実装するのではなく、一貫したミドルウェアとカスタムレイヤーとしてaxumのアプリケーションに組み込むことで、初めて持続可能な運用基盤となります。

本記事では、まず最初にやってはいけないアンチパターンを具体的に列挙し、その後に実践的な正しい解決策を段階的に解説します。
各アンチパターンは、筆者が実際のプロダクション環境で目撃した、あるいは自身が過去に犯した過ちに基づいています。
理論だけでなく、実コードレベルの落とし穴にも言及することで、あなたのaxumプロジェクトが運用フェーズで想定外の悲劇を迎えることを未然に防ぎます。

ログは、システムが発する「声」です。
その声が雑音か、それとも意味のあるメッセージかは、設計者であるあなたの手腕にかかっています。
では、具体的なアンチパターンから見ていきましょう。

アンチパターン1：TraceLayerへの過度な依存が生む構造化されないログ

axumを導入する際、多くの開発者が最初に手を伸ばすのがtower_httpクレートが提供するTraceLayerです。
このミドルウェアは、リクエストとレスポンスの基本情報を自動でログ出力してくれるため、実装コストがほぼゼロで「とりあえずのログ」を得られます。
しかし、この「とりあえず」が最大の落とし穴です。
TraceLayerをデフォルト設定で使い続けることは、構造化されていないテキストログの山を生み出し、運用フェーズで深刻な生産性低下を招きます。

デフォルト出力がもたらす非構造化テキストの弊害

TraceLayerのデフォルト動作は、info!レベルでリクエストの開始と終了を、error!レベルでエラーをそれぞれ人間可読な文字列として出力します。
一見すると親切ですが、この出力はキーとバリューの区別が曖昧で、たとえばstatus=404とmessage="Not Found"が単なるスペース区切りのテキストとして連結されます。
この形式では、ログ集計ツール（ElasticsearchやCloudWatch Logs Insightsなど）でフィールドベースのクエリを実行することが不可能に近くなります。

具体的な例を示しましょう。
デフォルトのTraceLayerが出力するログは、以下のような行になります。

2026-08-25T12:34:56.789Z INFO request{method=GET path=/api/users version=HTTP/1.1}: started
2026-08-25T12:34:56.890Z INFO request{method=GET path=/api/users version=HTTP/1.1}: finished status=200 duration=101ms

これだけならまだ許容できるように見えます。
しかし、エラーが発生した場合、スタックトレースやエラーコンテキストが文字列として丸ごと埋め込まれるため、ログ1行が数千文字に達することもざらです。
その結果、以下のような問題が連鎖的に発生します。

ログのパース処理が正規表現ベースの脆弱な実装に頼らざるを得なくなる
フィールド（例：statusやduration）が数値であるにも関わらず、文字列としてしか検索できず、範囲指定ができない
複数のサービス間でログフォーマットが統一されず、横断的なトレースが絶望的になる

TraceLayerのカスタマイズで解決できるが、それすらも過信は禁物

確かに、TraceLayerはmake_span_withやon_responseなどのコールバックを提供しており、カスタマイズすることでJSON出力や独自フィールドの追加が可能です。
しかし、ここで注意すべきは、そのカスタマイズが結局は場当たり的な対処に終わりがちという点です。
たとえば、on_responseクロージャ内でtracing::info!を呼び出して構造化フィールドを追加しようとしても、デフォルトのinfo!マクロはテキスト出力を前提としているため、結果的にキーと値が混在した曖昧な出力になることが多いのです。

また、TraceLayerはリクエストとレスポンスの「表面」しか扱いません。
アプリケーション内部のビジネスロジックやデータベースアクセス、外部API呼び出しなど、より深いレイヤーでのログ出力はTraceLayerの範囲外です。
そのため、開発者は結局、ハンドラ関数内で個別にtracing::debug!やinfo!を散りばめることになりますが、これらのログはTraceLayerが生成するスパンとは異なるコンテキストで出力されるため、リクエスト単位での相関付けが困難になります。

構造化ログの不在がもたらす運用フェーズの現実

構造化されていないログは、開発環境では問題になりません。
しかし、本番環境で1秒間に数百のリクエストを捌くシステムでは、ログの検索性の低さがそのまま障害対応時間の増加に直結します。
たとえば、「5分間にステータスコード500が発生したリクエストのうち、特定のユーザーエージェントからのものだけを抽出する」というクエリを考えてみてください。
構造化ログであれば、status=500 AND user_agent LIKE "%~Bot%"の1行で完了しますが、非構造化テキストではgrepやawkを駆使した複雑なワンライナーを書く必要があり、しかも誤検出のリスクが常に付きまといます。

さらに悪いことに、非構造化ログはアラートルールの精度を著しく劣化させます。
たとえば、errorレベルで出力されるログが、クライアントエラー（404）とサーバーエラー（500）の両方を含んでいる場合、単純に「errorレベルのログが10件/分以上」というアラートを設定すると、クライアントエラーの増加で過剰にアラートが飛び、運用者はアラート疲れを起こします。
その結果、本当に致命的なサーバー障害を見逃すという、本末転倒な事態に陥るのです。

では、なぜ開発者はTraceLayerに依存し続けるのか

その理由は明白で、実装の容易さと即時的な成果です。
TraceLayerを1行追加するだけでログが出るという体験は、開発初期のモチベーションを保つ上で確かに有効です。
しかし、その判断は短期的な楽観に過ぎません。
プロジェクトが成長し、チームが拡大し、トラフィックが増加するにつれて、この「借り」は確実に返済時期を迎えます。
返済手段は、ログ基盤の全面再構築という極めてコストの高いリファクタリングです。

ここで提案したいのは、最初からTraceLayerを補助的な位置付けに留め、主力のログ設計はtracingクレートのサブスクライバとカスタムスパンで構築するという方針です。
TraceLayerはあくまで「最低限の出入口」として使い、アプリケーション固有のログは全て構造化フォーマットで出力するように統一します。
そうすることで、後述する正しい解決策の土台が整います。

次のアンチパターンでは、エラーレベルの誤った使い方がどのように運用を混乱させるのかを掘り下げます。

アンチパターン2：エラーレベルの乱用で障害検知が鈍る問題

前章ではログの構造化の欠如について述べましたが、ここではそれと同様に深刻でありながら、初学者からベテランまで無意識に犯しやすいログレベルの乱用という問題に焦点を当てます。
axumに限らず、多くのWebフレームワークでは、エラーハンドリングの過程でerror!マクロを呼び出すことが推奨される場面があります。
しかし、この「とりあえずerrorで出力しておけ」という習慣が、運用監視の神経を完全に麻痺させるのです。

なぜ一律errorが問題なのか

ログレベルは、単なる「出力の色分け」ではありません。
それはアクションの優先度を定義する重要なシグナルです。
具体的には、errorは「即座に人間の介入が必要な状態」、warnは「注視すべきだが即時対応は不要な状態」、infoは「通常運用の一部として記録すべき状態」を意味します。
この階層が崩壊するとき、運用者はノイズに埋もれて本当の障害を見逃します。

例えば、axumのハンドラでユーザー入力のバリデーションエラーが発生した場合、これはHTTPステータスコードで言えば400系のクライアントエラーです。
このケースでerror!を使ってしまうと、クライアントの誤ったリクエストがサーバーサイドの障害と同じレベルで扱われます。
結果として、監視ダッシュボードではエラーレートが異常に高く表示され、アラートが頻発し、運用チームは「またか」とアラートを無視するようになります。
これこそが、アラート疲れの本質です。

ステータスコードとログレベルの誤ったマッピング

さらに悪質なケースとして、内部処理で回復可能なエラー（例：外部APIのタイムアウトリトライ）をerrorとして出力し、その後に正常応答を返すパターンがあります。
この場合、ログ上ではエラーが記録されているにもかかわらず、エンドユーザーには成功レスポンスが返ります。
この矛盾は、障害対応時に「ログはエラーを言っているのにシステムは動いている」という混乱を招き、結果として原因調査の時間を無駄に引き延ばします。

下表に、axumにおける典型的なシナリオと、誤ったレベル設定、正しいレベル設定を整理します。

シナリオ	ステータスコード	誤ったレベル	正しいレベル	理由
リクエストパラメータ不正	400 Bad Request	error	warn または info	クライアント起因であり、サーバーは正常動作
認証トークン期限切れ	401 Unauthorized	error	warn	再認証で回復可能。監視はするが即時対応不要
データベース接続失敗	500 Internal Server Error	info	error	サービス停止に直結するため即時対応必須
レートリミット超過	429 Too Many Requests	error	info	設計上の制御であり、システム異常ではない
外部APIの一時的エラー（リトライ成功）	200 OK（最終）	error	warn	リトライで回復したが、注視すべき事象

この表から明らかなように、同じ「例外が発生した」という事象でも、その原因と影響範囲によって適切なレベルが全く異なります。
axumでは、Result型とカスタムエラー型を組み合わせることで、エラーの種類を細かく分類できるため、レベル分けの設計は比較的容易です。
にもかかわらず、多くのプロジェクトではanyhow::ErrorやBox<dyn Error>を使ってエラーを一律に扱い、その結果としてレベルも一律になってしまうのです。

トレードオフ：ログ出力のコストと粒度

ここで考慮すべきもう一つの点は、warnやinfoの出力を増やしすぎると、ログの総量が肥大化し、ストレージコストや検索性能に影響を与えるというトレードオフです。
しかし、これは「出力しない」という選択ではなく、「集約的にサンプリングする」あるいは「重要度に応じて出力先を分ける」といった戦略で対処すべきものです。
たとえば、errorはSlackやPagerDutyに即時通知し、warnはElasticsearchにインデックスするがアラートは発行しない、infoは長期保存用にS3に圧縮保存する、といった運用が考えられます。

実装上の具体的な指針

では、axumでどう実装するか。
まず、エラー型を定義する際に、is_client_error()やis_retryable()といったメソッドを持たせることを推奨します。
そして、ミドルウェア内でエラーキャッチ時にこれらのメソッドを呼び出し、適切なログレベルを動的に決定します。

また、tracingのevent!マクロでは、レベルを動的に指定できるため、ハンドラ内で直接error!やwarn!をハードコードするのではなく、エラーオブジェクト自身にレベル情報を持たせる設計が有効です。

最後に、絶対に避けるべきは、デバッグ目的で一時的にerror!を仕込み、それをそのままリリースすることです。
この「仮のログ」は、後々まで残り、運用者の判断を誤らせます。
コードレビューでログレベルを必ず確認する習慣を、チームに根付かせてください。

ログレベルは、システムの「緊急度インジケーター」です。
このインジケーターが正しく機能しなければ、障害検知は遅れ、回復も遅れます。
結果として、サービス品質だけでなく、開発チームの信頼性までもが損なわれることを、肝に銘じておくべきでしょう。

アンチパターン3：ログへの機密情報混入が招くセキュリティリスク

構造化されておらず、エラーレベルも適切でないログは運用効率を損ねますが、それ以上に深刻なのがログへの機密情報の混入です。
この問題は、セキュリティインシデントとして直ちに法的・財務的な責任を問われる可能性があり、単なる「バッドプラクティス」の域を超えています。
axumはextractorを用いてリクエストデータを簡単に取得できるため、うっかりその情報をログに出力してしまう開発者が後を絶ちません。

なぜaxumで機密情報漏洩が起きやすいのか

axumのハンドラ関数は、Form、Json、Query、さらにはHeadersといった抽出器を使って、リクエストから構造化データを即座に受け取れます。
この便利さが仇となり、開発者はデバッグ目的で「とりあえず受け取った構造体を{:?}で表示する」という行為に走ります。
特にderive(Debug)が実装された構造体であれば、そのフィールドがたとえパスワードやクレジットカード番号であっても、全ての内容が文字列としてログにベタ書きされます。

典型的な被害例を挙げましょう。
ユーザー登録APIで、リクエストボディが以下のようなJSONだったとします。

{
  "email": "user@example.com",
  "password": "SuperSecret123!",
  "credit_card": "4111-1111-1111-1111"
}

そして、ハンドラ内でdbg!(&payload)やinfo!("received: {:?}", payload)と書いてしまえば、この平文のパスワードとクレジットカード番号が永遠にログファイルに残存します。
ログは通常、複数のシステムを経由し（例：Fluentd → Elasticsearch → バックアップS3）、削除されることは稀です。
つまり、一度出力された機密情報は、事実上「公開された」も同然なのです。

セキュリティ要件とコンプライアンスの観点

このようなログ出力は、GDPRやPCI DSS、日本の個人情報保護法といった各種コンプライアンスに明確に違反します。
特に、ログに含まれる個人情報（メールアドレスやIPアドレスなど）は「保有個人データ」として扱われ、適切なアクセス制御や暗号化、あるいはマスキングが要求されます。
しかし、ログはテキストファイルとして保存されることが多く、データベースのような行レベルのセキュリティを適用できません。
そのため、ログに機密情報を出力すること自体が、セキュリティ設計上の重大な過失と見なされます。

さらに厄介なのは、この問題がテスト環境では顕在化しにくいという点です。
開発者はダミーデータでテストするため、平文のパスワードがログに出ても「気にしない」で済ませます。
しかし、本番環境では実際のユーザーデータが流れ込み、その瞬間からリークが始まります。
そして、このリークは通常、セキュリティ監査や顧客からの指摘がなければ発覚せず、気づいた時にはすでに手遅れというケースがほとんどです。

うっかりミスを防げない文化の問題

技術的な対策以前に、「ログはデバッグ用」という認識自体が問題です。
多くの開発者は、ログ出力を開発中の一時的なトレース手段と捉え、リリース前に削除したり、マスク処理を追加することを忘れます。
しかし、現代のマイクロサービス環境では、一度リリースされたログ設定は変更が難しく、また出力箇所が分散しているため、事後的なマスク処理の適用は極めて困難です。

ここで重要なのは、機密情報はログに出力しないというポリシーを、コーディング規約レベルで強制することです。
具体的には、以下のようなルールをチームで合意しておくべきでしょう。

リクエストボディ全体をログ出力することを禁止し、必要なフィールドのみを選択的に出力する
Debugトレイトの実装をカスタマイズし、機密フィールドには#[debug(skip)]を付与する
ログ出力用の専用DTO（Data Transfer Object）を用意し、機密情報を除外した構造体を渡す
開発環境と本番環境でログ出力の詳細度を切り替える機能を組み込む（例：環境変数で制御）

現実的な対策としてのマスキングとハッシュ化

完全に出力をゼロにするのが理想ですが、運用上、エラーの原因調査には一部の識別情報が必要なケースもあります。
その場合は、マスキング（例：メールアドレスのドメイン部分を*に置換） や、ハッシュ化（例：ユーザーIDをSHA-256でハッシュして出力） を施した上で出力する手法が有効です。
ただし、ハッシュ化は元の値との突合せが必要な場合にのみ使い、単なる難読化として使うのは避けるべきです（短い値はレインボーテーブルで容易に逆引きされるため）

axumでは、カスタム抽出器を使ってリクエストデータを「ログ出力用にサニタイズ済みの型」として受け取る方法も考えられます。
例えば、SensitiveStringというラッパー型を定義し、そのDisplay実装では常に"***"を返すようにします。
そして、この型をハンドラの引数として受け取ることで、誤って平文をログに出すリスクをコンパイル時に排除できます。

このアンチパターンが他のものと決定的に異なるのは、対策の遅れが直接的に顧客の信頼喪失や法的制裁に結びつくという点です。
パフォーマンス問題はチューニングで何とかなりますが、セキュリティインシデントは取り返しがつきません。
ログ設計の段階で「出力してはいけないもの」を明確に定義し、コードレビューと静的解析ツール（例：cargo-auditやカスタムClippyリント）で機械的にチェックする仕組みを必ず導入してください。

アンチパターン4：トレースID不在で分散トレースが不可能な状態

ここまでのアンチパターンは、いずれも単一インスタンス内でのログ品質に関するものでした。
しかし、現代のWebアプリケーションは、単一のプロセスで完結することは稀です。
複数のマイクロサービス、キューイングシステム、外部API、データベースクラスタなど、リクエスト1つが数十のコンポーネントを横断するのが当たり前の時代において、トレースIDの不在は分散トレースを完全に不能にします。
このアンチパターンは、構造化やレベル分けよりも発見が難しく、かつ影響範囲が広大である点で、特に危険です。

トレースIDとは何か、なぜ必要なのか

トレースIDとは、あるリクエストのライフサイクル全体を通じて一意に付与される識別子です。
このIDがあれば、ログ集約システムでtrace_id = "abc-123"と検索するだけで、そのリクエストが関わった全てのサービス、全てのスパン、全てのログ行を時系列で取得できます。
逆に、トレースIDがなければ、各サービスのログはリクエスト単位ではなく「時刻」や「ユーザーIP」といった曖昧なキーでしか紐付けられず、特にエラーが発生した際に「どのリクエストが原因か」を特定するのに数十分から数時間を要することになります。

axumアプリケーションでは、リクエストが到達した時点でトレースIDを生成し、それを以降の全ての非同期タスク、データベースコール、外部API呼び出しに伝搬させる必要があります。
しかし、多くのプロジェクトではこの伝搬が中途半端か、そもそも生成自体を行っていません。

なぜトレースIDが伝搬されないのか

理由の一つは、axumの非同期モデルにおけるコンテキストの継承の難しさにあります。
tracingクレートはSpanを介してコンテキストを伝搬しますが、これはtokioのタスク単位で管理されます。
そのため、ハンドラ内でtokio::spawnを使って別タスクを起動する場合、親スパンを明示的に継承しない限り、子タスクは異なるトレースIDを持つことになります。
開発者はこの挙動を意識せずにspawnを使い、結果としてログがバラバラに出力されるのです。

さらに、外部サービスへのHTTPリクエストでは、W3C Trace Contextヘッダ（traceparentやtracestate）を正しく設定しなければなりません。
これを怠ると、たとえ自サービス内でトレースIDを持っていても、外部サービス側では別のIDが生成され、エンドツーエンドのトレースが断絶します。
reqwestやhyperを使う場合、このヘッダの追加は数行のコードですが、意識して実装しなければデフォルトでは行われません。

トレースID不在がもたらす運用上の具体的な悲劇

具体例を考えましょう。
ユーザーがフロントエンドからリクエストを送信し、axumのAPIゲートウェイが受け取り、認証サービスとデータベースと外部決済APIを順次呼び出し、最終的にレスポンスを返すとします。
このうち決済APIでタイムアウトが発生したとします。

トレースIDがある場合：ゲートウェイのログにtrace_id=xyz、決済APIのログにも同じtrace_id=xyzが記録されているため、1回の検索で「決済APIへのリクエストが3.2秒かかってタイムアウトした」ことが瞬時に判明します
トレースIDがない場合：ゲートウェイのログには「外部APIタイムアウト」とだけあり、決済APIのログには別のリクエストIDが付与されています。時刻を頼りに両者のログを照合しようとしても、同時刻に複数のリクエストが存在するため、どのリクエストが対応するのかを推定するしかありません。特にトラフィックが多い時間帯では、この推定はほぼ不可能です

この差は、障害対応時間を「5分」と「2時間」に分けるだけでなく、原因の誤特定を招き、無関係なコンポーネントの再起動や設定変更といった無駄な作業を生み続けます。

そもそもトレースIDの生成すらしていないケース

さらに初歩的なのが、トレースIDそのものを生成していないパターンです。
tracingのデフォルトスパンはランダムなIDを持ちますが、そのIDはログ行に自動では出力されません。
開発者はfmt::layer()にwith_span_id(true)を設定するか、カスタムフォーマッタを実装して初めてIDをログに含められます。
この設定を忘れると、各ログ行は「どのスパンから出力されたか」が一切わからない、無国籍な出力になります。

また、TraceLayerはデフォルトではリクエストごとにスパンを生成しますが、そのスパンIDをログに含めるかどうかは出力フォーマッタの設定次第です。
つまり、TraceLayerを導入しただけではトレースIDは有効活用されません。

正しい方向性：トレースIDを第一級市民として扱う

このアンチパターンを脱却するには、以下の3つの原則を徹底してください。

リクエスト受信時に必ず新しいトレースIDを生成し、それをルートスパンとして設定する
全てのログ出力にトレースIDフィールドを必ず含める（構造化ログの一部として）
外部サービスへの呼び出しには、W3C Trace Contextに準拠したヘッダを付与する

特に、axumではミドルウェア層でトレースIDを生成し、それをrequestの拡張機能（extensions）に格納することで、ハンドラ以降の全てのレイヤーで同一IDを参照可能にできます。
この実装は後述する正しい解決策で詳述しますが、ここで強調しておきたいのは、トレースIDの不在は「機能不足」ではなく「設計欠陥」 であるという認識です。
それは、分散システムにおいてリクエストの「身分証」を発行しないことに等しく、運用の根幹を揺るがす問題だと理解してください。

正しい解決策1：tracingクレートと構造化ログの導入

tracingのSpanとJSONフォーマットで構造化されたログ出力のサンプルコード

ここからは、前章までに列挙したアンチパターンを全て同時に解決するための具体的な設計指針を提示します。
最初のステップは、ログ出力の基盤そのものを刷新することです。
具体的には、従来のlogクレートやprintln!デバッグから、tracingクレートエコシステムへと完全に移行します。
tracingは、構造化されたスパンとイベントを非同期コンテキストで扱えるように設計されており、axumとの親和性は極めて高いです。

なぜtracingなのか

tracingは単なるログライブラリではなく、インストルメンテーション（計装）のフレームワークです。
スパン（開始・終了を持つ処理の区間）とイベント（時点でのログ出力）を明確に分離し、さらに親子関係や並列関係を保持できます。
これにより、リクエスト全体を1つのルートスパンとして定義し、その内部でデータベースアクセスや外部API呼び出しを子スパンとして配置することで、タイムライン上の因果関係が可視化されます。

加えて、tracingは構造化データをファーストクラスでサポートします。
event!(target: "app", level = Level::INFO, user_id = 12345, status = 200)のように、キーとバリューのペアを任意に付与でき、これらのフィールドは出力時にJSONなどの機械可読形式にシリアライズされます。
これにより、ElasticsearchやCloudWatch Logs Insightsでのフィールドベースクエリがシームレスに実現します。

具体的な導入手順とサブスクライバ設定

まず、Cargo.tomlに以下の依存関係を追加します。

[dependencies]
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["json", "env-filter"] }
tracing-appender = "0.2"

次に、アプリケーションのエントリポイント（main関数）でサブスクライバを初期化します。
ここで重要なのは、環境変数（例：RUST_LOG）で動的にログレベルを制御できることと、出力フォーマットをJSONに固定することです。
以下は、コンソール出力とファイル出力を同時に行う設定例です。

use tracing_subscriber::{fmt, layer::SubscriberExt, util::SubscriberInitExt, EnvFilter};

fn init_logging() {
    let env_filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| EnvFilter::new("info"));

    let fmt_layer = fmt::layer()
        .json()
        .with_span_list(false)
        .with_current_span(true)
        .with_span_events(fmt::format::FmtSpan::CLOSE)
        .with_target(true)
        .with_thread_ids(false)
        .with_thread_names(false);

    tracing_subscriber::registry()
        .with(env_filter)
        .with(fmt_layer)
        .init();
}

この設定により、すべてのログ出力が1行1件のJSONオブジェクトとして出力されます。
with_span_events(FmtSpan::CLOSE)を指定することで、スパン終了時にそのスパンが保持していた全てのフィールド（後述するトレースIDやリクエスト情報など）が自動的にログ行に含まれるようになります。

構造化ログの実践的な書き方

ハンドラ関数内では、info!やerror!といったマクロを使用する際に、必ずフィールドを明示的に指定します。
例えば、以下のように書きます。

async fn get_user(Path(user_id): Path<Uuid>) -> impl IntoResponse {
    tracing::info!(user_id = %user_id, "リクエスト受信");
    // 処理...
    tracing::info!(user_id = %user_id, status = 200, "正常終了");
    (StatusCode::OK, Json(response))
}

ここでポイントは、メッセージ文字列とフィールドを分離していることです。
これにより、検索エンジンはuser_idフィールドを認識し、特定のユーザーに関するログだけを高速に抽出できます。
また、%user_idはDisplayトレイトを使ったフォーマット指定で、?を使えばDebugフォーマットも可能です。

スパンとイベントの使い分け

さらに、リクエスト全体をスパンで包むことで、自動的に全ての子ログに共通フィールドを付与できます。
axumのミドルウェアで以下のように実装します。

async fn trace_middleware<B>(req: Request<B>, next: Next<B>) -> Result<Response, Infallible> {
    let trace_id = Uuid::new_v4().to_string();
    let span = tracing::info_span!("http_request", trace_id = %trace_id, method = %req.method(), path = %req.uri().path());
    let _guard = span.enter();
    // 以降の全てのログは、このスパンのフィールドを自動継承
    let response = next.run(req).await;
    // スパン終了時にCLOSEイベントが自動出力される
    response
}

こうすることで、tracing::info!を呼び出すたびにtrace_idを手動で指定する必要がなくなります。
また、スパン終了時には実行時間も自動計測され、duration_msなどのフィールドが追加されるため、パフォーマンス分析のための追加実装が不要です。

構造化ログがもたらす運用改善の実例

構造化ログを導入した後は、ログ集約システムで「statusが500以上で、かつpathが/api/paymentに一致するログを過去1時間分」といったクエリが数秒で実行できます。
また、trace_idでフィルタリングすれば、特定のリクエストの全工程を時系列でトレースすることも容易です。

さらに、tracingはOpenTelemetryとの統合も標準でサポートしており、JaegerやTempoなどの分散トレーシングバックエンドにスパンデータをエクスポートできます。
これにより、ログ検索だけでなく視覚的なウォーターフォールチャートでリクエストのボトルネックを特定できるようになります。

この第一の解決策は、後述する全ての正しい実装の基盤となります。
構造化ログなしに、トレースID伝搬やエラーレベル適正化は実質的に意味をなしません。
最初の一歩として、今すぐtracingへの移行をプロジェクト計画に組み込んでください。

正しい解決策2：エラー種別に応じたログレベルの適切な割り振り方

ステータスコード別にerror、warn、infoを色分けして表示したログレベル設計図

構造化ログの基盤が整ったならば、次はログレベルの適正化に取り組みます。
前章で述べたように、一律errorで出力する習慣は監視を無効化します。
ここでは、axumの型システムを活用して、エラーの性質に応じて自動的に適切なログレベルを選択する設計パターンを紹介します。

エラー型にレベル情報を組み込む設計

まず、アプリケーション全体で使用するカスタムエラー型を定義します。
この型は、単にエラーの種類を列挙するだけでなく、各バリアントがどのログレベルに対応するかを保持します。
Rustのenumとトレイトを組み合わせることで、非常に宣言的な実装が可能です。

use tracing::Level;

#[derive(Debug, thiserror::Error)]
pub enum AppError {
    #[error("バリデーションエラー: {0}")]
    Validation(String),
    #[error("認証トークンが無効です")]
    Unauthorized,
    #[error("データベース接続に失敗しました: {0}")]
    DatabaseConnection(#[source] sqlx::Error),
    #[error("外部APIがタイムアウトしました: {0}")]
    ExternalApiTimeout(#[source] reqwest::Error),
    #[error("予期せぬ内部エラー: {0}")]
    Internal(#[source] Box<dyn std::error::Error + Send + Sync>),
}

impl AppError {
    pub fn log_level(&self) -> Level {
        match self {
            AppError::Validation(_) => Level::WARN,
            AppError::Unauthorized => Level::WARN,
            AppError::DatabaseConnection(_) => Level::ERROR,
            AppError::ExternalApiTimeout(_) => Level::WARN,
            AppError::Internal(_) => Level::ERROR,
        }
    }

    pub fn http_status(&self) -> StatusCode {
        match self {
            AppError::Validation(_) => StatusCode::BAD_REQUEST,
            AppError::Unauthorized => StatusCode::UNAUTHORIZED,
            AppError::DatabaseConnection(_) => StatusCode::INTERNAL_SERVER_ERROR,
            AppError::ExternalApiTimeout(_) => StatusCode::GATEWAY_TIMEOUT,
            AppError::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
        }
    }
}

この設計の要点は、ログレベルとHTTPステータスコードが独立して定義されていることです。
たとえばExternalApiTimeoutは、クライアントには504を返しますが、ログレベルはWARNです。
なぜなら、外部APIの一時的な遅延はリトライで回復する可能性が高く、即座にページャーを鳴らすほどの緊急事態ではないからです。
一方、DatabaseConnectionはERRORとし、即時対応を促します。

エラーハンドリングミドルウェアでのレベル適用

次に、axumのエラーハンドリングミドルウェア（HandleErrorLayerや独自ミドルウェア）内で、このlog_level()を呼び出して実際のログ出力を行います。
以下の例では、tracingのevent!マクロを動的レベル指定で使います。

async fn handle_error(error: AppError) -> impl IntoResponse {
    let status = error.http_status();
    let level = error.log_level();

    tracing::event!(
        level,
        status = status.as_u16(),
        error = %error,
        error_type = std::any::type_name_of_val(&error),
        "リクエスト処理中にエラーが発生"
    );

    // クライアントへのレスポンスは、機密情報を除いた形で返す
    (status, Json(json!({ "error": error.to_string() })))
}

ここで重要なのは、tracing::event!にlevel変数をそのまま渡せる点です。
これにより、エラー種別ごとに条件分岐を書く必要がなくなり、コードの重複が劇的に削減されます。

運用監視との連携戦略

ログレベルを適正化しただけでは不十分です。
そのレベルをどう監視システムに反映させるかが次の課題です。
以下のような運用ルールを策定することを推奨します。

ERRORレベルのログは、PagerDutyやSlackのクリティカルチャネルに即時通知する。ただし、5分間で3件以上など、バースト検知のための閾値を設定する
WARNレベルのログは、ダッシュボードのトレンド表示に利用し、週次レビューで増減を確認する。アラートは発報しないが、異常な増加時には手動で調査する
INFOレベルはデバッグ用途とパフォーマンス分析に限定し、長期保存するが、リアルタイム通知の対象外とする

この階層化により、運用者は真に重要な通知だけに集中でき、アラート疲れを防げます。
また、ERRORの定義が厳格になることで、障害発生時に「本当にサービスが停止しているのか」をログだけで即座に判断できるようになります。

動的サンプリングとレートリミットの導入

さらに高度な対策として、WARNレベルでも大量発生するケース（例：ボットによる大量のバリデーションエラー）では、tracing_subscriberのサンプリング機能を使い、一部のログだけを出力する手法も有効です。
ただし、サンプリングはエラーの傾向分析を阻害するリスクもあるため、エラーレートが閾値を超えた場合のみ有効化する動的フィルタを実装するとよいでしょう。

// 環境変数でサンプリングレートを制御
let sample_rate = std::env::var("LOG_SAMPLE_RATE")
    .ok()
    .and_then(|v| v.parse::<f64>().ok())
    .unwrap_or(1.0);

let filter = EnvFilter::new("info")
    .add_directive("warn".parse().unwrap())
    .add_directive("error".parse().unwrap());
// サンプリングはWARN以上に適用

型システムを活用したコンパイル時チェック

最後に、Rustの強力な型システムを活用して、ログレベルの指定漏れをコンパイル時に検出する方法も紹介します。
AppErrorにlog_level()を実装する代わりに、各バリアントにレベルを関連付けるトレイトを定義し、エラーハンドラがそのトレイトを要求するようにします。
これにより、新しいエラー種別を追加した際に、レベル未定義のままリリースされることを防げます。

このように、エラー種別とログレベルを明示的に関連付ける設計は、一見するとオーバーエンジニアリングに思えるかもしれません。
しかし、チーム規模が拡大し、エラーの種類が増えるにつれて、その恩恵は計り知れません。
ログレベルは「運用者が最初に目にする判断材料」です。
その判断材料を誤りなく届けるために、コードレベルでの厳格な管理を徹底してください。

正しい解決策3：Sensitiveラッパーとマスキングで機密情報を保護する実装

機密データをSensitive型でラップし、マスク処理を施したRustコードスニペット

前章まででログの構造化とレベルの適正化は達成しました。
しかし、どれほど構造化されていても、そこに生のパスワードやクレジットカード情報が含まれていれば、セキュリティ上の重大な脆弱性に変わりはありません。
ここでは、Rustの型システムを最大限に活用して、コンパイル時に機密情報の漏洩を防ぐ実践的なテクニックを紹介します。

型で機密情報をマークするSensitiveラッパー

最もシンプルで効果的な方法は、機密データをラップする専用の型を定義することです。
この型はDebugやDisplayの実装をカスタマイズし、一切の生データを外部に露出させません。

use std::fmt;
use serde::{Deserialize, Serialize};

#[derive(Clone, Serialize, Deserialize)]
pub struct Sensitive<T>(T);

impl<T> Sensitive<T> {
    pub fn new(inner: T) -> Self {
        Self(inner)
    }

    // 内部値が必要な処理（ハッシュ化や検証など）のためのメソッド
    pub fn expose<F, U>(&self, f: F) -> U
    where
        F: FnOnce(&T) -> U,
    {
        f(&self.0)
    }
}

// Debug実装では一切の情報を隠す
impl<T> fmt::Debug for Sensitive<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Sensitive(<redacted>)")
    }
}

// Displayも同様に隠す
impl<T> fmt::Display for Sensitive<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "***")
    }
}

このSensitive型を使用すると、たとえ開発者がうっかり{:?}でログ出力しようとしても、実際の値が表示されることは決してありません。
axumの抽出器と組み合わせることで、リクエストボディの受信時に即座に機密フィールドをラップできます。

抽出器レベルでのサニタイズ

axumでは、Json抽出器を使ってリクエストボディを受け取るのが一般的です。
ここで、機密フィールドを持つ構造体を定義する際に、該当フィールドをSensitiveで包むことを強制します。

use serde::Deserialize;
use axum::Json;

#[derive(Debug, Deserialize)]
pub struct LoginRequest {
    pub email: String, // メールアドレスは識別情報だが、機密度は中程度
    #[serde(deserialize_with = "deserialize_sensitive")]
    pub password: Sensitive<String>,
}

fn deserialize_sensitive<'de, D>(deserializer: D) -> Result<Sensitive<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let s = String::deserialize(deserializer)?;
    Ok(Sensitive::new(s))
}

async fn login_handler(Json(payload): Json<LoginRequest>) -> impl IntoResponse {
    // この時点で payload.password は Sensitive<String>
    tracing::info!(email = %payload.email, "ログイン試行");
    // 以下の行はコンパイルエラーにならずとも、出力は "***" になる
    tracing::debug!(password = %payload.password, "パスワード受信");

    // 実際の検証処理では expose を使って内部値にアクセス
    let is_valid = payload.password.expose(|pwd| {
        // ハッシュ化されたパスワードとの比較など
        verify_password(pwd)
    });

    // ...
}

この実装により、ログ出力時の人為的ミスを型レベルでブロックできます。
Sensitive型はDisplayとDebugを隠蔽しているため、%や?を使ったフォーマット指定でも生データが漏れません。

部分的なマスキング（部分開示）の実装

ただし、運用上、エラー調査のために一部の情報（例：メールアドレスのドメイン部分、クレジットカードの下4桁）が必要なケースもあります。
その場合は、Sensitive型にマスキング用のメソッドを追加し、意図的に一部だけを出力できるようにします。

impl Sensitive<String> {
    pub fn mask_email(&self) -> String {
        let inner = &self.0;
        if let Some(at_pos) = inner.find('@') {
            let local = &inner[..at_pos];
            let domain = &inner[at_pos..];
            if local.len() <= 2 {
                format!("{}{}", "*".repeat(local.len()), domain)
            } else {
                format!("{}…{}", &local[..1], &local[local.len()-1..], domain)
            }
        } else {
            "***".to_string()
        }
    }

    pub fn mask_credit_card(&self) -> String {
        let inner = &self.0;
        let digits: String = inner.chars().filter(|c| c.is_ascii_digit()).collect();
        if digits.len() >= 4 {
            format!("****-****-****-{}", &digits[digits.len()-4..])
        } else {
            "****".to_string()
        }
    }
}

// 使用例
tracing::info!(
    email = %payload.email,
    masked_email = %payload.email.mask_email(),
    "ログイン試行"
);

このように、マスキングは明示的なメソッド呼び出しとして実装することで、「デフォルトで生データが出力される」という危険を排除します。

静的解析とコードレビューの補助

型システムだけでは完全には防げないケース（例：Sensitiveを外してから誤ってログ出力する）に対処するため、Clippyのカスタムリントやcargo-denyなどのツールを導入するのも有効です。
また、コードレビューではログ出力行にSensitive型の変数が直接渡されていないかを必ず確認するチェックリストを用意します。

さらに、開発環境と本番環境でログ出力の詳細度を変える仕組みも併用します。
たとえば、開発環境ではSensitive型でもDebugで中身を表示するようにコンパイルフラグを切り替え、本番ビルドでは完全に隠蔽する、といったアプローチが考えられます。

// Cargo.toml で features = ["dev-logs"] を定義
#[cfg(feature = "dev-logs")]
impl<T> fmt::Debug for Sensitive<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "Sensitive({:?})", self.0)
    }
}

ログ出力前の最終フィルタリング

万が一、サードパーティのライブラリが機密情報をログに出力する可能性がある場合は、サブスクライバ層でフィルタリングを行います。
tracing_subscriberのLayerトレイトを実装し、特定のパターン（例：passwordやcredit_cardというキーワードを持つフィールド）を検出したら、その値を自動で[REDACTED]に置換するミドルウェアを挟むことも可能です。

この多重防御戦略により、ヒューマンエラーとライブラリ起因の漏洩の両方をカバーできます。
機密情報の保護は、「後からマスクする」ではなく「最初から出力させない」 が原則です。
Sensitiveラッパーはその原則をコードで具現化する、最もRustらしい解決策の一つと言えるでしょう。

正しい解決策4：独自ミドルウェアでトレースIDを自動伝搬させる仕組み

axumのミドルウェアでリクエスト毎にユニークなtrace_idを生成し伝搬する流れ図

構造化ログ、適切なレベル分け、機密情報の保護——これらの基盤が整ったら、最後に残された最大の課題は分散トレースの実現です。
前章のアンチパターンで述べたように、トレースIDが伝搬されないシステムは、複数サービスにまたがる障害の原因究明を著しく困難にします。
ここでは、axumのミドルウェア機構を活用して、リクエスト単位のトレースIDを自動生成・伝搬する堅牢な仕組みを構築します。

トレースIDの生成とスパンへの埋め込み

最初のステップは、リクエスト受信時にユニークなトレースIDを生成し、それをルートスパンに組み込むことです。
UUID v4を推奨しますが、既に上位のロードバランサやAPIゲートウェイからX-Request-IDヘッダが渡される場合は、それを流用しても構いません。
重要なのは、1つのリクエストに対してライフサイクル全体で不変のIDを割り当てることです。

use axum::{middleware, Router, RequestPartsExt};
use tower_http::request_id::{MakeRequestId, RequestId};
use uuid::Uuid;

// リクエストID生成ミドルウェア
#[derive(Clone)]
pub struct UuidRequestId;

impl MakeRequestId for UuidRequestId {
    fn make_request_id<B>(&mut self, _req: &axum::http::Request<B>) -> Option<RequestId> {
        let id = Uuid::new_v4().to_string();
        Some(RequestId::new(id.parse().unwrap()))
    }
}

// ミドルウェア本体（トレーススパンを作成）
pub async fn trace_middleware<B>(mut req: axum::extract::Request<B>, next: middleware::Next<B>) -> impl IntoResponse {
    // 既存のリクエストIDを取得（生成済みならそれを使う）
    let request_id = req
        .extensions()
        .get::<RequestId>()
        .map(|id| id.as_str().to_string())
        .unwrap_or_else(|| Uuid::new_v4().to_string());

    // メソッドとパスを抽出（所有権を移動しないよう参照で取得）
    let method = req.method().clone();
    let path = req.uri().path().to_string();

    // ルートスパンを作成し、トレースIDを明示的にフィールドとして設定
    let span = tracing::info_span!(
        "http_request",
        trace_id = %request_id,
        method = %method,
        path = %path,
        // 後でフィルタリングできるように追加フィールド
        service.name = "axum-api",
    );

    // スパンをガードで保持し、このリクエスト処理全体をカバー
    let _guard = span.enter();

    // トレースIDをレスポンスヘッダにも設定（クライアント側で相関を取れるように）
    let response = next.run(req).await;

    // レスポンスヘッダにトレースIDを付与（任意）
    let (mut parts, body) = response.into_parts();
    parts.headers.insert(
        "X-Trace-Id",
        request_id.parse().unwrap()
    );

    axum::response::Response::from_parts(parts, body)
}

外部サービスへのトレースコンテキスト伝搬

自サービス内での伝搬だけでは不十分です。
外部APIやデータベース、メッセージブローカーに対して同じトレースIDを渡すことで、エンドツーエンドのトレースを実現します。
HTTPクライアントにはreqwestを使用し、W3C Trace Context仕様に準拠したヘッダを自動追加するミドルウェアを実装します。

use reqwest::RequestBuilder;
use tracing::Span;

pub trait TraceContextExt {
    fn with_trace_context(self) -> Self;
}

impl TraceContextExt for reqwest::RequestBuilder {
    fn with_trace_context(self) -> Self {
        // 現在のスパンからトレースIDを取得
        let current_span = Span::current();
        let trace_id = current_span
            .field("trace_id")
            .and_then(|f| f.to_string().ok())
            .unwrap_or_else(|| "unknown".to_string());

        // W3C Trace Context ヘッダを設定 (format: version-traceid-parentid)
        let traceparent = format!("00-{}-0000000000000000-01", trace_id);
        self.header("traceparent", traceparent)
    }
}

// 使用例
async fn call_external_api() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    client
        .get("https://api.example.com/data")
        .with_trace_context()
        .send()
        .await?;
    Ok(())
}

この実装により、外部サービス側がW3C Trace Contextをサポートしていれば、リクエスト単位で完全なトレースチェーンが構成されます。
もし外部サービスが独自のヘッダ（例：X-Request-ID）しか受け付けない場合は、そのヘッダにも同じトレースIDを設定します。

非同期タスク間でのスパン継承

axumのハンドラ内でtokio::spawnを使って別タスクを起動する場合、デフォルトでは親スパンが継承されません。
これを解決するには、tracingのInstrumentトレイトを使って、子タスクに明示的にスパンをアタッチします。

use tracing::Instrument;

async fn handler() -> impl IntoResponse {
    // 現在のスパンを取得
    let span = tracing::info_span!("background_task");

    // 子タスクを生成し、スパンを継承
    let handle = tokio::spawn(
        async {
            tracing::info!("バックグラウンド処理開始");
            // この中でのログには自動的にtrace_idが含まれる
            do_heavy_work().await;
            tracing::info!("バックグラウンド処理終了");
        }
        .instrument(span)
    );

    // 必要に応じて join する
    handle.await.unwrap();
    // ...
}

このinstrumentメソッドは、クロージャや非同期ブロックに対してスパンをアタッチし、そのスコープ内での全てのログに自動的に親スパンのフィールド（トレースID含む）を継承させます。

ミドルウェアの登録と全体統合

最後に、これらをaxumのルータに組み込みます。
tower_httpのRequestIdLayerと組み合わせることで、リクエストIDの生成とスパン作成を一貫して行えます。

use tower_http::request_id::{MakeRequestId, PropagateRequestIdLayer, RequestIdLayer};

let app = Router::new()
    .route("/api/users", get(get_users))
    .layer(
        // リクエストID生成
        RequestIdLayer::new(UuidRequestId)
    )
    .layer(
        // トレースミドルウェア（カスタム実装）
        middleware::from_fn(trace_middleware)
    )
    .layer(
        // リクエストIDをレスポンスヘッダに伝搬
        PropagateRequestIdLayer::new()
    );

この構成により、全てのリクエストが自動的にトレースIDを持ち、そのIDがログ・レスポンスヘッダ・外部呼び出しに一貫して伝搬されます。
運用者は、クライアントから提供されたトレースIDを使って、APIゲートウェイからデータベースまで一気通貫のログ検索が可能になります。

メトリクスとの連携

トレースIDはログだけでなく、メトリクス（Prometheus等）のラベルとしても活用できます。
エラーレートをトレースID別に集計することで、特定のリクエストパターンに起因する障害を早期に発見できるようになります。

この独自ミドルウェア方式は、TraceLayerの代わりとなる完全に制御可能な実装です。
デフォルトのTraceLayerに頼るよりもコード量は増えますが、運用フェーズで得られる可観測性の質は桁違いです。
トレースIDの伝搬を「オプション」ではなく「必須要件」として設計に組み込むことが、真にスケーラブルなaxumシステムへの道です。

実践上の落とし穴：出力量とコストのトレードオフ

ここまで、構造化ログ、適切なレベル分け、機密保護、トレースID伝搬と、理想的なログ設計の要素を全て解説してきました。
しかし、これらのベストプラクティスをすべて同時に最高水準で実装すると、今度はログの出力量が爆発的に増加するという新たなジレンマに直面します。
ログは運用の命綱である一方、ストレージコスト、転送帯域、検索パフォーマンス、さらにはアプリケーション自体の処理オーバーヘッドと、あらゆるリソースを消費する重い資産でもあるのです。

出力量がもたらす3つのコスト

ログの出力量が増えると、以下の3つのコストが連動して上昇します。
それぞれを定量的に理解しておくことが、現実的な設計には不可欠です。

ストレージコスト：構造化JSONログはテキストよりサイズが大きくなります。1リクエストあたり数百バイトでも、1日1億リクエストあれば数十GB単位の増加となり、クラウドのログ保管料金は月間で数百万円に達することも珍しくありません
検索パフォーマンス：ElasticsearchやCloudWatch Logsでインデックス化されるフィールドが増えるほど、クエリ応答時間は線形に悪化します。特にtrace_idのような高カーディナリティフィールドは、インデックスサイズを著しく肥大化させます
アプリケーションオーバーヘッド：tracingのスパン生成やJSONシリアライズは、特に高負荷時にはCPUとメモリを消費します。ベンチマークによっては、ログ出力だけで全体のレイテンシが5〜15%増加したという報告もあります

サンプリングという選択肢とそのリスク

最も一般的な対策はサンプリング、すなわち全リクエストのうち一部だけを詳細ログとして出力し、残りはエラー時や特定条件時のみ出力する戦略です。
しかし、サンプリングはトレースの抜けを生むため、特定のリクエストだけを後から追跡したい場合に致命的な欠陥となります。

たとえば、エンドユーザーから「10分前にエラーが発生した」と報告を受けたとき、そのリクエストがサンプリングで除外されていたら、原因調査は不可能です。
このトレードオフを解決するには、サンプリング率を固定するのではなく、エラー発生時や特定のヘッダ（例：X-Debug: true）が付与されたリクエストだけは必ず出力する条件付きサンプリングを導入します。

// 条件付きサンプリングの例
let should_sample = if req.headers().contains_key("x-debug") {
    false // デバッグヘッダがあれば常に出力
} else if is_error {
    false // エラーは常に出力
} else {
    // 通常リクエストは1%だけ出力
    rand::random::<f64>() > 0.99
};

if should_sample {
    // 詳細ログを出力
} else {
    // 最小限のログ（trace_idとステータスのみ）に抑える
}

ログレベルの動的調整と環境分離

もう一つの現実的なアプローチは、環境ごとにログ出力の詳細度を変えることです。
開発環境ではdebugレベルまで出力し、ステージング環境ではinfo、本番環境ではwarn以上を基本としつつ、必要時にのみ動的にinfoを有効化できる仕組みを用意します。

tracing_subscriberのEnvFilterは実行時に再設定可能なため、管理用エンドポイント（セキュアに保護されたもの）からログレベルを動的に変更するAPIを実装することも有効です。

// 動的フィルタ更新の例（要認証）
async fn set_log_level(level: String) -> impl IntoResponse {
    let filter = EnvFilter::try_new(&level).unwrap();
    // グローバルなフィルタを差し替え（実装は要検討）
    tracing_subscriber::registry()
        .with(filter)
        .init();
    "ログレベルを変更しました"
}

ただし、動的変更はレースコンディションやパフォーマンスへの影響を考慮する必要があるため、本番導入前に入念なテストを実施してください。

ログのライフサイクル管理とコールドストレージ

さらに、ログの保存期間を階層化するのも効果的です。
直近7日間のログは高速なホットストレージ（Elasticsearchのホットノード）に置き、それより古いものはコールドストレージ（S3 Glacierなど）に圧縮保存し、検索頻度が低いことを前提にコストを抑えます。
また、errorレベルのログだけは長期保存し、infoは30日で削除するなど、重要度に応じた保持ポリシーを設定します。

下表に、出力量とコスト対策のマッピングを示します。

対策手法	適用対象	コスト削減効果	注意点
条件付きサンプリング	`info`以下の通常リクエスト	高い（80%以上削減可能）	エラー時は必ず出力する例外ルール必須
動的レベル変更	全ログ	中程度（オンデマンドで調整）	実装複雑性あり、セキュリティ要保護
ストレージ階層化	全ログ	長期コストで高い効果	検索レイテンシが増加（コールド層）
フィールド削減	JSONの全フィールド	中程度（1行あたり20〜30%削減）	必須フィールド以外を省くと分析の質が低下
バッファリングとバルク送信	全ログ出力処理	アプリケーションオーバーヘッド低減	バッファ溢れによるログ欠損リスク

理想論と現実のバランスをどう取るか

結論として、全てのリクエストに完全な構造化ログを出力することは、小規模プロジェクトでは可能でも、大規模システムでは現実的ではありません。
重要なのは、「何を絶対にログに残すか」と「何をサンプリングや省略で妥協するか」 を運用要件と予算に基づいて明確に定義することです。

筆者の経験則では、以下の優先順位を推奨します。

エラーと警告は100%出力（これが最優先。障害対応の根幹）
トレースIDとリクエスト基本情報（メソッド・パス・ステータス）は全てのリクエストで出力（これがなければ分散トレースが成立しない）
リクエストボディやカスタムフィールドはサンプリングまたはデバッグヘッダ時のみ（データ量の大半を占めるため）

この優先順位をコードに落とし込むことで、コストを抑えつつ運用に必要な情報を失わないバランスが取れます。
ログ設計において「完璧」を目指すよりも、「実用的に持続可能」な状態を目指すことが、結局は長期的なシステム健全性につながるのです。

まとめ：運用し続けられるログ設計とは何か

ここまで、axumにおけるログ設計のアンチパターンとその正しい解決策を、構造化からレベル分け、機密保護、トレース伝搬、そしてコスト管理に至るまで網羅的に解説してきました。
最後に、これらの知見を統合し、「運用し続けられるログ設計」の本質を改めて問い直してみましょう。

ログ設計が失敗する最大の要因は、「最初は動くから」という楽観主義にあります。
開発フェーズでは数件のリクエストしか流れず、エラーも限定的なため、非構造化ログでも問題なく見えます。
しかし、サービスが成長し、トラフィックが増え、チームが拡大するにつれて、その場しのぎのログは技術的負債の塊と化します。
そして、その負債は一度発生すると、リファクタリングに膨大な工数を要するため、結果として「ログは諦める」という悲しい選択を強いられることになります。

では、運用し続けられるログ設計とは何か。
それは「変化に耐えられる抽象化」 と 「運用フローに組み込まれた可観測性」 の2つを満たすものです。
具体的には、以下の5つの原則を守ることです。

原則1：ログを「テキスト」ではなく「データ」として扱う。構造化フォーマット（JSON）を標準とし、全てのログ出力が機械可読であることを保証します。これにより、人間が目視で確認するのではなく、ツールが自動で分析・集計できる基盤が整います
原則2：エラーは「種類」で分類し、レベルとステータスを分離する。前章で示したように、クライアント起因とサーバー起因を明確に区別し、それぞれに適切な監視ルートを割り当てます。この分離が、アラート疲れを防ぎ、真の障害に集中するための鍵です
原則3：機密情報は型システムで守る。Sensitiveラッパーやカスタム抽出器を活用し、ヒューマンエラーをコンパイルエラーに変換します。セキュリティは「後付けのフィルタ」ではなく「設計の一部」であるべきです
原則4：トレースIDを「空気」のように伝搬させる。リクエスト受信から外部呼び出し、非同期タスクに至るまで、全ての経路で同一のトレースIDが自動的に付与されるミドルウェア基盤を構築します。これにより、分散システムでもリクエスト単位の追跡が当たり前の操作になります
原則5：コストとトレードオフを事前に設計に組み込む。サンプリング戦略、動的レベル変更、ストレージ階層化を初回リリース時から実装し、「後で最適化」ではなく「最初から持続可能」な状態を目指します

これらの原則を実装する際に、完璧を求めるあまり過剰エンジニアリングに陥らないことも重要です。
たとえば、最初から全てのフィールドを完璧に構造化しようとするのではなく、必須フィールド（trace_id、method、path、status、level）だけを確実に出力し、それ以外は段階的に追加するアプローチが現実的です。
また、チームの運用ノウハウが蓄積されるにつれて、ログの粒度や保存期間は進化していくものですから、設計自体が固定的にならないよう、設定ファイルや環境変数で挙動を変えられる柔軟性を持たせてください。

さらに、ログ設計はコードだけの問題ではありません。
運用ダッシュボードの整備、アラートルールの定期見直し、ログを活用した障害訓練（ゲームデイ）の実施など、人間とプロセスを含めた総合的な可観測性戦略の一部として位置付ける必要があります。
いくら完璧なログが出ていても、それを活用する運用フローが整っていなければ、宝の持ち腐れです。

最後に、読者の皆さんに一つだけ問いかけたいと思います。
あなたのaxumアプリケーションのログは、「開発者のためのメモ」 ですか、それとも 「運用者のための羅針盤」 ですか。
もし前者なら、今すぐこの記事で示した解決策の一部でも実装に移してください。
後者を目指すなら、ログ設計を「付加機能」ではなく「コア機能」として位置付け、リソースと時間を適切に投資してください。

ログは、システムが本当に伝えたい「声」です。
その声を正しく聞き取り、解釈し、行動に移すための設計こそが、運用し続けられるシステムの真の基盤です。
この記事が、その一助となれば幸いです。