OTEP-0097: ログのデータモデル

OpenTelemetryが理解するログレコードのためのデータモデルを導入します。

目次

• 動機
• 設計上の注記
  • 要件
  • フィールドの種類
• ログおよびイベントレコードの定義
  • フィールド: Timestamp
  • トレースコンテキストフィールド
    • フィールド: TraceId
    • フィールド: SpanId
    • フィールド: TraceFlags
  • 重大度フィールド
    • フィールド: SeverityText
    • フィールド: SeverityNumber
    • SeverityNumber のマッピング
    • 逆マッピング
    • エラーのセマンティクス
    • 重大度の表示
    • 重大度の比較
  • フィールド: Name
  • フィールド: Body
  • フィールド: Resource
  • フィールド: Attributes
• ログレコードの例
• OTEPの議論中に解決された疑問
  • TraceFlags 対 TraceParent と TraceState
  • 重大度フィールド
  • Timestamp の要件
  • セキュリティログ
• 代替設計
• 先行技術
  • RFC5424 Syslog
  • Fluentd Forwardプロトコルモデル
• 付録A. マッピング例
  • RFC5424 Syslog
  • Windowsイベントログ
  • SignalFxイベント
  • Splunk HEC
  • Log4j
  • Zap
  • Apache HTTPサーバーアクセスログ
  • CloudTrailログイベント
  • Google Cloud Logging
• Elastic Common Schema
• 付録B: SeverityNumber のマッピング例
• 参考文献

動機

これは、アプリケーションのログファイル、機械生成のイベント、システムログなど、さまざまなソースからのログを表現できるデータモデルとセマンティック規約の提案です。 既存のログ形式は、このデータモデルに一意にマッピングできます。 このデータモデルからの逆マッピングも、対象のログ形式が同等の機能を持つ範囲において可能です。

このデータモデルの目的は、ログレコードとは何か、ロギングシステムによって記録、転送、保存、解釈される必要があるデータは何かについて、共通の理解を持つことです。

この提案は、Standalone Log のためのデータモデルを定義します。 その関連する部分は、将来のOTEPでEmbedded Logのために採用されることがあります。

設計上の注記

要件

このデータモデルは、以下の要件を満たすように設計されました。

• 既存のログ形式をこのデータモデルに一意にマッピングできる必要があります。 任意のログ形式からこのデータモデルへ、そして元のログ形式に戻すログデータの変換は、理想的には同一のデータになるべきです。

• 他のログ形式からこのデータモデルへのマッピングは、意味的に妥当であるべきです。 このデータモデルは、既存のログ形式の特定の要素のセマンティクスを保持しなければなりません。

• 任意のログ形式Aからこのデータモデルへログデータを変換し、さらにこのデータモデルから別のログ形式Bへ変換した場合、理想的には、ログ形式Aからログ形式Bへの妥当な直接変換に劣らない意味のあるログデータの変換になるべきです。

• データを保存または送信する必要がある具体的な実装において、このデータモデルを効率的に表現できる必要があります。 私たちが主に関心を持つのは、効率性の2つの側面です。 シリアライズ／デシリアライズにかかるCPU使用率と、シリアライズされた形式での容量要件です。 これは、データモデルそのものではなくデータモデルの具体的な表現方法によって左右される間接的な要件ですが、それでも留意しておく価値があります。

このデータモデルは、次の3種類のログとイベントをうまく表現することを目指しています。

• システム形式です。 これらは、オペレーティングシステムによって生成される、私たちが制御できないログとイベントです。 （私たちが変更できるアプリケーションによってデータが生成される場合を除いて）形式を変更したり、含まれる情報に影響を与えたりすることはできません。 システム形式の例としてはSyslogがあります。

• サードパーティアプリケーションです。 これらはサードパーティのアプリケーションによって生成されます。 含まれる情報について、たとえば形式をカスタマイズするなど、ある程度の制御ができる場合があります。 例としてはApacheのログファイルがあります。

• ファーストパーティアプリケーションです。 これらは私たちが開発するアプリケーションであり、ログやイベントがどのように生成され、ログにどのような情報を含めるかについて、ある程度の制御ができます。 必要であれば、アプリケーションのソースコードを変更できる可能性が高いです。

フィールドの種類

このデータモデルは、（レコードの物理的な形式やエンコーディングに関わらず）ログレコードの論理モデルを定義します。 各レコードには、2種類のフィールドが含まれます。

• 特定の型と意味を持つ、名前付きのトップレベルフィールド。

• キーと値のペアのリストに格納されるフィールドで、さまざまな型の任意の値を含むことができます。 よく知られたフィールドのキーと値は、そのフィールドを扱うすべての関係者がデータについて同じ解釈を持てるように、キー名と可能な値についてのセマンティック規約に従います。 Resource フィールドと Attributes フィールドのセマンティック規約への参照、および付録Aの例を参照してください。

この2種類のフィールドを持つ理由は次のとおりです。

• 名前付きのトップレベルフィールドを効率的に表現できることです。 これらのフィールドはほぼ常に存在します（たとえば、フィールドが列挙されるもののワイヤー上では名前を持たないProtocol Buffersのようなエンコーディングを使用する場合など）。

• 名前付きフィールドの型を強制できることです。 これは、型チェックを行うコンパイル言語にとって非常に有用です。

• キーと値のペアのリストを介して、頻度の低いデータを表現できる柔軟性です。 これには、標準化されたセマンティクスを持つよく知られたデータだけでなく、アプリケーションがログに含めたい任意のカスタムデータも含まれます。

このデータモデルを設計する際、トップレベルの名前付きフィールドをいつ使用するかを決定するために、以下の考え方に従いました。

• そのフィールドは、すべてのレコードにとって必須であるか、よく知られたログおよびイベント形式で頻繁に存在する（Timestamp など）か、今後登場するロギングシステムのログレコードで頻繁に存在すると期待される（TraceId など）必要があります。

• そのフィールドのセマンティクスは、既知のすべてのログおよびイベント形式で同一であり、このデータモデルに直接かつ一意にマッピングできる必要があります。

上記の両方の条件が、そのフィールドにレコードのトップレベル構造の中の場所を与えるために必要でした。

ログおよびイベントレコードの定義

注記: 以下では型 any を使用します。 これはスカラー値（数値、文字列、真偽値）、または値の配列やマップになり得ます。 配列やマップの値については任意の深さのネストが許可されます（本質的にはJSONオブジェクトと同等のものを表現できます）。

付録Aには、既存のログ形式が以下で定義されるフィールドにどのようにマッピングされるかを示す多くの例が含まれています。 フィールドの意味について疑問がある場合は、これらの例を確認すると役立つでしょう。

ログレコードのフィールドの一覧は以下のとおりです。

以下は各フィールドの詳細な説明です。

フィールド: Timestamp

型: Timestamp、UNIXエポックからのナノ秒を表すuint64。

説明: 発生元のクロックで計測された、イベントが発生した時刻です。 このフィールドは省略可能で、タイムスタンプが不明な場合は存在しないことがあります。

トレースコンテキストフィールド

フィールド: TraceId

型: バイト列。

説明: W3C Trace Context で定義されているリクエストのトレースIDです。 リクエスト処理の一部であり、トレースIDが割り当てられているログに対して設定できます。 このフィールドは省略可能です。

フィールド: SpanId

型: バイト列。

説明: スパンIDです。 特定の処理スパンの一部であるログに対して設定できます。 SpanIdが存在する場合、TraceIdも存在すべきです（SHOULD）。 このフィールドは省略可能です。

フィールド: TraceFlags

型: バイト。

説明: W3C Trace Context 仕様で定義されているトレースフラグです。 本ドキュメントの執筆時点では、この仕様はSAMPLEDフラグという1つのフラグのみを定義しています。 このフィールドは省略可能です。

重大度フィールド

フィールド: SeverityText

型: 文字列。

説明: 重大度のテキストです（ログレベルとも呼ばれます）。 これは、発生元で知られているとおりの、重大度の元の文字列表現です。 このフィールドが存在せず SeverityNumber が存在する場合、SeverityNumber に対応する短い名前が代替として使用されることがあります。 このフィールドは省略可能です。

フィールド: SeverityNumber

型: 数値。

説明: このドキュメントで説明されている値に正規化された、重大度の数値です。 このフィールドは省略可能です。

SeverityNumber は整数値です。 小さい数値はより重大度の低いイベント（デバッグイベントなど）に対応し、大きい数値はより重大度の高いイベント（エラーやクリティカルなイベントなど）に対応します。 次の表は SeverityNumber の値の意味を定義します。

各範囲内で小さい数値は重要度の低い（重大度の低い）イベントを表します。 各範囲内で大きい数値は重要度の高い（重大度の高い）イベントを表します。 たとえば SeverityNumber=17 は、SeverityNumber=20 のエラーよりも重大度の低いエラーを表します。

SeverityNumber のマッピング

既存のロギングシステムおよび形式（略してソース形式）からのマッピングは、上の表で各範囲に与えられた意味に基づいて、その特定の形式の重大度（またはログレベル）がこのデータモデルの SeverityNumber にどのように対応するかを定義しなければなりません。

ソース形式にこの表の単一の範囲に一致する重大度が複数存在する場合、ソース形式の重大度は、そのソースの重大度がどれだけ重大（重要）であるかに応じて、その範囲内の数値が割り当てられなければなりません。

たとえば、ソース形式が「Error」と「Critical」をエラーイベントとして定義しており、「Critical」がより重要かつより重大な状況を表す場合、マッピングとして次の SeverityNumber の値を選択できます。「Error」→17、「Critical」→18。

ソース形式にその範囲の意味に一致する重大度が1つしかない場合は、その重大度にその範囲の最小値を割り当てることが推奨されます。

たとえば、ソース形式に「Informational」というログレベルがあり、類似の意味を持つ他のログレベルがない場合は、「Informational」に対して SeverityNumber=9 を使用することが推奨されます。

重大度やログレベルの概念を定義していないソース形式は、SeverityNumber フィールドと SeverityText フィールドを省略してもよい（MAY）です。 バックエンドとUIは、重大度情報が欠落しているログレコードを区別して表現してもよいですし、SeverityNumber フィールドと SeverityText フィールドが欠落しているログレコードを、あたかも SeverityNumber がINFO（数値の9）に設定されているかのように解釈してもよいです。

逆マッピング

SeverityNumber から特定の形式への逆マッピングを実行する際、その形式に対応するマッピングエントリが SeverityNumber に存在しない場合は、同じ重大度の範囲内にあり、数値的に最も近い対象の重大度を選択することが推奨されます。

たとえば、Zapには「Info」と呼ばれる、INFO範囲の重大度が1つしかありません。 逆マッピングを行う際、INFO範囲（数値9〜12）のすべての SeverityNumber の値は、Zapの「Info」レベルにマッピングされます。

エラーのセマンティクス

SeverityNumber が存在し、その値がERROR（数値17）以上である場合、そのログレコードはエラーの状況を表していることを示しています。 この事実をどのように利用するかを判断するのは、この値の読み手次第です（たとえば、UIはこのようなエラーを異なる色で表示したり、エラーのあるログレコードをすべて見つける機能を持たせたりしてもよいです）。

ログレコードがエラーのイベントを表しており、ソース形式が重大度やログレベルの概念を定義していない場合は、マッピング処理の間に SeverityNumber をERROR（数値17）に設定することが推奨されます。 ログレコードがエラーでないイベントを表す場合、SeverityNumber フィールドは省略してもよいですし、ERROR（数値17）未満の任意の数値に設定してもよいです。 この場合の推奨値はINFO（数値9）です。 マッピング例については付録Bを参照してください。

重大度の表示

次の表は、各 SeverityNumber の値に対する推奨される短縮名を定義します。 この短縮名は、たとえばUIで SeverityNumber を表現するために使用できます。

個々のログレコードを表示する際は、SeverityText と SeverityNumber の両方の値を表示することが推奨されます。 この場合に推奨される結合文字列は、短縮名で始まり、それに続けて括弧内に SeverityText を記載する形式です。

たとえば、「Informational」のSyslogレコードは INFO (Informational) として表示されます。 特定のログレコードで SeverityNumber は定義されているが SeverityText が存在しない場合は、短縮名のみを表示することが推奨されます（たとえば INFO）。

ドロップダウンリスト（または、取り得る値の集合を表現することを意図したその他のUI要素）を重大度の表現に使用する場合は、そのようなUI要素に短縮名を表示することが望ましいです。

たとえば、重大度でログレコードをフィルタリングできる重大度のドロップダウンリストは、システムに知られているすべての異なる SeverityText の値を列挙するドロップダウンリスト（要素数が多くなる可能性があり、しばしば大文字小文字や省略の違いだけで異なります。たとえば「Info」と「Information」）と比較して、SeverityNumber の短縮名を含む（そのため要素数の上限が限られる）方が、より使いやすい可能性が高いです。

重大度の比較

重大度が未満／超過の比較に関わる文脈では、SeverityNumber フィールドを使用すべきです。 SeverityNumber は、別の SeverityNumber や、1〜24の範囲の数値（または対応する短縮名）と比較できます。

重大度が等価または不等価の比較に使用される場合（たとえばUIのフィルターなど）、マッチングを行う際には SeverityText と SeverityNumber の短縮名の両方を使用することを試みることが推奨されます（つまり、これらいずれかのフィールドとの一致もマッチとみなすべきです）。 たとえば、SeverityText フィールドが「Informational」に等しく、SeverityNumber フィールドがINFOに等しいレコードがある場合、そのレコードについて severity=“Informational” と severity=“INFO” の両方の条件がTRUEになるようにすることが、ユーザー体験の観点からは望ましいでしょう。

フィールド: Name

型: 文字列。

説明: 変動する部分を含まない、短いイベント識別子です。 Name は何が起きたかを表します（たとえば「ProcessStarted」）。 50文字以内にすることが推奨されます。 一意性は一切保証されません。 通常、バックエンドでのフィルタリングやグルーピングの目的で使用されます。 このフィールドは省略可能です。

フィールド: Body

型: any。

説明: ログレコードの本文を含む値です（上記の any 型の説明を参照）。 たとえば、イベントを自由形式で説明する（複数行を含む）人間可読な文字列メッセージであってもよいですし、他の値の配列やマップで構成された構造化データであってもよいです。 同じソースから発生するイベントの発生ごとに異なる場合があります。 このフィールドは省略可能です。

フィールド: Resource

型: キーと値のペアのリスト。

説明: ログのソース、すなわちリソースを説明します。 各ペアの「キー」は string 型で、「値」は any 型です。 同じイベントソースから発生する複数回のイベントは時間をまたいで発生し得ますが、それらはすべて同じ Resource の値を持ちます。 たとえば、レコードを発行するアプリケーションに関する情報や、アプリケーションが実行されるインフラストラクチャに関する情報を含むことができます。 このデータモデルを表現するデータ形式は、同じソースから発生するログレコードのバッチごとに Resource フィールドを1回だけ記録できるように設計されることがあります。 リソースのセマンティック規約に従うべきです（SHOULD）。 このフィールドは省略可能です。

フィールド: Attributes

型: キーと値のペアのリスト。

説明: 特定のイベント発生に関する追加情報です。 各ペアの「キー」は string 型で、「値」は any 型です。 特定のソースに対して固定される Resource フィールドとは異なり、Attributes は同じソースから発生するイベントの発生ごとに異なる場合があります。 （TraceId/SpanId以外の）リクエストコンテキストに関する情報を含むことができます。 OpenTelemetryの属性のセマンティック規約に従うべきです（SHOULD）。 このフィールドは省略可能です。

ログレコードの例

以下は、ログレコードをJSONで表現する一つの可能な方法を示す例です。 これらはあくまでこのデータモデルの理解を助けるための例です。 これらの例を、このデータモデルをJSONで表現する_唯一の_方法として捉えないでください。

このドキュメントは、ログレコード表現の実際のエンコーディングと形式を定義しません。 形式の定義は、別のOTEPで行われます（たとえば、ログレコードはmsgpack、JSON、Protocol Bufferのメッセージなどとして表現される場合があります）。

例1

{
  "Timestamp": 1586960586000, // JSON needs to make a decision about
                              // how to represent nanoseconds.
  "Attributes": {
    "http.status_code": 500,
    "http.url": "http://example.com",
    "my.custom.application.tag": "hello",
  },
  "Resource": {
    "service.name": "donut_shop",
    "service.version": "semver:2.0.0",
    "k8s.pod.uid": "1138528c-c36e-11e9-a1a7-42010a800198",
  },
  "TraceId": "f4dbb3edd765f620", // this is a byte sequence
                                 // (hex-encoded in JSON)
  "SpanId": "43222c2d51a7abe3",
  "SeverityText": "INFO",
  "SeverityNumber": 9,
  "Body": "20200415T072306-0700 INFO I like donuts"
}

例2

{
  "Timestamp": 1586960586000,
  ...
  "Body": {
    "i": "am",
    "an": "event",
    "of": {
      "some": "complexity"
    }
  }
}

例3

{
   "Timestamp": 1586960586000,
   "Attributes":{
      "http.scheme":"https",
      "http.host":"donut.mycie.com",
      "http.target":"/order",
      "http.method":"post",
      "http.status_code":500,
      "http.flavor":"1.1",
      "http.user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36",
   }
}

OTEPの議論中に解決された疑問

これらは、OTEPのプルリクエストで議論され、解決された未解決の疑問でした。

TraceFlags 対 TraceParent と TraceState

質問: TraceFlags だけでなく、traceparent フィールドと tracestate フィールドを含むW3C Trace Context全体を保存すべきでしょうか。

回答: この議論では、traceparent と tracestate が必要であるという証拠は見つかりませんでした。

重大度フィールド

質問: SeverityText/SeverityNumber フィールドの設計は十分に優れているでしょうか。

回答: 議論の結果、この設計は妥当であることが示されました。

Timestamp の要件

質問: この提案の初期の草稿では、Timestamp は単調増加でNTP同期されたソースから設定されるべきであると規定されていました。 混乱を避けるため、この要件は削除しました。 タイムスタンプのソースについて何らかの要件が必要でしょうか。

回答: 議論の結果、そのような要件を規定することはデータモデルの責務ではないことが明らかになりました。

セキュリティログ

質問: セキュリティログに対して特別な扱いが必要でしょうか。

回答: このOTEPでの議論では、データモデルの提案という文脈においてセキュリティログを特別に扱う必要性は見出されませんでした。

代替設計

エンベロープ方式を用いた代替設計も検討しましたが、総合的にこちらの設計より優れているとは判断しませんでした。

先行技術

RFC5424 Syslog

RFC5424 は、構造化されたログデータの形式とプロトコルを定義しています。 このプロトコルは広く普及していますが（残念ながら多くの実装は構造化データの推奨事項に従っていません）、Syslogをデータモデルの有力な候補としない、いくつかの欠点があります。

• 構造化された属性を許容する一方で、メッセージの本文は文字列のみです。

• 重大度は8つの数値にハードコードされており、カスタムの重大度テキストを許容しません。

• 構造化データは任意のネストを許容せず、2階層のみです。

• データソース（すなわちリソース）を指定するための明確な独立した場所がありません。 この目的を限定的に果たすハードコードされたフィールドがいくつか存在します（HOSTNAME、APP-NAME、FACILITY）。

Fluentd Forwardプロトコルモデル

Forwardプロトコル は、タイムスタンプ付きレコードとしてログEntryの概念を定義しています。 このレコードは、タグと任意のキーと値のペアのマップという2つの要素で構成されます。

このモデルは、あらゆるログレコードを表現できるほど汎用的です。 しかし、いくつかの欠点があります。

• レコードのすべての属性は、（タグとタイムスタンプを除いて）汎用的なキーと値のペアで表現されます。 これは、最適化の機会を逃しています（設計上の注記を参照）。

• データソース（すなわちリソース）を指定するための明確な独立した場所がありません。

• キーがどのように命名されるべきか、どのような値が期待されるかについての言及がありません。 命名規則やキーと値のペアの標準化が欠如していることが、相互運用性を難しくしています。

付録A. マッピング例

このセクションには、他のイベントおよびログの形式をこのデータモデルにマッピングする例が含まれています。

RFC5424 Syslog

Windowsイベントログ

SignalFxイベント

Splunk HEC

Log4j

Zap

Apache HTTPサーバーアクセスログ

CloudTrailログイベント

Google Cloud Logging

Elastic Common Schema

* まだECSに正式に組み込まれていません。

** OpenTelemetryのリソースのセマンティック規約に存在しないリソースです。

これは、最も関連性の高いフィールドを抜粋したものです。 網羅的な一覧については完全なリファレンスを参照してください。

付録B: SeverityNumber のマッピング例

参考文献

• データモデルの草稿の議論