> Source: https://www.ymotongpoo.com/works/oteps/logs/otep-0097/ # OTEP-0097: ログのデータモデル OpenTelemetryが理解するログレコードのためのデータモデルを導入します。 ## 目次 {#table-of-contents} * [動機](#motivation) * [設計上の注記](#design-notes) * [要件](#requirements) * [フィールドの種類](#field-kinds) * [ログおよびイベントレコードの定義](#log-and-event-record-definition) * [フィールド: `Timestamp`](#field-timestamp) * [トレースコンテキストフィールド](#trace-context-fields) * [フィールド: `TraceId`](#field-traceid) * [フィールド: `SpanId`](#field-spanid) * [フィールド: `TraceFlags`](#field-traceflags) * [重大度フィールド](#severity-fields) * [フィールド: `SeverityText`](#field-severitytext) * [フィールド: `SeverityNumber`](#field-severitynumber) * [`SeverityNumber` のマッピング](#mapping-of-severitynumber) * [逆マッピング](#reverse-mapping) * [エラーのセマンティクス](#error-semantics) * [重大度の表示](#displaying-severity) * [重大度の比較](#comparing-severity) * [フィールド: `Name`](#field-name) * [フィールド: `Body`](#field-body) * [フィールド: `Resource`](#field-resource) * [フィールド: `Attributes`](#field-attributes) * [ログレコードの例](#example-log-records) * [OTEPの議論中に解決された疑問](#questions-resolved-during-otep-discussion) * [`TraceFlags` 対 `TraceParent` と `TraceState`](#traceflags-vs-traceparent-and-tracestate) * [重大度フィールド](#severity-fields-1) * [`Timestamp` の要件](#timestamp-requirements) * [セキュリティログ](#security-logs) * [代替設計](#alternate-design) * [先行技術](#prior-art) * [RFC5424 Syslog](#rfc5424-syslog) * [Fluentd Forwardプロトコルモデル](#fluentd-forward-protocol-model) * [付録A. マッピング例](#appendix-a-example-mappings) * [RFC5424 Syslog](#rfc5424-syslog-1) * [Windowsイベントログ](#windows-event-log) * [SignalFxイベント](#signalfx-events) * [Splunk HEC](#splunk-hec) * [Log4j](#log4j) * [Zap](#zap) * [Apache HTTPサーバーアクセスログ](#apache-http-server-access-log) * [CloudTrailログイベント](#cloudtrail-log-event) * [Google Cloud Logging](#google-cloud-logging) * [Elastic Common Schema](#elastic-common-schema) * [付録B: `SeverityNumber` のマッピング例](#appendix-b-severitynumber-example-mappings) * [参考文献](#references) ## 動機 {#motivation} これは、アプリケーションのログファイル、機械生成のイベント、システムログなど、さまざまなソースからのログを表現できるデータモデルとセマンティック規約の提案です。 既存のログ形式は、このデータモデルに一意にマッピングできます。 このデータモデルからの逆マッピングも、対象のログ形式が同等の機能を持つ範囲において可能です。 このデータモデルの目的は、ログレコードとは何か、ロギングシステムによって記録、転送、保存、解釈される必要があるデータは何かについて、共通の理解を持つことです。 この提案は、[Standalone Log](https://github.com/open-telemetry/oteps/blob/main/text/logs/0091-logs-vocabulary.md#standalone-log) のためのデータモデルを定義します。 その関連する部分は、将来のOTEPで[Embedded Log](https://github.com/open-telemetry/oteps/blob/main/text/logs/0091-logs-vocabulary.md#embedded-log)のために採用されることがあります。 ## 設計上の注記 {#design-notes} ### 要件 {#requirements} このデータモデルは、以下の要件を満たすように設計されました。 - 既存のログ形式をこのデータモデルに一意にマッピングできる必要があります。 任意のログ形式からこのデータモデルへ、そして元のログ形式に戻すログデータの変換は、理想的には同一のデータになるべきです。 - 他のログ形式からこのデータモデルへのマッピングは、意味的に妥当であるべきです。 このデータモデルは、既存のログ形式の特定の要素のセマンティクスを保持しなければなりません。 - 任意のログ形式Aからこのデータモデルへログデータを変換し、さらにこのデータモデルから別のログ形式Bへ変換した場合、理想的には、ログ形式Aからログ形式Bへの妥当な直接変換に劣らない意味のあるログデータの変換になるべきです。 - データを保存または送信する必要がある具体的な実装において、このデータモデルを効率的に表現できる必要があります。 私たちが主に関心を持つのは、効率性の2つの側面です。 シリアライズ／デシリアライズにかかるCPU使用率と、シリアライズされた形式での容量要件です。 これは、データモデルそのものではなくデータモデルの具体的な表現方法によって左右される間接的な要件ですが、それでも留意しておく価値があります。 このデータモデルは、次の3種類のログとイベントをうまく表現することを目指しています。 - システム形式です。 これらは、オペレーティングシステムによって生成される、私たちが制御できないログとイベントです。 （私たちが変更できるアプリケーションによってデータが生成される場合を除いて）形式を変更したり、含まれる情報に影響を与えたりすることはできません。 システム形式の例としてはSyslogがあります。 - サードパーティアプリケーションです。 これらはサードパーティのアプリケーションによって生成されます。 含まれる情報について、たとえば形式をカスタマイズするなど、ある程度の制御ができる場合があります。 例としてはApacheのログファイルがあります。 - ファーストパーティアプリケーションです。 これらは私たちが開発するアプリケーションであり、ログやイベントがどのように生成され、ログにどのような情報を含めるかについて、ある程度の制御ができます。 必要であれば、アプリケーションのソースコードを変更できる可能性が高いです。 ### フィールドの種類 {#field-kinds} このデータモデルは、（レコードの物理的な形式やエンコーディングに関わらず）ログレコードの論理モデルを定義します。 各レコードには、2種類のフィールドが含まれます。 - 特定の型と意味を持つ、名前付きのトップレベルフィールド。 - キーと値のペアのリストに格納されるフィールドで、さまざまな型の任意の値を含むことができます。 よく知られたフィールドのキーと値は、そのフィールドを扱うすべての関係者がデータについて同じ解釈を持てるように、キー名と可能な値についてのセマンティック規約に従います。 `Resource` フィールドと `Attributes` フィールドのセマンティック規約への参照、および[付録A](#appendix-a-example-mappings)の例を参照してください。 この2種類のフィールドを持つ理由は次のとおりです。 - 名前付きのトップレベルフィールドを効率的に表現できることです。 これらのフィールドはほぼ常に存在します（たとえば、フィールドが列挙されるもののワイヤー上では名前を持たないProtocol Buffersのようなエンコーディングを使用する場合など）。 - 名前付きフィールドの型を強制できることです。 これは、型チェックを行うコンパイル言語にとって非常に有用です。 - キーと値のペアのリストを介して、頻度の低いデータを表現できる柔軟性です。 これには、標準化されたセマンティクスを持つよく知られたデータだけでなく、アプリケーションがログに含めたい任意のカスタムデータも含まれます。 このデータモデルを設計する際、トップレベルの名前付きフィールドをいつ使用するかを決定するために、以下の考え方に従いました。 - そのフィールドは、すべてのレコードにとって必須であるか、よく知られたログおよびイベント形式で頻繁に存在する（`Timestamp` など）か、今後登場するロギングシステムのログレコードで頻繁に存在すると期待される（`TraceId` など）必要があります。 - そのフィールドのセマンティクスは、既知のすべてのログおよびイベント形式で同一であり、このデータモデルに直接かつ一意にマッピングできる必要があります。 上記の両方の条件が、そのフィールドにレコードのトップレベル構造の中の場所を与えるために必要でした。 ## ログおよびイベントレコードの定義 {#log-and-event-record-definition} 注記: 以下では型 `any` を使用します。 これはスカラー値（数値、文字列、真偽値）、または値の配列やマップになり得ます。 配列やマップの値については任意の深さのネストが許可されます（本質的にはJSONオブジェクトと同等のものを表現できます）。 [付録A](#appendix-a-example-mappings)には、既存のログ形式が以下で定義されるフィールドにどのようにマッピングされるかを示す多くの例が含まれています。 フィールドの意味について疑問がある場合は、これらの例を確認すると役立つでしょう。 ログレコードのフィールドの一覧は以下のとおりです。 | Field Name | Description | | -------------- | -------------------------------------------- | | Timestamp | イベントが発生した時刻です。 | | TraceId | リクエストのトレースIDです。 | | SpanId | リクエストのスパンIDです。 | | TraceFlags | W3Cのトレースフラグです。 | | SeverityText | 重大度のテキストです（ログレベルとも呼ばれます）。 | | SeverityNumber | 重大度の数値です。 | | Name | 短いイベント識別子です。 | | Body | ログレコードの本文です。 | | Resource | ログのソースを説明します。 | | Attributes | イベントに関する追加情報です。 | 以下は各フィールドの詳細な説明です。 ### フィールド: `Timestamp` {#field-timestamp} 型: Timestamp、UNIXエポックからのナノ秒を表すuint64。 説明: 発生元のクロックで計測された、イベントが発生した時刻です。 このフィールドは省略可能で、タイムスタンプが不明な場合は存在しないことがあります。 ### トレースコンテキストフィールド {#trace-context-fields} #### フィールド: `TraceId` {#field-traceid} 型: バイト列。 説明: [W3C Trace Context](https://www.w3.org/TR/trace-context/#trace-id) で定義されているリクエストのトレースIDです。 リクエスト処理の一部であり、トレースIDが割り当てられているログに対して設定できます。 このフィールドは省略可能です。 #### フィールド: `SpanId` {#field-spanid} 型: バイト列。 説明: スパンIDです。 特定の処理スパンの一部であるログに対して設定できます。 SpanIdが存在する場合、TraceIdも存在すべきです（SHOULD）。 このフィールドは省略可能です。 #### フィールド: `TraceFlags` {#field-traceflags} 型: バイト。 説明: [W3C Trace Context](https://www.w3.org/TR/trace-context/#trace-flags) 仕様で定義されているトレースフラグです。 本ドキュメントの執筆時点では、この仕様はSAMPLEDフラグという1つのフラグのみを定義しています。 このフィールドは省略可能です。 ### 重大度フィールド {#severity-fields} #### フィールド: `SeverityText` {#field-severitytext} 型: 文字列。 説明: 重大度のテキストです（ログレベルとも呼ばれます）。 これは、発生元で知られているとおりの、重大度の元の文字列表現です。 このフィールドが存在せず `SeverityNumber` が存在する場合、`SeverityNumber` に対応する短い名前が代替として使用されることがあります。 このフィールドは省略可能です。 #### フィールド: `SeverityNumber` {#field-severitynumber} 型: 数値。 説明: このドキュメントで説明されている値に正規化された、重大度の数値です。 このフィールドは省略可能です。 `SeverityNumber` は整数値です。 小さい数値はより重大度の低いイベント（デバッグイベントなど）に対応し、大きい数値はより重大度の高いイベント（エラーやクリティカルなイベントなど）に対応します。 次の表は `SeverityNumber` の値の意味を定義します。 | SeverityNumber range | Range name | Meaning | | -------------------- | ---------- | ---------------------------------------------------------------------------------------| | 1-4 | TRACE | きめ細かいデバッグイベントです。デフォルト設定では通常無効になっています。 | | 5-8 | DEBUG | デバッグイベントです。 | | 9-12 | INFO | 情報イベントです。イベントが発生したことを示します。 | | 13-16 | WARN | 警告イベントです。エラーではありませんが、情報イベントよりも重要である可能性が高いです。| | 17-20 | ERROR | エラーイベントです。何か問題が発生しました。 | | 21-24 | FATAL | アプリケーションやシステムのクラッシュなど、致命的なエラーです。 | 各範囲内で小さい数値は重要度の低い（重大度の低い）イベントを表します。 各範囲内で大きい数値は重要度の高い（重大度の高い）イベントを表します。 たとえば `SeverityNumber=17` は、`SeverityNumber=20` のエラーよりも重大度の低いエラーを表します。 #### `SeverityNumber` のマッピング {#mapping-of-severitynumber} 既存のロギングシステムおよび形式（略して**ソース形式**）からのマッピングは、上の表で各範囲に与えられた意味に基づいて、その特定の形式の重大度（またはログレベル）がこのデータモデルの `SeverityNumber` にどのように対応するかを定義しなければなりません。 ソース形式にこの表の単一の範囲に一致する重大度が複数存在する場合、ソース形式の重大度は、そのソースの重大度がどれだけ重大（重要）であるかに応じて、その範囲内の数値が割り当てられなければなりません。 たとえば、ソース形式が「Error」と「Critical」をエラーイベントとして定義しており、「Critical」がより重要かつより重大な状況を表す場合、マッピングとして次の `SeverityNumber` の値を選択できます。「Error」→17、「Critical」→18。 ソース形式にその範囲の意味に一致する重大度が1つしかない場合は、その重大度にその範囲の最小値を割り当てることが推奨されます。 たとえば、ソース形式に「Informational」というログレベルがあり、類似の意味を持つ他のログレベルがない場合は、「Informational」に対して `SeverityNumber=9` を使用することが推奨されます。 重大度やログレベルの概念を定義していないソース形式は、`SeverityNumber` フィールドと `SeverityText` フィールドを省略してもよい（MAY）です。 バックエンドとUIは、重大度情報が欠落しているログレコードを区別して表現してもよいですし、`SeverityNumber` フィールドと `SeverityText` フィールドが欠落しているログレコードを、あたかも `SeverityNumber` がINFO（数値の9）に設定されているかのように解釈してもよいです。 #### 逆マッピング {#reverse-mapping} `SeverityNumber` から特定の形式への逆マッピングを実行する際、その形式に対応するマッピングエントリが `SeverityNumber` に存在しない場合は、同じ重大度の範囲内にあり、数値的に最も近い対象の重大度を選択することが推奨されます。 たとえば、Zapには「Info」と呼ばれる、INFO範囲の重大度が1つしかありません。 逆マッピングを行う際、INFO範囲（数値9〜12）のすべての `SeverityNumber` の値は、Zapの「Info」レベルにマッピングされます。 #### エラーのセマンティクス {#error-semantics} `SeverityNumber` が存在し、その値がERROR（数値17）以上である場合、そのログレコードはエラーの状況を表していることを示しています。 この事実をどのように利用するかを判断するのは、この値の読み手次第です（たとえば、UIはこのようなエラーを異なる色で表示したり、エラーのあるログレコードをすべて見つける機能を持たせたりしてもよいです）。 ログレコードがエラーのイベントを表しており、ソース形式が重大度やログレベルの概念を定義していない場合は、マッピング処理の間に `SeverityNumber` をERROR（数値17）に設定することが推奨されます。 ログレコードがエラーでないイベントを表す場合、`SeverityNumber` フィールドは省略してもよいですし、ERROR（数値17）未満の任意の数値に設定してもよいです。 この場合の推奨値はINFO（数値9）です。 マッピング例については[付録B](#appendix-b-severitynumber-example-mappings)を参照してください。 #### 重大度の表示 {#displaying-severity} 次の表は、各 `SeverityNumber` の値に対する推奨される短縮名を定義します。 この短縮名は、たとえばUIで `SeverityNumber` を表現するために使用できます。 | SeverityNumber | Short Name | | -------------- | ---------- | | 1 | TRACE | | 2 | TRACE2 | | 3 | TRACE3 | | 4 | TRACE4 | | 5 | DEBUG | | 6 | DEBUG2 | | 7 | DEBUG3 | | 8 | DEBUG4 | | 9 | INFO | | 10 | INFO2 | | 11 | INFO3 | | 12 | INFO4 | | 13 | WARN | | 14 | WARN2 | | 15 | WARN3 | | 16 | WARN4 | | 17 | ERROR | | 18 | ERROR2 | | 19 | ERROR3 | | 20 | ERROR4 | | 21 | FATAL | | 22 | FATAL2 | | 23 | FATAL3 | | 24 | FATAL4 | 個々のログレコードを表示する際は、`SeverityText` と `SeverityNumber` の両方の値を表示することが推奨されます。 この場合に推奨される結合文字列は、短縮名で始まり、それに続けて括弧内に `SeverityText` を記載する形式です。 たとえば、「Informational」のSyslogレコードは **INFO (Informational)** として表示されます。 特定のログレコードで `SeverityNumber` は定義されているが `SeverityText` が存在しない場合は、短縮名のみを表示することが推奨されます（たとえば **INFO**）。 ドロップダウンリスト（または、取り得る値の集合を表現することを意図したその他のUI要素）を重大度の表現に使用する場合は、そのようなUI要素に短縮名を表示することが望ましいです。 たとえば、重大度でログレコードをフィルタリングできる重大度のドロップダウンリストは、システムに知られているすべての異なる `SeverityText` の値を列挙するドロップダウンリスト（要素数が多くなる可能性があり、しばしば大文字小文字や省略の違いだけで異なります。たとえば「Info」と「Information」）と比較して、`SeverityNumber` の短縮名を含む（そのため要素数の上限が限られる）方が、より使いやすい可能性が高いです。 #### 重大度の比較 {#comparing-severity} 重大度が未満／超過の比較に関わる文脈では、`SeverityNumber` フィールドを使用すべきです。 `SeverityNumber` は、別の `SeverityNumber` や、1〜24の範囲の数値（または対応する短縮名）と比較できます。 重大度が等価または不等価の比較に使用される場合（たとえばUIのフィルターなど）、マッチングを行う際には `SeverityText` と `SeverityNumber` の短縮名の両方を使用することを試みることが推奨されます（つまり、これらいずれかのフィールドとの一致もマッチとみなすべきです）。 たとえば、`SeverityText` フィールドが「Informational」に等しく、`SeverityNumber` フィールドがINFOに等しいレコードがある場合、そのレコードについて **severity="Informational"** と **severity="INFO"** の両方の条件がTRUEになるようにすることが、ユーザー体験の観点からは望ましいでしょう。 ### フィールド: `Name` {#field-name} 型: 文字列。 説明: 変動する部分を含まない、短いイベント識別子です。 `Name` は何が起きたかを表します（たとえば「ProcessStarted」）。 50文字以内にすることが推奨されます。 一意性は一切保証されません。 通常、バックエンドでのフィルタリングやグルーピングの目的で使用されます。 このフィールドは省略可能です。 ### フィールド: `Body` {#field-body} 型: any。 説明: ログレコードの本文を含む値です（上記の `any` 型の説明を参照）。 たとえば、イベントを自由形式で説明する（複数行を含む）人間可読な文字列メッセージであってもよいですし、他の値の配列やマップで構成された構造化データであってもよいです。 同じソースから発生するイベントの発生ごとに異なる場合があります。 このフィールドは省略可能です。 ### フィールド: `Resource` {#field-resource} 型: キーと値のペアのリスト。 説明: ログのソース、すなわち[リソース](../../specification/overview.md#resources)を説明します。 各ペアの「キー」は `string` 型で、「値」は `any` 型です。 同じイベントソースから発生する複数回のイベントは時間をまたいで発生し得ますが、それらはすべて同じ `Resource` の値を持ちます。 たとえば、レコードを発行するアプリケーションに関する情報や、アプリケーションが実行されるインフラストラクチャに関する情報を含むことができます。 このデータモデルを表現するデータ形式は、同じソースから発生するログレコードのバッチごとに `Resource` フィールドを1回だけ記録できるように設計されることがあります。 リソースの[セマンティック規約](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource)に従うべきです（SHOULD）。 このフィールドは省略可能です。 ### フィールド: `Attributes` {#field-attributes} 型: キーと値のペアのリスト。 説明: 特定のイベント発生に関する追加情報です。 各ペアの「キー」は `string` 型で、「値」は `any` 型です。 特定のソースに対して固定される `Resource` フィールドとは異なり、`Attributes` は同じソースから発生するイベントの発生ごとに異なる場合があります。 （TraceId/SpanId以外の）リクエストコンテキストに関する情報を含むことができます。 OpenTelemetryの[属性のセマンティック規約](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/naming.md#attributes)に従うべきです（SHOULD）。 このフィールドは省略可能です。 ## ログレコードの例 {#example-log-records} 以下は、ログレコードをJSONで表現する一つの可能な方法を示す例です。 これらはあくまでこのデータモデルの理解を助けるための例です。 これらの例を、このデータモデルをJSONで表現する_唯一の_方法として捉えないでください。 このドキュメントは、ログレコード表現の実際のエンコーディングと形式を定義しません。 形式の定義は、別のOTEPで行われます（たとえば、ログレコードはmsgpack、JSON、Protocol Bufferのメッセージなどとして表現される場合があります）。 例1 ```javascript { "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 ```javascript { "Timestamp": 1586960586000, ... "Body": { "i": "am", "an": "event", "of": { "some": "complexity" } } } ``` 例3 ```javascript { "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の議論中に解決された疑問 {#questions-resolved-during-otep-discussion} これらは、[OTEPのプルリクエスト](https://github.com/open-telemetry/oteps/pull/97)で議論され、解決された未解決の疑問でした。 ### `TraceFlags` 対 `TraceParent` と `TraceState` {#traceflags-vs-traceparent-and-tracestate} 質問: `TraceFlags` だけでなく、`traceparent` フィールドと `tracestate` フィールドを含む[W3C Trace Context](https://www.w3.org/TR/trace-context/)全体を保存すべきでしょうか。 回答: この議論では、`traceparent` と `tracestate` が必要であるという証拠は見つかりませんでした。 ### 重大度フィールド {#severity-fields-1} 質問: `SeverityText`/`SeverityNumber` フィールドの設計は十分に優れているでしょうか。 回答: 議論の結果、この設計は妥当であることが示されました。 ### `Timestamp` の要件 {#timestamp-requirements} 質問: この提案の初期の草稿では、`Timestamp` は単調増加でNTP同期されたソースから設定されるべきであると規定されていました。 混乱を避けるため、この要件は削除しました。 タイムスタンプのソースについて何らかの要件が必要でしょうか。 回答: 議論の結果、そのような要件を規定することはデータモデルの責務ではないことが明らかになりました。 ### セキュリティログ {#security-logs} 質問: セキュリティログに対して特別な扱いが必要でしょうか。 回答: このOTEPでの議論では、データモデルの提案という文脈においてセキュリティログを特別に扱う必要性は見出されませんでした。 ## 代替設計 {#alternate-design} エンベロープ方式を用いた代替設計も検討しましたが、総合的にこちらの設計より優れているとは判断しませんでした。 ## 先行技術 {#prior-art} ### RFC5424 Syslog {#rfc5424-syslog} [RFC5424](https://datatracker.ietf.org/doc/html/rfc5424) は、構造化されたログデータの形式とプロトコルを定義しています。 このプロトコルは広く普及していますが（残念ながら多くの実装は構造化データの推奨事項に従っていません）、Syslogをデータモデルの有力な候補としない、いくつかの欠点があります。 - 構造化された属性を許容する一方で、メッセージの本文は文字列のみです。 - 重大度は8つの数値にハードコードされており、カスタムの重大度テキストを許容しません。 - 構造化データは任意のネストを許容せず、2階層のみです。 - データソース（すなわちリソース）を指定するための明確な独立した場所がありません。 この目的を限定的に果たすハードコードされたフィールドがいくつか存在します（HOSTNAME、APP-NAME、FACILITY）。 ### Fluentd Forwardプロトコルモデル {#fluentd-forward-protocol-model} [Forwardプロトコル](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1) は、タイムスタンプ付きレコードとしてログEntryの概念を定義しています。 このレコードは、タグと任意のキーと値のペアのマップという2つの要素で構成されます。 このモデルは、あらゆるログレコードを表現できるほど汎用的です。 しかし、いくつかの欠点があります。 - レコードのすべての属性は、（タグとタイムスタンプを除いて）汎用的なキーと値のペアで表現されます。 これは、最適化の機会を逃しています（[設計上の注記](#design-notes)を参照）。 - データソース（すなわちリソース）を指定するための明確な独立した場所がありません。 - キーがどのように命名されるべきか、どのような値が期待されるかについての言及がありません。 命名規則やキーと値のペアの標準化が欠如していることが、相互運用性を難しくしています。 ## 付録A. マッピング例 {#appendix-a-example-mappings} このセクションには、他のイベントおよびログの形式をこのデータモデルにマッピングする例が含まれています。 ### RFC5424 Syslog {#rfc5424-syslog-1}
プロパティ 型 説明 統合モデルフィールドへのマッピング
TIMESTAMP Timestamp 発生元のクロックで計測された、イベントが発生した時刻です。 Timestamp
SEVERITY enum イベントの重要度を定義します。例: `Debug` Severity
FACILITY enum イベントの発生元を説明します。あらかじめ定義されたUNIXプロセスの一覧です。イベントソースの識別情報の一部です。例: `mail system` `Attributes["syslog.facility"]`
VERSION number メタ情報: プロトコルのバージョンで、イベントとは直交しています。 `Attributes["syslog.version"]`
HOSTNAME string イベントが発生した場所を説明します。取り得る値はFQDN、IPアドレスなどです。 `Resource["host.hostname"]`
APP-NAME string ユーザーが定義したアプリケーション名です。イベントソースの識別情報の一部です。 `Resource["service.name"]`
PROCID string 明確に定義されていません。プロトコル操作の目的でメタフィールドとして使われることも、イベントソースの識別情報の一部として使われることもあります。 `Attributes["syslog.procid"]`
MSGID string イベントの種類を定義します。イベントソースの識別情報の一部です。例: `"TCPIN"` Name
STRUCTURED-DATA array of maps of string to string SD-IDによってさまざまな用途があります。 イベントソースの識別情報を説明できます。 イベントの特定の発生を説明するデータを含められます。 メタ情報（たとえばタイムスタンプ値の品質など）にもなり得ます。 SD-ID origin.swVersionは `Resource["service.version"]` にマッピングされます SD-ID origin.ipは `Attributes["net.host.ip"]` にマッピングされます それ以外のSD-IDは `Attributes["syslog.*"]` にマッピングされます
MSG string イベントに関する自由形式のテキストメッセージです。通常は人間が読める形式です。 Body
### Windowsイベントログ {#windows-event-log}
プロパティ 型 説明 統合モデルフィールドへのマッピング
TimeCreated Timestamp イベントがログに記録された時刻を識別するタイムスタンプです。 Timestamp
Level enum イベントの重大度レベルを含みます。 Severity
Computer string イベントが発生したコンピューターの名前です。 `Resource["host.hostname"]`
EventID uint プロバイダーがイベントを識別するために使用した識別子です。 Name
Message string メッセージ文字列です。 Body
それ以外のフィールド。 any イベント内のその他すべてのフィールドです。 `Attributes["winlog.*"]`
### SignalFxイベント {#signalfx-events}
フィールド 型 説明 統合モデルフィールドへのマッピング
Timestamp Timestamp 発生元のクロックで計測された、イベントが発生した時刻です。 Timestamp
EventType string イベントの種類を説明する、機械が理解できる短い文字列です。SignalFx固有の概念です。名前空間を持ちません。例: k8sのEvent Reasonフィールド。 Name
Category enum イベントの発生元と理由を説明します。SignalFx固有の概念です。例: AGENT。この属性がSignalFxのEventに存在しない場合、LogRecordではnull属性値に設定すべきです。これにより、SignalFxのイベントがLogRecordとして表現される際に一意に識別できるようになります。 `Attributes["com.splunk.signalfx.event_category"]`
Dimensions map of string to string EventTypeおよびCategoryと合わせて、イベントソースの識別情報を定義するのに役立ちます。同じイベントソースから発生する複数回のイベントは時間をまたいで発生し得ますが、それらはすべて同じDimensionsの値を持ちます。SignalFxでは、イベントのDimensionsはEventTypeとともに、個々のEvent Time Series（ETS）を決定します。 Attributes
Properties map of string to any 特定のイベント発生に関する追加情報です。特定のイベントソースに対して固定されるDimensionsとは異なり、Propertiesは同じイベントソースから発生するイベントの発生ごとに異なる値を持つことができます。SignalFxでは、イベントのPropertiesはイベントに関する追加のメタデータとみなされ、Event Time Series（ETS）の識別情報には影響しません。 `Attributes["com.splunk.signalfx.event_properties"]`
### Splunk HEC {#splunk-hec}
フィールド 型 説明 統合モデルフィールドへのマッピング
time numeric, string 秒単位のエポックタイム形式でのイベント時刻です。 Timestamp
host string イベントデータに割り当てるホストの値です。通常は、データの送信元となるクライアントのホスト名です。 `Resource["host.hostname"]`
source string イベントデータに割り当てるソースの値です。たとえば、開発中のアプリケーションからデータを送信している場合、このキーをそのアプリケーションの名前に設定できます。 `Resource["service.name"]`
sourcetype string イベントデータに割り当てるsourcetypeの値です。 `Attributes["source.type"]`
event any イベントの生の本文をJSONで表現したものです。文字列、数値、文字列配列、数値配列、JSONオブジェクト、またはJSON配列になり得ます。 Body
fields Map of any 明示的なカスタムフィールドを含むJSONオブジェクトを指定します。 Attributes
index string イベントデータのインデックス作成に使用するインデックスの名前です。トークンにindexesパラメーターが設定されている場合、ここで指定するインデックスは許可されたインデックスの一覧内でなければなりません。 未定、おそらくattributesに入ります
### Log4j {#log4j}
フィールド 型 説明 統合モデルフィールドへのマッピング
Instant Timestamp 発生元のクロックで計測された、イベントが発生した時刻です。 Timestamp
Level enum ログレベルです。 Severity
Message string 人間が読めるメッセージです。 Body
それ以外のすべてのフィールド any 構造化データです。 Attributes
### Zap {#zap}
フィールド 型 説明 統合モデルフィールドへのマッピング
ts Timestamp 発生元のクロックで計測された、イベントが発生した時刻です。 Timestamp
level enum ログレベルです。 Severity
caller string 呼び出し元関数のファイル名と行番号です。 Attributes、キーは未定
msg string 人間が読めるメッセージです。 Body
それ以外のすべてのフィールド any 構造化データです。 Attributes
### Apache HTTPサーバーアクセスログ {#apache-http-server-access-log}
フィールド 型 説明 統合モデルフィールドへのマッピング
%t Timestamp 発生元のクロックで計測された、イベントが発生した時刻です。 Timestamp
%a string クライアントのIPアドレスです。 `Attributes["net.peer.ip"]`
%A string サーバーのIPアドレスです。 `Attributes["net.host.ip"]`
%h string リモートホスト名です。 `Attributes["net.peer.name"]`
%m string リクエストメソッドです。 `Attributes["http.method"]`
%v,%p,%U,%q string URLに組み合わせられる複数のフィールドです。 `Attributes["http.url"]`
%>s string レスポンスステータスです。 `Attributes["http.status_code"]`
それ以外のすべてのフィールド any 構造化データです。 Attributes、キーは未定
### CloudTrailログイベント {#cloudtrail-log-event}
フィールド 型 説明 統合モデルフィールドへのマッピング
eventTime string 協定世界時（UTC）で表された、リクエストが行われた日時です。 Timestamp
eventSource string リクエストの送信先となったサービスです。この名前は通常、サービス名からスペースを除いた短縮形に.amazonaws.comを付加したものです。 `Resource["service.name"]`?
awsRegion string リクエストの送信先となったAWSリージョンです（例: us-east-2）。 `Resource["cloud.region"]`
sourceIPAddress string リクエストの送信元となったIPアドレスです。 `Resource["net.peer.ip"]` または `Resource["net.host.ip"]`？未定
errorCode string リクエストがエラーを返した場合のAWSサービスのエラーです。 Name
errorMessage string リクエストがエラーを返した場合の、そのエラーの説明です。 Body
それ以外のすべてのフィールド * `Attributes["cloudtrail.*"]`
### Google Cloud Logging {#google-cloud-logging} | Field | Type | Description | Maps to Unified Model Field | | ----- | ---- | ----------- | --------------------------- | | timestamp | string | ログエントリが説明するイベントが発生した時刻です。 | Timestamp | | resource | MonitoredResource | このログエントリを生成した監視対象リソースです。 | Resource | | log_name | string | このエントリがどのログストリームに属するかを識別する、log_nameフィールドのURLエンコードされたLOG_IDサフィックスです。 | Name | | json_payload | google.protobuf.Struct | JSONオブジェクトとして表現された構造体で表されるログエントリのペイロードです。 | Body | | proto_payload | google.protobuf.Any | プロトコルバッファーとして表されるログエントリのペイロードです。 | Body | | text_payload | string | Unicode文字列（UTF-8）で表されるログエントリのペイロードです。 | Body | | severity | LogSeverity | ログエントリの重大度です。 | Severity | | trace | string | ログエントリに関連付けられたトレースです（存在する場合）。 | TraceId | | span_id | string | ログエントリに関連付けられたトレース内のスパンIDです。 | SpanId | | labels | map | ログエントリに関する追加情報を提供する、ユーザー定義の（キー、値）データの集合です。 | Attributes | | それ以外のすべてのフィールド | | | `Attributes["google.*"]` | ## Elastic Common Schema {#elastic-common-schema}
フィールド 型 説明 統合モデルフィールドへのマッピング
@timestamp datetime イベントが記録された時刻です。 timestamp
message string 任意の種類のメッセージです。 body
labels key/value イベントに関連する任意のラベルです。 attributes[*]
tags array of string イベントに関連する値の一覧です。 ?
trace.id string トレースIDです。 TraceId
span.id* string スパンIDです。 SpanId
agent.ephemeral_id string エージェントが作成したエフェメラルIDです。 **resource
agent.id string このエージェントの一意な識別子です。 **resource
agent.name string エージェントに付けられた名前です。 `Resource["telemetry.sdk.name"]`
agent.type string エージェントの種類です。 `Resource["telemetry.sdk.language"]`
agent.version string エージェントのバージョンです。 `Resource["telemetry.sdk.version"]`
source.ip, client.ip string リクエストの送信元となったIPアドレスです。 `Attributes["net.peer.ip"]` または `Attributes["net.host.ip"]`
cloud.account.id string 対象のクラウドにおけるアカウントのIDです。 `Resource["cloud.account.id"]`
cloud.availability_zone string このホストが実行されているアベイラビリティゾーンです。 `Resource["cloud.zone"]`
cloud.instance.id string ホストマシンのインスタンスIDです。 **resource
cloud.instance.name string ホストマシンのインスタンス名です。 **resource
cloud.machine.type string ホストマシンのマシンタイプです。 **resource
cloud.provider string クラウドプロバイダーの名前です。例としてaws、azure、gcp、digitaloceanなどの値があります。 `Resource["cloud.provider"]`
cloud.region string このホストが実行されているリージョンです。 `Resource["cloud.region"]`
cloud.image.id* string `Resource["host.image.name"]`
container.id string 一意なコンテナIDです。 `Resource["container.id"]`
container.image.name string コンテナのビルド元となったイメージの名前です。 `Resource["container.image.name"]`
container.image.tag Array of string コンテナイメージのタグです。 **resource
container.labels key/value イメージのラベルです。 attributes[*]
container.name string コンテナ名です。 `Resource["container.name"]`
container.runtime string このコンテナを管理するランタイムです。例: "docker" **resource
destination.address string イベントの宛先アドレスです。 `Attributes["destination.address"]`
error.code string エラーを説明するエラーコードです。 `Attributes["error.code"]`
error.id string エラーの一意な識別子です。 `Attributes["error.id"]`
error.message string エラーメッセージです。 `Attributes["error.message"]`
error.stack_trace string このエラーのスタックトレースをプレーンテキストで表したものです。 `Attributes["error.stack_trace]
host.architecture string オペレーティングシステムのアーキテクチャです。 **resource
host.domain string ホストが属しているドメインの名前です。 たとえば、Windowsの場合はホストのActive Directoryドメインまたは NetBIOSドメイン名になり得ます。Linuxの場合はホストのLDAPプロバイダーのドメインになり得ます。 **resource
host.hostname string ホストのホスト名です。 通常、ホストマシン上でhostnameコマンドが返す値が含まれます。 `Resource["host.hostname"]`
host.id string 一意なホストIDです。 `Resource["host.id"]`
host.ip Array of string ホストのIPです。 `Resource["host.ip"]`
host.mac array of string ホストのMACアドレスです。 `Resource["host.mac"]`
host.name string ホストの名前です。 UNIXシステムでhostnameが返す値、完全修飾名、またはユーザーが指定した名前が含まれる場合があります。 `Resource["host.name"]`
host.type string ホストの種類です。 `Resource["host.type"]`
host.uptime string ホストが稼働している秒数です。 ?
service.ephemeral_id string このサービスのエフェメラル識別子です。 **resource
service.id string 実行中のサービスの一意な識別子です。サービスが多数のノードで構成されている場合、service.idはすべてのノードで同一であるべきです。 **resource
service.name string データの収集元となるサービスの名前です。 `Resource["service.name"]`
service.node.name string そのサービスを提供する特定のノードです。 `Resource["service.instance.id"]`
service.state string サービスの現在の状態です。 `Attributes["service.state"]`
service.type string データの収集元となるサービスの種類です。 **resource
service.version string データの収集元となるサービスのバージョンです。 `Resource["service.version"]`
\* まだECSに正式に組み込まれていません。 \*\* [OpenTelemetryのリソースのセマンティック規約](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource)に存在しないリソースです。 これは、最も関連性の高いフィールドを抜粋したものです。 網羅的な一覧については[完全なリファレンス](https://www.elastic.co/docs/reference/ecs/ecs-field-reference)を参照してください。 ## 付録B: `SeverityNumber` のマッピング例 {#appendix-b-severitynumber-example-mappings} | Syslog | WinEvtLog | Log4j | Zap | java.util.logging | SeverityNumber | | ------ | --------- | ----- | --- | ----------------- | -------------- | | | | TRACE | | FINEST | TRACE | | Debug | Verbose | DEBUG | Debug | FINER | DEBUG | | | | | | FINE | DEBUG2 | | | | | | CONFIG | DEBUG3 | | Informational | Information | INFO | Info | INFO | INFO | | Notice | | | | | INFO2 | | Warning | Warning | WARN | Warn | WARNING | WARN | | Error | Error | ERROR | Error | SEVERE | ERROR | | Critical | Critical | | Dpanic | | ERROR2 | | Emergency | | | Panic | | ERROR3 | | Alert | | FATAL | Fatal | | FATAL | ## 参考文献 {#references} - [データモデルの草稿の議論](https://docs.google.com/document/d/1ASjqT4eV0JKm-a15J508HEJ2-gbqdcM1Abud_Ek86Tc/edit?tab=t.0)