LASSIC Media らしくメディア
構造化ログ基盤の導入を外注で進める
LASSIC IT事業部｜元請（プライムベンダー）としてシステム保守・運用を受託
この記事のポイント
- 構造化ログとテキストログの違いと、検索・集計・相関付けにおける限界を整理します。
- 共通フィールド設計・相関ID伝播・秘匿情報のマスキングなど、構造化ログ設計の要点を解説します。
- 収集パイプラインの構成とログレベル運用、外注に委託する範囲の考え方を紹介します。
目次
構造化ログとは——テキストログとの違い
構造化ログ（structured logging）とは、アプリケーションが出力するログをJSON等の一定のスキーマを持つ形式で記録し、タイムスタンプ・ログレベル・トレースIDといったフィールドを個別に検索・集計できるようにする手法を指します。OpenTelemetryのドキュメントでも、ログは「タイムスタンプ付きのテキストレコードであり、構造化（推奨）または非構造化のいずれかで、任意のメタデータを伴う」と定義され、下流のシステムが安定して解析・解釈できる一貫したスキーマを持つことが推奨されています*1。
従来型のテキストログは「2026-07-01 10:23:11 ERROR order failed for user 123」のように人間が読む前提の自由記述で出力されます。これに対し構造化ログは、同じ内容を{"timestamp":"...","level":"error","message":"order failed","user_id":"123","trace_id":"..."}のようにフィールド単位で持たせる点が異なります。The Twelve-Factor Appの「XI. Logs」でも、ログは「実行中のアプリケーションおよび支援サービスの出力ストリームから収集された、時間順に並んだイベントのストリーム」と位置づけられ、アプリ自身はログファイルの管理やルーティング先を意識せず、標準出力（stdout）にイベントストリームとして出力すべきだとされています*2。構造化ログはこの原則の上に、フィールドの一貫したスキーマを載せる考え方だといえます。
grepベースのテキストログが抱える限界
自由記述のテキストログは、サーバー1台・機能が単純なうちはgrepやテキストエディタでの目視確認でも運用できます。しかし規模が大きくなるほど、以下の3つの限界が表面化します。
第一に、フィールド単位の検索や集計ができません。「特定ユーザーIDのエラーだけを抽出する」「レスポンスタイムの分布を集計する」といった操作は、テキストログでは正規表現によるパターンマッチに頼ることになり、ログの書式が少しでも変わると集計が壊れます。
第二に、複数サービスにまたがるリクエストの追跡が難しくなります。マイクロサービスやAPI連携が増えると、1つのユーザー操作が複数のプロセス・サービスをまたいで処理されますが、共通の識別子がなければ「どのログがどのリクエストに属するか」を突き合わせる手段がありません。OpenTelemetryでは、ログレコードにTraceId・SpanIdを持たせることで、既存のログを稼働中のトレース・スパンと自動的に相関付ける仕組みが提供されています*1。
第三に、ログの保存・転送先をアプリ自身が管理する設計は、実行環境の変化に弱くなります。The Twelve-Factor Appは、アプリケーションが出力ストリームの保存先やルーティングに関与すべきではないと明記しており*2、この原則に反してアプリ内でログファイルの書き出し先を直接制御している構成は、収集基盤の入れ替えやスケールアウト時に修正コストが生じやすくなります。
構造化ログ設計の要点：共通フィールド・相関ID・マスキング
構造化ログ基盤の設計でまず決めるべきは、全サービス共通で持たせるフィールドのスキーマです。OpenTelemetryのログモデルでは、タイムスタンプ（Timestamp／ObservedTimestamp）、重大度（SeverityText／SeverityNumber）、本文（Body）、トレース情報（TraceId／SpanId／TraceFlags）、任意の追加属性（Attributes）が主要な構成要素として定義されています*1。自社でログ基盤を設計する場合も、この構成を土台に「サービス名」「環境（本番／検証）」「リクエストID」といった項目を共通フィールドとして追加するのが実務上の出発点になります。
次に重要なのが相関ID（correlation ID）の伝播です。1つのユーザー操作が複数サービスを経由する場合、リクエストの入口で払い出した識別子をヘッダーやコンテキストで下流のサービスまで引き継ぎ、各サービスのログに同じ値を記録する必要があります。OpenTelemetryが提供するトレースコンテキストとの自動相関の仕組み*1は、この相関ID伝播をアプリケーションコードの改修を抑えつつ実現する代表的な方法の一つです。
加えて、ログに含める情報の範囲も設計段階で線引きが必要です。氏名・メールアドレス・カード番号の下4桁を除く番号といった個人情報や認証情報をログにそのまま出力すると、ログ集約基盤自体が情報漏えいのリスク要因になります。マスキング（伏せ字化）やハッシュ化の対象フィールドをあらかじめ定義し、アプリケーション側のログ出力処理に組み込んでおくことが、構造化ログ設計の要点の一つです。
収集パイプラインの設計：収集・格納・検索とコスト管理
構造化ログを生かすには、出力したログを集約し検索可能な状態にする収集パイプラインが必要です。一般的な構成は、各サーバー・コンテナに配置した収集エージェントがログを収集し、ログ集約基盤（検索エンジンやログ管理サービス）に転送・格納し、そこに対してフィールド検索や集計クエリを実行する流れになります。The Twelve-Factor Appが示す「アプリはstdoutに出すだけで、収集・保存は実行環境側の責務」という原則*2は、この収集エージェント以降の工程を実行基盤側に切り出す設計とも整合します。
収集パイプラインの設計では、ログレベルの運用ルールも欠かせません。全ログをDEBUGレベルのまま集約基盤に送り続けると、検索性が落ちるだけでなく、格納コストや検索性能にも影響します。本番環境ではINFO以上を基本としつつ、障害調査時に一時的にDEBUGへ切り替えられる仕組みを用意する、といった運用ルールをあらかじめ決めておく必要があります。
保持期間の設計も重要な論点です。障害調査や監査対応に必要な期間はログを検索可能な状態で保持し、それを超えた期間は低コストなアーカイブストレージへ移す、あるいは削除するといった階層化を行うことで、格納コストを抑えながら必要な期間の追跡可能性を確保できます。保持期間や階層化の具体的な設計は、扱うログの種類（アプリケーションログ／アクセスログ／監査ログ）や社内の規程によって異なるため、要件を整理したうえで決める必要があります。
ログ基盤を内製構築する難易度
構造化ログ基盤を内製で構築するには、複数の専門領域にまたがる知識が必要になります。具体的には、アプリケーション側のログ出力形式の統一設計、収集エージェントの選定・設定、ログ集約基盤の構築・運用、検索クエリの設計、そしてマスキングやアクセス権限といったセキュリティ設計です。これらを1人の担当者がすべて把握して運用し続けるのは負担が大きく、構築後も収集量の増減に応じたチューニングや、サービス追加時のスキーマ拡張といった継続的な保守が発生します。
ログ設計を誤ると、後から修正するコストも大きくなります。共通フィールドの命名規則を途中で変更すると、既存の検索クエリやダッシュボードがすべて書き換えになり、過去ログとの整合性も失われます。相関IDの伝播漏れがあると、障害発生時に「どのサービスで何が起きたか」をログだけでは追跡できず、原因調査の時間が長引く要因になります。こうした手戻りの大きさが、内製構築の難易度を高めている実態です。
外注の委託範囲と発注準備で整理すべきこと
ログ基盤の構築を外部パートナーに委託する場合、発注前に委託範囲を明確にしておくことが、期待していた成果物とのずれを防ぐうえで重要です。委託範囲は大きく「設計」「実装」「運用」の3段階に分けて整理できます。
| 委託範囲 | 主な作業内容 | 発注前に準備すべき情報 |
|---|---|---|
| ログ設計 | 共通フィールドのスキーマ策定。 相関ID伝播方式の設計。 マスキング対象項目の定義。 |
対象サービス一覧と技術スタック。 既存ログの出力状況（形式・出力量の目安）。 |
| 収集パイプライン実装 | 収集エージェントの導入・設定。 ログ集約基盤への転送設定。 ログレベル運用ルールの実装。 |
既存のインフラ構成（オンプレミス／クラウド）。 想定ログ量とピーク時の見込み。 |
| 運用・保守 | 保持期間・アーカイブ方針の運用。 検索クエリ・ダッシュボードの保守。 収集障害時の一次対応。 |
保持期間の社内規程・監査要件。 障害対応の連絡フロー・エスカレーション先。 |
発注準備の段階では、まず自社のどのサービスがどの形式でログを出力しているかを棚卸しすることが出発点になります。すでにJSON形式で出力しているサービスと、自由記述のテキストログのままのサービスが混在している場合、統一のスキーマに揃える移行作業がどの範囲まで必要かを外部パートナーと事前にすり合わせておく必要があります。あわせて、個人情報や認証情報を含むログの有無を洗い出し、マスキングが必要な項目をリスト化しておくと、設計フェーズの手戻りを減らせます。
委託先を評価する際は、OpenTelemetryのような業界標準の枠組みに沿った設計を提案できるか、既存システムへの影響を抑えた段階的な移行計画を示せるかを確認するとよいでしょう。ログ基盤は一度構築して終わりではなく、サービスの追加・変更に合わせてスキーマや収集設定を継続的に見直す必要があるため、運用フェーズまで見据えた体制を持つパートナーかどうかも判断材料になります。
まとめ：構造化ログ基盤導入の3つの判断軸
本稿では、構造化ログ基盤の導入を外注で進める際に押さえるべき論点を整理しました。要点を3つに集約すると次の通りです。第一に、構造化ログはテキストログのフィールド検索・相関付けの限界を解消する手段であり、OpenTelemetryが示す共通フィールドの考え方が設計の土台になります。第二に、共通フィールド設計・相関ID伝播・マスキングという3つの設計要素と、収集・格納・検索という収集パイプラインの構成を分けて検討する必要があります。第三に、外注時は「設計」「実装」「運用」の委託範囲を明確にし、既存ログの棚卸しとマスキング対象の洗い出しを発注前に済ませておくことが、後工程の手戻りを防ぎます。
よくある質問
構造化ログとログ監視・オブザーバビリティ基盤はどう違いますか。
構造化ログはログという1種類のデータをJSON等のスキーマで整理する手法です。オブザーバビリティは、メトリクス・ログ・トレースの3種類のデータを組み合わせてシステムの状態を把握する広い概念であり、構造化ログはそのうちログの柱を支える取り組みの一つに位置づけられます。
既存のテキストログを構造化ログに移行する際、全サービスを一度に切り替える必要がありますか。
一度に全サービスを切り替える必要はありません。優先度の高いサービスやトラブルの多いサービスから段階的にJSON出力へ移行し、共通フィールドのスキーマを揃えていく進め方が実務上は取られています。移行期間中はテキストログと構造化ログが混在する前提で収集パイプライン側を設計しておくと、切り替えの負担を抑えられます。
相関IDはどの単位で発行するのが基本ですか。
リクエストの入口となるサービス（APIゲートウェイやフロントのサーバーなど)で1つのユーザー操作ごとに発行し、下流のサービス呼び出しにヘッダーやコンテキストで引き継ぐのが基本です。OpenTelemetryではトレースIDとスパンIDによってこの相関を仕組み化しており*1、既存の分散トレーシングの仕組みがある場合はそのIDを流用する方法もあります。
ログの保持期間はどのように決めればよいですか。
障害調査に必要な直近の期間は検索可能な状態で保持し、それ以降は低コストなアーカイブストレージに移す、または削除するという階層化が基本的な考え方です。具体的な年数は監査要件や業界の規程によって異なるため、社内の情報管理規程やコンプライアンス部門と確認したうえで設計する必要があります。
ログ基盤の構築を外注する場合、契約形態はどのようなものが一般的ですか。
設計・実装フェーズは成果物を定義しやすいため請負契約、運用・保守フェーズは継続的な対応が中心になるため準委任契約が選ばれることが多いです。委託範囲を「設計」「実装」「運用」に分けて整理しておくと、フェーズごとに適した契約形態を検討しやすくなります。
著者：テレリモ総研編集部 鈴木 亮佑
ご不明な点はお問い合わせフォームからもご連絡いただけます。
- *1 出典：OpenTelemetry「Logs」（https://opentelemetry.io/docs/concepts/signals/logs/）
- *2 出典：The Twelve-Factor App「XI. Logs」（https://12factor.net/logs）
