はじめに

Technology Innovation Groupの八木です。

フューチャー社内の有志メンバーでログ設計ガイドラインを作成し公開しました！

ログは、システムの稼働状況を可視化し、トラブルが発生した際に迅速に原因特定するための生命線になります。しかし、その重要性の一方で、プロジェクトごとに設計がバラバラになりがちだったり、とりあえず標準出力しているだけになっていたりと、十分に活用しきれていないケースも多く見受けられます。

本記事では、今回公開したログ設計ガイドラインの背景や、現場で役立つ設計のポイントを抜粋してご紹介します。

ガイドライン作成のモチベーション

これまで、ログ設計は個々のエンジニアの経験則や、プロジェクトごとの慣習に委ねられることが多くありました。しかし、システムが複雑化し、マイクロサービスやクラウドネイティブな構成が当たり前になった現代において、ログの役割は「単なるデバッグ用のテキスト」から「オブザーバビリティ（可観測性）の基盤」へと進化しています。

ログ設計が不十分だと、以下のような課題が発生し得ます。

原因追求ができない: 必要な情報（トレースIDやユーザーIDなど）が不足しており、エラーの原因を追えない
横断的な集計ができない: フォーマットがバラバラで、CloudWatch Logs や Datadog などのツールで検索・集計がしにくい
コストと性能: 無意味なログが大量に出力され、ストレージ費用を圧迫したり、アプリケーションの性能を劣化させる

ガイドラインのポイント紹介

ログ設計ガイドラインでは、アプリケーションログを対象に命名規則から出力項目、セキュリティ、コストまで幅広くカバーしています。その中から主なトピックをいくつかピックアップします。

1. ログキー命名規則

特定のプラットフォーム（AWS/GCP）やSaaS（Datadog/New Relic）に依存しすぎない移植性の高いログにするため、標準仕様といえるOpenTelemetry (OTel) Semantic ConventionsやElastic Common Schema (ECS)をベースにした命名規則を推奨しています。

標準化のメリット: timestamp や @timestamp といった些細な表記揺れを排除し、ログ解析ツールで利用しやすくする
共通スキーマ: timestamp, severity.text, message, trace_id といった、どのログにも含めるべき必須項目を定義する

2. コンテキスト情報の付与

エラーが発生した際、「何が起きたか（メッセージ）」だけでは原因特定に至らないことが多々あります。「どのユーザーが」「どのリクエストで」起こしたのかというコンテキスト情報を付与することで、調査の解像度を高めます。

トレースID：マイクロサービスなどの分散システムにおいて、サービス間をまたぐ一連の処理を紐付けるためのIDです。これを全ログに含めることで、点在するログを追跡可能にします
HTTP/DBコンテキスト：リクエストメソッドやパス、ステータスコード、DBクエリの実行時間といった情報を「拡張スキーマ」として定義します。これにより、「特定のAPIだけレスポンスが遅い」「特定のクエリでエラーが頻発している」といった多角的な分析が可能になります

3. 出力ルールとメッセージの書き方

意外と疎かにされがちなログメッセージ自体の書き方について紹介しています。

事実とデータの分離: メッセージ内に可変値を入れる（例. User login failed: {userId}）ではなく、メッセージ自体は User login failed と固定し、user.id を構造化データの別フィールドとして分離します。これにより、ログの集計が楽になります
メッセージコードの導入: エラーログを運用者が参照する「運用手順書（障害対応マニュアル）」と紐づけるために、一意のメッセージコード（例：E001）を付与するパターンを紹介しています
「通知フラグ」の考え方: 全てのエラーを即座に通報するのではなく、ログに「通知の是非」のフラグを持たせる設計についても言及しています

4. セキュリティと機密情報

ログに含めてはいけない情報（個人情報、パスワード、認証トークン等）の管理と、誤って出力しないためのマスキングの考え方についてもガイドを設けています。

ガイドライン活動後の感想

私自身、これまでログ設計についてあまり時間をかける機会がありませんでした。しかし、今回のガイドライン活動を通して、今まで慣習として従っていたキー名や構造にもOTel Semantic Conventionsといった標準が存在することや、効率的に開発/運用するための考え方を知ることができました。

加えて、活動内でシニアな方々と議論することで、なぜそのような設計なのかというWhyの部分も学ぶことができたことも大きな収穫でした。

今後は自らのプロジェクトでこれを実践し、開発/運用者が幸せになれるシステム作りに貢献したいと思います。

おわりに

ログは「出力して終わり」ではなく、「トラブル時にいかに迅速に原因を特定できるか」という運用のための資産になります。

今回公開したガイドラインが、皆さんのプロジェクトにおける保守・運用しやすいシステム作りの一助となれば幸いです。

また、ガイドラインを読んでのフィードバックやGitHubでのIssue/PRもお待ちしております！

ログ設計ガイドライン:

https://future-architect.github.io/arch-guidelines/documents/forLog/log_guidelines.html

ログ設計ガイドラインを公開しました