ログのデータモデル

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/logs/data-model/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

ステータス: Stable

これは、アプリケーションのログファイル、マシンが生成するイベント、システムログなど、さまざまな発生源のログを表現できるデータモデルとセマンティック規約です。既存のログフォーマットは、このデータモデルへ一意にマッピングできます。対象のログフォーマットが同等の能力を持つ限り、このデータモデルからの逆マッピングも可能です。

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

この提案は、Standalone Logのデータモデルを定義します。

設計上の注記

要件

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

• 既存のログフォーマットをこのデータモデルへ一意にマッピングできるべきです。任意のログフォーマットのログデータをこのデータモデルへ変換し、再び元に戻す変換は、理想的には同一のデータになるべきです。

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

• 任意のログフォーマットAのログデータをこのデータモデルへ変換し、続いてこのデータモデルから別のログフォーマットBへ変換する処理は、理想的には、ログフォーマットAからログフォーマットBへの妥当な直接変換と比べて劣らない、意味のあるログデータの変換にならなければなりません。

• データの保存や送信を必要とする具体的な実装において、このデータモデルを効率的に表現できるべきです。ここで主に問題にしているのは効率性の2つの側面です。シリアライズ・デシリアライズに要するCPU使用量と、シリアライズされた形式に必要な容量です。これは、データモデル自体よりもデータモデルの具体的な表現形式によって影響される間接的な要件ですが、念頭に置いておく価値があります。

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

• システムフォーマット。オペレーティングシステムが生成するログとイベントであり、私たちにはそのフォーマットを変更したり含まれる情報に影響を与える手段がありません（変更可能なアプリケーションがそのデータを生成している場合を除きます）。システムフォーマットの例はSyslogです。

• サードパーティアプリケーション。サードパーティのアプリケーションが生成するログとイベントです。フォーマットのカスタマイズなど、含まれる情報について一定の制御が可能な場合があります。例はApacheのログファイルです。

• ファーストパーティアプリケーション。私たち自身が開発し、ログとイベントの生成方法やログに含める情報について一定の制御を持つアプリケーションです。必要であれば、アプリケーションのソースコードを変更できる可能性があります。

Events

Eventは、LogRecordに対するOpenTelemetryの標準化されたフォーマットです。ログ向けに定義されたすべてのセマンティック規約は、Eventとしてフォーマットされるべきです（SHOULD）。Eventフォーマットの要件と詳細は、セマンティック規約にあります。

Eventは、OpenTelemetryの計装によって使われることを意図しています。すべてのLogRecordがEventとしてフォーマットされることは要件ではありません。

フィールドの種別

このデータモデルは、ログレコードの物理的なフォーマットやエンコーディングとは無関係に、ログレコードの論理モデルを定義します。各レコードには、次の2種類のフィールドが含まれます。

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

• Attribute Collectionとして格納されるフィールド。その値はAnyValueです。よく知られたフィールドのキーと値は、そのフィールドを扱うすべての関係者が同じ解釈を持てるように、キー名と可能な値についてのセマンティック規約に従います。ResourceフィールドとAttributesフィールドのセマンティック規約への参照や例については、付録Aを参照してください。

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

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

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

• 頻度の低いデータをAttribute Collectionで表現できる柔軟性。これには、標準化された意味を持つよく知られたデータと、アプリケーションがログに含めたい任意のカスタムデータの両方が含まれます。

このデータモデルを設計する際、トップレベルの名前付きフィールドをいつ使うべきかについて、次の考え方に従いました。

• そのフィールドが、すべてのレコードで必須であるか、よく知られたログ・イベントフォーマットで頻繁に存在する（Timestampなど）か、今後のロギングシステムのログレコードで頻繁に存在すると見込まれる（TraceIdなど）必要があります。

• そのフィールドの意味は、既知のすべてのログ・イベントフォーマットで同一であり、このデータモデルへ直接かつ一意にマッピングできなければなりません。

上記の両方の条件を満たすフィールドにのみ、レコードのトップレベル構造の中に場所を与えました。

Log and Event Record Definition

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

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

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

Field: Timestamp

型: Timestamp（UNIXエポックからのuint64ナノ秒）。

説明: イベント発生元のクロックで計測された、イベントが発生した時刻（すなわち発生元での時刻）。このフィールドはオプションであり、発生元のタイムスタンプが不明な場合は欠落することがあります。

Field: ObservedTimestamp

型: Timestamp（UNIXエポックからのuint64ナノ秒）。

説明: 収集システムによってイベントが観測された時刻。OpenTelemetry内で発生するイベント（例えばOpenTelemetry Logging SDKを使う場合）では、このタイムスタンプは通常生成時に設定され、Timestampと等しくなります。外部で発生し、OpenTelemetryによって収集されるイベント（例えばCollectorを使う場合）では、これはOpenTelemetryのコードのクロックで計測された、OpenTelemetryのコードがそのイベントを観測した時刻です。このフィールドは、OpenTelemetryによってイベントが観測された時点で設定されるべきです（SHOULD）。

OpenTelemetryのログデータを、タイムスタンプを1つしかサポートしないフォーマットへ変換する場合、あるいは内部でタイムスタンプを1つしかサポートしない受信者がOpenTelemetryのログデータを受信する場合は、次のロジックが推奨されます。

• Timestampが存在する場合はそれを使い、そうでない場合はObservedTimestampを使います。

Trace Context Fields

Field: TraceId

型: バイト列。

説明: W3C Trace Contextで定義されているリクエストのトレースID。リクエスト処理の一部であり、割り当てられたトレースIDを持つログに設定できます。このフィールドはオプションです。

Field: SpanId

型: バイト列。

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

Field: TraceFlags

型: バイト。

説明: W3C Trace Context仕様で定義されているトレースフラグ。本稿執筆時点では、この仕様はSAMPLEDフラグ1つのみを定義しています。このフィールドはオプションです。

重大度に関するフィールド

Field: SeverityText

型: string。

説明: 重大度テキスト（ログレベルとも呼ばれる）。これは、発生元で知られている重大度の元の文字列表現です。このフィールドが欠落しており、SeverityNumberが存在する場合、SeverityNumberに対応する短縮名を代わりに使ってよい（MAY）。このフィールドはオプションです。

Field: SeverityNumber

型: number。

説明: 本文書で説明されている値に正規化された、重大度の数値。このフィールドはオプションです。

SeverityNumberは整数です。数値が小さいほど重大度が低いイベント（デバッグイベントなど）に対応し、数値が大きいほど重大度が高いイベント（エラーやクリティカルなイベントなど）に対応します。

例えば、SeverityNumber=17は、SeverityNumber=20のエラーよりも重大度が低いエラーを表します。

次の表は、SeverityNumberの値の意味を定義します。

SeverityNumber=0は、値が未指定であることを表すために使ってよい（MAY）。

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=0が未指定の重大度を表すために使われている場合には、特別な扱いを与えてもよい（MAY）。

Field: Body

型: AnyValue。

説明: ログレコードのbodyを含む値。例えば、イベントを自由形式で記述する人間が読める文字列メッセージ（複数行を含む）であることも、他の値の配列やマップから構成される構造化データであることもあります。Bodyは、アプリケーションが発行する構造化ログの意味を保持するため、AnyValueをサポートしなければなりません（MUST）。同じ発生元から来るイベントの発生ごとに変化することがあります。このフィールドはオプションです。

Field: Resource

型: Resource。

説明: ログの発生源、すなわちリソースを記述します。同じイベント発生源から来るイベントが時間をおいて複数回発生しても、それらはすべて同じResourceの値を持ちます。例えば、そのレコードを発行しているアプリケーションや、アプリケーションが動作しているインフラストラクチャに関する情報を含められます。このデータモデルを表現するデータフォーマットは、同じ発生源から来るログレコードのバッチごとにResourceフィールドを1回だけ記録できるように設計してもかまいません。OpenTelemetryのリソースに関するセマンティック規約に従うべきです（SHOULD）。このフィールドはオプションです。

Field: InstrumentationScope

型: Instrumentation Scope。

説明: 計装スコープ。同じスコープから来るイベントが時間をおいて複数回発生しても、それらはすべて同じInstrumentationScopeの値を持ちます。このフィールドはオプションです。

Field: Attributes

型: Attribute Collection。

説明: 特定のイベント発生に関する追加情報。特定の発生源に対して固定されているResourceフィールドとは異なり、Attributesは同じ発生源から来るイベントの発生ごとに変化することがあります。（Trace Context Fields以外の）リクエストコンテキストに関する情報を含められます。このフィールドはオプションです。

エラーとエクセプション

ログレコードに関連付けられたエラーやエクセプションに関する追加情報は、レコードのAttributesセクションの構造化データに含めてよい（MAY）。含める場合は、OpenTelemetryのエクセプション関連属性のセマンティック規約に従わなければなりません（MUST）。

Field: EventName

型: string。

説明: Eventのクラス・種別を識別する名前。この名前は、（属性とbodyの両方を含む）イベントの構造を一意に識別すべきです（SHOULD）。空でないイベント名を持つログレコードはEventです。

ログレコードの例

ログレコードの例については、JSON File serializationを参照してください。

マッピングの例

ログフォーマットのマッピング例については、データモデル付録を参照してください。

参考文献

• ログのデータモデル OTEP 0097