ログのデータモデル付録

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

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

注: この文書は仕様ではなく、ログのデータモデル仕様を補足するために提供されています。これらの例はあくまで説明のためのものであり、網羅的・規範的なものではありません。正確な詳細が必要な場合は、それぞれのエクスポーターのドキュメントを参照してください。

Appendix A. Example Mappings

この節には、他のイベント・ログフォーマットをこのデータモデルへマッピングする例が含まれています。

RFC5424 Syslog

プロパティ	型	説明	統一モデルのフィールドへのマッピング
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.name"]`
APP-NAME	string	ユーザー定義のアプリケーション名。イベント発生源のアイデンティティの一部です。	`Resource["service.name"]`
PROCID	string	明確には定義されていません。プロトコル操作のためのメタフィールドとして使われることも、イベント発生源のアイデンティティの一部として使われることもあります。	`Attributes["syslog.procid"]`
MSGID	string	イベントの種別を定義します。イベント発生源のアイデンティティの一部です。例: `"TCPIN"`	`Attributes["syslog.msgid"]`
STRUCTURED-DATA	array of maps of string to string	SD-IDに応じてさまざまな用途があります。イベント発生源のアイデンティティを記述できます。イベントの特定の発生を記述するデータを含められます。タイムスタンプ値の品質など、メタ情報になることもあります。	SD-IDのorigin.swVersionは`Resource["service.version"]`にマッピングされます。SD-IDのorigin.ipは`Attributes["client.address"]`にマッピングされます。残りのSD-IDは`Attributes["syslog.*"]`にマッピングされます。
MSG	string	イベントに関する自由形式のテキストメッセージ。通常は人間が読める形式です。	Body

Windows Event Log

プロパティ	型	説明	統一モデルのフィールドへのマッピング
TimeCreated	Timestamp	イベントが記録された時刻を識別するタイムスタンプ。	Timestamp
Level	enum	イベントの重大度レベルを含みます。	Severity
Computer	string	イベントが発生したコンピューターの名前。	`Resource["host.name"]`
EventID	uint	プロバイダーがイベントを識別するために使った識別子。	`Attributes["winlog.event_id"]`
Message	string	メッセージ文字列。	Body
その他すべてのフィールド。	any	イベント内のその他すべてのフィールド。	`Attributes["winlog.*"]`

SignalFx Events

フィールド	型	説明	統一モデルのフィールドへのマッピング
Timestamp	Timestamp	発生元のクロックで計測された、イベントが発生した時刻。	Timestamp
EventType	string	イベント種別を記述する、機械が理解できる短い文字列。SignalFx固有の概念です。名前空間を持ちません。例: k8sのEvent Reasonフィールド。	`Attributes["com.splunk.signalfx.event_type"]`
Category	enum	イベントの発生元とその理由を記述します。SignalFx固有の概念です。例: AGENT。	`Attributes["com.splunk.signalfx.event_category"]`
Dimensions	map<string, string>	EventTypeとCategoryと合わせて、イベント発生源のアイデンティティを定義するのに役立ちます。同じイベント発生源から来るイベントが時間をおいて複数回発生しても、それらはすべてDimensionsの値を持ちます。	Resource
Properties	map<string, any>	特定のイベント発生に関する追加情報。特定のイベント発生源に対して固定されているDimensionsとは異なり、Propertiesは同じイベント発生源から来るイベントの発生ごとに異なる値を持てます。	Attributes

Splunk HEC

HECから統一モデルへ、次のマッピングを適用します。

フィールド	型	説明	統一モデルのフィールドへのマッピング
time	numeric, string	秒単位のエポックタイム形式によるイベント時刻。	Timestamp
host	string	イベントデータに割り当てるhostの値。通常はデータを送信しているクライアントのホスト名です。	`Resource["host.name"]`
source	string	イベントデータに割り当てるsourceの値。例えば、開発中のアプリケーションからデータを送信している場合、このキーをそのアプリケーションの名前に設定できます。	`Resource["com.splunk.source"]`
sourcetype	string	イベントデータに割り当てるsourcetypeの値。	`Resource["com.splunk.sourcetype"]`
event	any	イベントの生のbodyをJSONで表現したもの。文字列、数値、文字列配列、数値配列、JSONオブジェクト、JSON配列のいずれかです。	Body
fields	map<string, any>	明示的なカスタムフィールドを含むJSONオブジェクトを指定します。	Attributes
index	string	イベントデータのインデックス付けに使われるインデックスの名前。トークンにindexesパラメータが設定されている場合、ここで指定するインデックスは許可されたインデックスのリストに含まれていなければなりません。	`Attributes["com.splunk.index"]`

統一モデルからHECへマッピングする際は、次の追加のマッピングを適用します。

統一モデルの要素	型	説明	HECへのマッピング
SeverityText	string	人間が読める文字列としてのイベントの重大度。	`Fields["otel.log.severity.text"]`
SeverityNumber	string	数値としてのイベントの重大度。	`Fields["otel.log.severity.number"]`
Name	string	変化する部分を含まない短いイベント識別子。	`Fields["otel.log.name"]`
TraceId	string	リクエストのトレースID。	`Fields["trace_id"]`
SpanId	string	リクエストのスパンID。	`Fields["span_id"]`
TraceFlags	string	W3Cのトレースフラグ。	`Fields["trace_flags"]`

Log4j

フィールド	型	説明	統一モデルのフィールドへのマッピング
Instant	Timestamp	発生元のクロックで計測された、イベントが発生した時刻。	Timestamp
Level	enum	ログレベル。	Severity
Message	string	人間が読めるメッセージ。	Body
その他すべてのフィールド	any	構造化データ。	Attributes

Zap

フィールド	型	説明	統一モデルのフィールドへのマッピング
ts	Timestamp	発生元のクロックで計測された、イベントが発生した時刻。	Timestamp
level	enum	ログレベル。	Severity
caller	string	呼び出し元関数のファイル名と行番号。	Attributes、key=未定
msg	string	人間が読めるメッセージ。	Body
その他すべてのフィールド	any	構造化データ。	Attributes

Apache HTTP Server access log

フィールド	型	説明	統一モデルのフィールドへのマッピング
%t	Timestamp	発生元のクロックで計測された、イベントが発生した時刻。	Timestamp
%a	string	クライアントアドレス	`Attributes["network.peer.address"]`
%A	string	サーバーアドレス	`Attributes["network.local.address"]`
%h	string	クライアントのホスト名。	`Attributes["client.address"]`
%m	string	リクエストメソッド。	`Attributes["http.request.method"]`
%v,%p,%U,%q	string	組み合わせてURLを構成できる複数のフィールド。	`Attributes["url.full"]`
%>s	string	レスポンスステータス。	`Attributes["http.response.status_code"]`
その他すべてのフィールド	any	構造化データ。	Attributes、key=未定

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アドレス。	`Attributes["client.address"]`
errorCode	string	リクエストがエラーを返した場合のAWSサービスのエラー。	`Attributes["cloudtrail.error_code"]`
errorMessage	string	リクエストがエラーを返した場合の、そのエラーの説明。	Body
その他すべてのフィールド	*		`Attributes["cloudtrail.*"]`

Google Cloud Logging

フィールド	型	説明	統一モデルのフィールドへのマッピング
timestamp	string	ログエントリが記述するイベントが発生した時刻。	Timestamp
resource	MonitoredResource	このログエントリを生成した監視対象リソース。	Resource
log_name	string	log_nameフィールドのURLエンコードされたLOG_IDサフィックスは、このエントリがどのログストリームに属するかを識別します。	`Attributes["gcp.log_name"]`
json_payload	google.protobuf.Struct	JSONオブジェクトとして表現された構造体として表されるログエントリのペイロード。	Body
proto_payload	google.protobuf.Any	Protocol Bufferとして表現されるログエントリのペイロード。	Body
text_payload	string	Unicode文字列（UTF-8）として表現されるログエントリのペイロード。	Body
severity	LogSeverity	ログエントリの重大度。	Severity
trace	string	ログエントリに関連付けられたトレース（あれば）。	TraceId
span_id	string	ログエントリに関連付けられたトレース内のスパンID。	SpanId
labels	map<string,string>	ログエントリに関する追加情報を提供する、ユーザー定義のキーと値の組の集合。	Attributes
http_request	HttpRequest	ログエントリに関連付けられたHTTPリクエスト（あれば）。	`Attributes["gcp.http_request"]`
trace_sampled	boolean	ログエントリに関連付けられたトレースのサンプリング判定。	TraceFlags.SAMPLED
その他すべてのフィールド			`Attributes["gcp.*"]`

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["client.address"]`
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ではホストのアクティブディレクトリドメインやNetBIOSドメイン名になります。LinuxではホストのLDAPプロバイダーのドメインになります。	**Resource
host.name	string	ホストのホスト名。通常はホストマシンでhostnameコマンドが返す値を含みます。	`Resource["host.name"]`
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が返す値、FQDN、あるいはユーザーが指定した名前を含むことがあります。	`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のリソースに関するセマンティック規約には存在しないリソースです。

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

ETW (Event Tracing for Windows)

次の表は、ETWイベントのフィールドがログのデータモデルへどのようにマッピングされるかを示します。ETWのヘッダーメタデータはetw.*属性の下に保持され、TDHでデコードされたTraceLoggingのペイロードフィールドは、そのフィールド名をキーとする属性として追加されます。

ETWフィールド	型	説明	統一モデルのフィールドへのマッピング
TimeStamp	Timestamp	`EVENT_HEADER.TimeStamp`を、トレース・セッションのタイムスタンプメタデータ（QPC、システム時刻、CPUサイクルカウンターなど）に従ってUNIXエポックナノ秒に変換した値	Timestamp
Level	uint8	イベントの重大度・詳細レベル	Severity（`SeverityNumber`と`SeverityText`）および`Attributes["etw.level"]`
Event name	string	TraceLoggingのイベント名（TDH経由）。取得できない場合は`etw.<EventId>`にフォールバックします	`EventName`
Payload	any	ETWには単一のメッセージフィールドがありません。デコードされたフィールドは`Attributes`へ格納され、`Body`は空のままになります	Body
ProviderId	GUID	プロバイダーGUID。ハイフン区切りの16進文字列でフォーマットされます	`Attributes["etw.provider.id"]`
EventId	uint16	イベントディスクリプタから得られるイベント識別子	`Attributes["etw.event.id"]`
Opcode	uint8	イベントディスクリプタから得られるOpcode	`Attributes["etw.opcode"]`
Version	uint8	イベントディスクリプタから得られるバージョン	`Attributes["etw.version"]`
Keywords	uint64	イベントディスクリプタから得られるKeywordsのビットマスク	`Attributes["etw.keywords"]`
ProcessId	uint32	イベントヘッダーから得られる発行元プロセスID	`Attributes["etw.process.id"]`
ThreadId	uint32	イベントヘッダーから得られる発行元スレッドID	`Attributes["etw.thread.id"]`
ActivityId	GUID	相関ID。ゼロでない場合にのみ発行されます	`Attributes["etw.activity.id"]`
Decoded payload fields	any	フィールド名をキーとする、TDHでデコードされたTraceLoggingフィールド	`Attributes[<field name>]`

ETWのLevelは8ビットの値であり、その意味はEVENT_DESCRIPTORによって定義されます。SeverityTextには、発生元で知られている元のETWレベル名がそのまま入ります。

ETWレベル	ETW名	SeverityNumber	SeverityText
0	LOG_ALWAYS	0 (UNSPECIFIED)	LOG_ALWAYS
1	CRITICAL	21 (FATAL)	CRITICAL
2	ERROR	17 (ERROR)	ERROR
3	WARNING	13 (WARN)	WARNING
4	INFO	9 (INFO)	INFO
5	VERBOSE	5 (DEBUG)	VERBOSE
6–15	reserved	0 (UNSPECIFIED)	(none)
16–255	provider-defined	0 (UNSPECIFIED)	provider-defined (if any)

Level 0（LOG_ALWAYS）は重大度ではなく、フィルタリングの指示です。ETWはevent.level <= session.levelのときにイベントを配信するため、レベル0のイベントは設定されたセッションレベルにかかわらず常に配信されます。重大度の情報を持たないため、特定の重大度を作り出すのではなくSeverityNumberはUNSPECIFIED (0)にマッピングされます。元の発生源名はSeverityTextにLOG_ALWAYSとしてそのまま記録されます。レベル6〜15はMicrosoftによって予約されており、プロバイダーが定義に使うことはできないため、名前を持ちません。レベル16〜255はプロバイダー定義のカスタムレベルです。各プロバイダーのマニフェストが名前（NotValidなど）を割り当てることがありますが、プロバイダー間で標準化された名前はないため、SeverityTextはそのレベルに対してプロバイダーが定義した値（あれば）になります。いずれの範囲も標準化された重大度を持たず、UNSPECIFIED (0)にマッピングされます。いずれの場合も、元のETWレベルはAttributes["etw.level"]に保持されるため、マッピングは可逆的です。

このマッピングの実装例として、OpenTelemetry otel-arrowプロジェクトのETW receiverがあります。この参照は説明のためのものであり非規範的です。上記のマッピングは特定の実装に紐づくものではありません。

Appendix B: `SeverityNumber` example mappings

Syslog	WinEvtLog	ETW	Log4j	Zap	java.util.logging	.NET (Microsoft.Extensions.Logging)	SeverityNumber
			TRACE		FINEST	LogLevel.Trace	TRACE (1)
Debug (7)	Verbose	VERBOSE	DEBUG	Debug	FINER	LogLevel.Debug	DEBUG (5)
					FINE		DEBUG2 (6)
					CONFIG		DEBUG3 (7)
Informational (6)	Information	INFO	INFO	Info	INFO	LogLevel.Information	INFO (9)
Notice (5)							INFO2 (10)
Warning (4)	Warning	WARNING	WARN	Warn	WARNING	LogLevel.Warning	WARN (13)
Error (3)	Error	ERROR	ERROR	Error	SEVERE	LogLevel.Error	ERROR (17)
Critical (2)	Critical			Dpanic			ERROR2 (18)
Alert (1)				Panic			ERROR3 (19)
Emergency (0)		CRITICAL	FATAL	Fatal		LogLevel.Critical	FATAL (21)

参考文献

OTEP0097 ログのデータモデル、Appendix A. Example Mappings