イベントに関するセマンティック規約

ステータス: Development

この文書は、データモデルにおいてEventRecord（イベント名を持つ LogRecord）として表現されるイベントに関するセマンティック規約を説明します。

イベントを定義すべき場合

イベントは、意味のある時点で発生した名前付きの出来事を記述します。

イベントを定義すべき場合:

その出来事が、新しいトレースコンテキストや子操作を必要としない場合。
その出来事が、より長い操作や非同期フローにおけるチェックポイント、状態変化、ある時点での出来事、または結果を表す場合。

例えば、ユーザーの操作、状態遷移、フィーチャーフラグの評価、サービスの起動・設定のリロード・シャットダウンの完了などのライフサイクル上の出来事、操作の実行中に発生した例外に対してイベントを定義します。

イベントを定義すべきでない場合:

継続時間と意味のある境界を持つ操作の場合は、代わりにスパンを使います。
操作全体を記述し、それ自体のタイムスタンプを必要としない属性の場合は、代わりにスパン属性を使います。
名前付きイベントとして問い合わせられることを意図していない、構造化されていない診断メッセージの場合は、代わりに通常のログレコードを発行します。これらのレコードはイベントとしてモデル化されませんが、それでもログに関するセマンティック規約に従うことができます。

イベントは、しばしばスパンの定義を補完します。イベントは、アクティブなトレースコンテキストの内側でも外側でも発行できます。

データが操作内の明確な出来事を表し、同じスパンに対して0回以上発生し得る場合、またはそれ自体のタイムスタンプ、重大度、出来事固有の属性を必要とする場合は、スパン属性の代わりにイベントを使います。データが操作全体を記述する場合、特にそれがサンプリングに役立つ場合やスパン開始時点で判明している場合は、スパン属性を使います。

イベントの定義では、そのイベントがいつ記録されるか、計装対象のコンポーネントにおいてどのドメイン固有の出来事を表すか、イベント名、どのタイムスタンプを使うか、デフォルトの重大度、適用可能な属性を説明すべきです。

イベント名

セマンティック規約は、イベント名を文書化しなければなりません（MUST）。

イベントは、イベント構造を一意に識別するイベント名を持たなければなりません（MUST）。

イベント名は、イベント構造を一意に識別します。ユーザーが特定のイベント名で問い合わせを行う際、対応するセマンティック規約に準拠したイベントを取得できるべきです。

イベント名は命名ガイドラインに従うべきです（SHOULD）。
イベント名は、動的な値を含んではなりません（MUST NOT）。出来事ごとに変わる識別子、名前、その他の値には属性を使います。
イベントが特定の操作やシステムに結び付いている場合は、完全修飾されたドメイン固有の名前を使います。例えば、http.client.request.exception はHTTPクライアントリクエスト中の例外を表します。
共有名は、その名前で記録されるすべての出来事に同じ定義が適用される場合にのみ使います。
既存のシステムからの出来事をOpenTelemetryのイベントとしてモデル化する場合、そのシステムに単一の名前フィールドがなかったり、イベントを識別するために複数のフィールドが必要になることがよくあります。このような場合、セマンティック規約は複数のフィールドを組み合わせて、低カーディナリティのイベント名を作成できます。

タイムスタンプ

イベントは、Timestampに、その出来事が発生した時刻を設定しなければなりません（MUST）。

セマンティック規約は、ObservedTimestampの値を定義してはなりません（MUST NOT）。SDK、コレクター、その他のコンポーネントが、そのイベントが観測・受信された時刻を反映するようにこの値を設定すべきです。

重大度

セマンティック規約は、デフォルトの重大度番号を指定すべきです（SHOULD）。

重大度番号は、その出来事が想定する影響の大きさに基づいて定義します。同じイベントが文脈によって異なる重大度を持ちうる場合は、それぞれの重大度を設定する条件を文書化してください。

例外イベントについては、ログにおける例外に関するセマンティック規約の重大度に関する指針に従ってください。

セマンティック規約は、重大度テキストを定義してはなりません（MUST NOT）。

属性

セマンティック規約は、構造化されたイベントの詳細とコンテキストを表すイベント属性を文書化しなければなりません（MUST）。

可能な場合は既存の属性を再利用します。特に、関連するスパン、メトリクス、リソース、他のイベントで使われている属性です。
ユーザーがフィルター、グループ化、集計、関連付けに使う可能性が高い属性を含めます。
イベントが通常スパンに関連付けられている場合、デフォルトでスパンのすべての属性をコピーすることは避けます。スパンなしでそのイベントを理解、ルーティング、保持するために必要な場合にのみ、イベント上でスパンレベルの属性を参照します。
値を構造なしで明確に表現できる場合は、フラットな属性を優先します。構造がイベントのセマンティクスの一部であり、フラットな表現では不都合が生じたり情報が失われる場合にのみ、複合的な属性を使います。
失敗、または成功・失敗のいずれにもなり得る操作の結果を表すイベントを定義する場合は、error.type を含めます。
要求レベルを指定し、そのイベントに合わせて概要と注記を調整してください。
機密情報を含む可能性がある、取得コストが高い、または特に大きい可能性がある属性を文書化します。

本文

セマンティック規約は、イベントの文字列による表示メッセージを表す場合を除き、本文の値を定義してはなりません（MUST NOT）。