Yoshi Yamaguchi

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/general/naming/

翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）

命名

ステータス: Stable（特に断りがない限り）。

一般的な命名上の考慮事項

この節は、属性名（「属性キー」とも呼ばれます）に加え、メトリクス名とイベント名にも適用されます。 この節の中で形容詞を付けずに「名前」という語を使う場合、これらすべてを意味するものとします。

すべての名前は、有効なUnicode列でなければなりません（MUST）。

[!NOTE] ここで要求しているのは、名前がUnicode列として表現されることだけです。 この仕様は、そのUnicode列を正確にどのようにエンコードするかを定義しません。 エンコード方法は、プログラミング言語やワイヤーフォーマットによって異なります。 対象のプログラミング言語やワイヤーフォーマットにおいて、Unicodeを表現するイディオムに従ってください。

名前は、次の規則に従うべきです（SHOULD）。

  • 名前は小文字にすべきです（SHOULD）。

  • 名前空間を使ってください。名前空間はドット文字で区切ります。 例えば service.version は、サービスのバージョンを表し、ここで service が名前空間、version がその名前空間内の属性です。

  • 名前空間は入れ子にできます。 例えば telemetry.sdk は、トップレベルの名前空間 telemetry の中にある名前空間であり、telemetry.sdk.name は名前空間 telemetry.sdk の中にある属性です。

    意味が通る場合は常に名前空間（とドット区切り）を使ってください。 例えば、あるオブジェクトのプロパティを表す属性を導入する場合は、*{object}.{property} というパターンに従ってください。 そのオブジェクトが他のプロパティを持ちうる場合は、アンダースコア（*{object}_{property}）を使うのは避けてください。

  • 名前のドット区切りの各構成要素が複数語からなる場合、単語をアンダースコアで区切ってください（つまりsnake_caseを使ってください）。 例えば http.response.status_code は、HTTP名前空間内のステータスコードを表します。

    既知の例外として、インストゥルメント対象のAPIとの整合性のために単一の単語が使われるK8s APIの名前があります。

    ドット（名前空間化）を使うことが意味をなさない場合や、名前の意味そのものが変わってしまう場合にのみアンダースコアを使ってください。 例えば、rate.limiting ではなく rate_limiting を使ってください。

  • 正確であってください。属性名、イベント名、メトリクス名、その他の名前は、説明的で曖昧さのないものにすべきです。

    • あるオブジェクトの特定のプロパティを表す名前を導入する場合は、そのプロパティ名を含めてください。 例えば、file.owner の代わりに file.owner.name を、system.network.dropped の代わりに system.network.packet.dropped を使ってください。
    • 異なる規約や計装で使われた場合に別の意味になってしまうような名前や名前空間の導入は避けてください。 例えば、rule の代わりに security_rule を使ってください。

  • 明確さを損なわない範囲で、短い名前を使ってください。 必要のない名前空間の構成要素や、複数語の構成要素の中の単語は削ってください。 例えば、vcs.change.id は vcs.repository.change.id と同じくらい正確にプルリクエストIDを表現します。

名前の省略ガイドライン

省略形は、広く認知され一般的に使われている場合には使ってもかまいません（MAY）。

例としては、IP、DB、CPU、HTTP、URL などの一般的な技術的省略形や、AWS、GCP、K8s などの製品名が挙げられます。

一般的に認知されているものの、特定の領域内でのみ認知されている省略形は、対応する名前空間で修飾されている場合に使ってもかまいません（MAY）。

例えば、container.container_storage_interface の代わりに container.csi.* を、container.open_container_initiative.* の代わりに container.oci.* を使ってください。

省略形が曖昧な場合、例えば複数の製品や概念に当てはまる場合は、使用を避けるべきです（SHOULD）。

名前の再利用の禁止

2つの属性、2つのメトリクス、あるいは2つのイベントが同じ名前を共有してはなりません（MUST NOT）。 異なる種類のエンティティ（属性とメトリクス、メトリクスとイベント）は、同じ名前を共有してもかまいません（MAY）。

属性、メトリクス、イベントは、成熟度のレベルにかかわらず、セマンティック規約から削除するべきではありません（SHOULD NOT）。 規約の名前が変更された場合や推奨されなくなった場合は、非推奨（deprecated）にすべきです（SHOULD）。

OpenTelemetryの作成者への推奨事項

  • 新しいセマンティック規約を考える際は、既存の名前空間（Semantic Conventions）を確認し、類似の名前空間が既に存在しないかを確かめてください。

  • OpenTelemetryのセマンティック規約に含まれるすべての名前は、名前空間の一部であるべきです（SHOULD）。

  • 新しい名前空間が必要になった場合は、それをトップレベルの名前空間（例: service）にするべきか、入れ子の名前空間（例: service.instance）にするべきかを検討してください。

  • セマンティック規約は、名前を印字可能なBasic Latin文字（より正確には U+0021 .. U+007E の部分集合）に限定しなければなりません（MUST）。 さらに、名前を次のUnicodeコードポイントに限定することが推奨されます。ラテンアルファベット、数字、アンダースコア、ドット（名前空間の区切り文字として）です。

[!Note] セマンティック規約のツールは、名前を小文字のラテンアルファベット、数字、アンダースコア、ドット（名前空間の区切り文字として）に限定します。 名前は文字で始まり、英数字で終わらなければならず、2つ以上の区切り文字（アンダースコアまたはドット）を連続して含んではなりません。

アプリケーション開発者への推奨事項

アプリケーション開発者として属性、メトリクス、イベント、その他のシグナルを記録する必要がある場合は、まず既存のセマンティック規約を確認してください。 適切な名前が存在しない場合は、新しい名前を考える必要があります。 そのためには、いくつかの選択肢を検討してください。

  • その名前が自社に固有であり、社外でも使われる可能性がある場合、複数のベンダーのアプリケーションを使う分散システムにおいて他社が導入した名前との衝突を避けるため、自社のリバースドメイン名を新しい名前の前に付けることが推奨されます（例: com.acme.shopname）。

  • その名前が社内でのみ使われる自社のアプリケーションに固有である場合、名前の衝突が起きないようにする社内プロセスが既にあるなら、それに従ってもかまいません。 そうでない場合は、アプリケーション名が組織内で十分に一意であることを前提に、属性名の前にアプリケーション名を付けることが推奨されます（例: myuniquemapapp.longitude はおそらく問題ありません）。 アプリケーション名が既存のセマンティック規約の名前空間と衝突しないようにしてください。

  • 既存のOpenTelemetryセマンティック規約の名前空間を、新しい自社固有・アプリケーション固有の属性名の接頭辞として使うことは推奨されません。 そうすると、将来OpenTelemetryが同じ名前を別の目的で使うことを決めた場合や、別のサードパーティ計装が全く同じ属性名を使い、それを自社の計装と組み合わせた場合に、名前の衝突が生じる可能性があります。

  • その名前が業界のアプリケーション全般に広く適用できる場合は、この仕様に新しい名前を追加する提案の提出を検討してください。必要であれば新しい名前空間の追加も検討してください。

名前は印字可能なBasic Latin文字（より正確には U+0021 .. U+007E の部分集合）に限定することが推奨されます。

属性

otel.* 名前空間

otel. で始まる属性名は、OpenTelemetry仕様で定義するために予約されています。 これらは通常、対応する概念を持たないフォーマットでOpenTelemetryの概念を表現するために使われます。

例えば、otel.scope.name 属性は、計装スコープ名を記録するために使われます。これはOTLPにネイティブに表現されるOpenTelemetryの概念ですが、他のテレメトリーフォーマットやプロトコルには対応する概念がありません。

otel.* 名前空間への追加は、OpenTelemetry仕様の一部として承認されなければなりません（MUST）。

属性名の複数形化ガイドライン

  • 属性が単一のエンティティを表す場合、属性名は単数形にすべきです（SHOULD）。例: host.name、container.id。

  • 属性が複数のエンティティを表せる場合、属性名は複数形にし、値の型は配列にすべきです（SHOULD）。 例えば process.command_args には、実行ファイル名とコマンド引数という複数の値が含まれることがあります。

  • 属性が計測値を表す場合は、属性名について名前の複数形化ガイドラインに従うべきです（SHOULD）。

シグナル固有の属性

ステータス: Development

属性は、シグナルに依存しない形でセマンティック規約の中で定義されます。 同じ属性が複数のシグナルで使われることが期待されます。

属性が定義される時点で、それが特定のメトリクス、イベント、その他の規約の範囲を超えて使われるかどうかは、必ずしも明確ではありません。

特定の規約を超えて使われる可能性が低い属性は、そのメトリクス（イベントなど）の名前空間の下に追加すべきです（SHOULD）。

例:

メトリクス system.filesystem.usage の属性 mode と mountpoint は、system.filesystem.mode と system.filesystem.mountpoint として名前空間化すべきです。

メトリクス、イベント、リソース、その他のシグナルは、複数の名前空間にわたる適用可能な属性を使うことが期待され、推奨されます。

例:

メトリクス http.server.request.duration は、レジストリの server.port、error.type などの属性を使います。

メトリクス

ステータス: Development

CounterとUpDownCounterの命名規則

複数形化

メトリクスの名前空間は複数形化するべきではありません（SHOULD NOT）。

記録される値が可算の量の離散的なインスタンスを表す場合を除き、メトリクス名は複数形化するべきではありません（SHOULD NOT）。 一般に、メトリクスの単位が非単位（{fault} や {operation} のようなもの）である場合にのみ、名前を複数形化するべきです（SHOULD）。

例:

  • system.filesystem.utilization、http.server.request.duration、system.cpu.time は、多数のデータポイントが記録される場合でも複数形化するべきではありません。
  • system.paging.faults、system.disk.operations、system.network.packets は、単一のデータポイントのみが記録される場合でも複数形化するべきです。

UpDownCounter名の複数形化禁止

UpDownCounterの名前は複数形化するべきではありません（SHOULD NOT）。

例えば、プロセスに関連するすべてのメトリクスを含む名前空間 system.process がある場合、プロセス数を表すには、system.processes の代わりに system.process.count という名前のメトリクスを使えます。 同様に、cicd.pipeline.active_runs よりも cicd.pipeline.run.active が好まれます。

total の非使用

UpDownCounterは _total を使うべきではありません（SHOULD NOT）。使うと単調な合計（sum）のように見えてしまうためです。

Counterも _total を付けるべきではありません（SHOULD NOT）。差分（delta）ベースのバックエンドではその意味が混乱を招くためです。

計測器の命名

ステータス: Development

  • limit - あるものの一定の既知の総量を計測する計測器は entity.limit と呼ぶべきです。 例えば、システム上のメモリの総量を表す system.memory.limit です。

  • usage - 既知の総量（limit）に対して使用された量を計測する計測器は entity.usage と呼ぶべきです。 例えば、state = used | cached | free | ... という属性を持つ system.memory.usage は、各状態にあるメモリ量を表します。 適切な場合、すべての属性値にわたるusageの合計は、limitと等しくなるべきです（SHOULD）。

    制限のないリソース、あるいは制限が知りえないリソースの消費量の計測は、usageとは区別されます。 例えば、プロセスが消費しうる仮想メモリの最大量は時間とともに変動し、通常は既知ではありません。

  • utilization - limitに対するusageの割合を計測する計測器は entity.utilization と呼ぶべきです。 例えば、使用中のメモリの割合を表す system.memory.utilization です。 utilizationは、固定された上限に対しても、ソフトリミットに対しても定義できます。 utilizationの値は比率として表現され、通常は [0, 1] の範囲に収まりますが、ソフトリミットを超えた場合は1より大きくなることがあります。

  • time - 時間の経過を計測する計測器は entity.time と呼ぶべきです。 例えば、state = idle | user | system | ... という属性を持つ system.cpu.time です。 timeの計測値は必ずしもウォールタイムではなく、実際の計測間のウォールタイムより短くも長くもなりえます。

    timeの計測器はusageメトリクスの特殊なケースであり、そのlimitは通常すべての属性値にわたるtimeの合計として計算できます。 timeの計測器におけるutilizationは、メトリクスイベントのタイムスタンプから自動的に導出できます。 例えば system.cpu.utilization は、system.cpu.time の計測値の差分を経過時間とCPU数で割ったものとして定義されます。

  • duration - 操作の実行時間を計測するヒストグラムは {operation name}.duration と呼ぶべきです。 例えば、各HTTPリクエストの処理にかかった時間を表す http.server.request.duration です。 timeとの違いは、timeが単調増加する合計時間の計測に使われるのに対し、durationは個々の操作の経過時間を捉える点です。

  • io - 双方向のデータフローを計測する計測器は entity.io と呼び、方向を示す属性を持つべきです。 例えば system.network.io です。

  • 上記の説明に当てはまらないその他の計測器は、より自由に名前を付けてかまいません。 例えば system.paging.faults や system.network.packets です。 単位は計測器の作成時に含まれるため、名前に含める必要はありませんが、曖昧さがある場合は追加してもかまいません。

クライアントとサーバーのメトリクス

物理的または論理的なネットワーク呼び出しの何らかの側面を計測するメトリクスは、そのメトリクスがどちら側で記録されているかを示すべきです（SHOULD）。

そのようなメトリクスは、与えられた {area} と {metric_name} について通信の側が曖昧な場合、{area}.{client|server}.{metric_name} というパターンに従うべきです（SHOULD）。 一方、与えられた {area} または {metric_name} から通信の側を推測できる場合は、{area}.{metric_name} というパターンを使うべきです（SHOULD）。

例:

  • http.client.request.duration
  • gen_ai.server.request.duration
  • messaging.client.sent.messages
  • messaging.process.duration - process という語が、このメトリクスが消費者によって報告されることを明確に示しています。
  • kestrel.connection.duration - ここでは kestrel がWebサーバーの名前であるため、追加の指示は必要ありません。

システム固有の命名

ステータス: Development

システム（プロジェクト・製品・プロバイダー）名の属性

ある領域のセマンティック規約は通常、複数のシステム（プロジェクト、プロバイダー、製品）に適用可能です。

例えば、データベースのセマンティック規約は、広範なデータベースシステムのテレメトリーを記述するために使えます。

このような規約は、{area}.system|provider|protocol.name というパターンに従って、システム名を表す属性を定義すべきです（SHOULD）。

例えば、データベースの規約には db.system.name 属性が含まれます。

システム名の選択

新しいシステムをセマンティック規約に追加する際は、次の原則に優先度の高い順に従ってください。

  1. システム名は、この文書に記載されている一般的な属性の命名ガイドラインに従うべきです（SHOULD）。システム固有の属性名における名前空間として使われるためです。

  2. システム名は、この特定の製品またはプロジェクトを一意に識別すべきです（SHOULD）。

    例えば、gcp.pubsub や oracle.db を使ってください。 複数のメッセージング製品を指しうる pubsub や、複数のOracle製品を指しうる oracle のような一般的な名前は避けてください。

  3. システム名は、次のような場合には対応するプロジェクトまたは製品の名前と一致すべきです（SHOULD）。

    • kafka や cassandra のような、特定の企業に属さないApache Foundationのプロジェクトなどの独立したプロジェクト。
    • mongodb や elasticsearch のような、所有企業と似た名前を持つ製品。
    • 自社のエコシステムの外でも広く認知されている製品。 これらの製品はしばしば企業名を含まない商標を持ち、独自のトップレベルドメインを持ちます（例: spring や mysql）。

  4. それ以外の場合、システム名には企業（組織、部門、グループ）名を接頭辞として付けるべきです（SHOULD）。 クラウドサービスの場合は、対応するクラウドプロバイダー名を使うべきです（SHOULD）。例えば aws.dynamodb や azure.cosmosdb を使ってください。

    企業（組織、部門、グループ）名は、異なるセマンティック規約の領域にわたる複数の製品名間で一貫させるべきです（SHOULD）。

システム固有の属性

ある属性が特定のシステム（プロジェクト、プロバイダー、製品）に固有である場合、対応する属性名は {system_name}.*.{property} というパターンに従って、システム名で始まるべきです（SHOULD）。

例:

  • cassandra.consistency.level - Cassandraデータベースに固有の整合性レベルのプロパティを表します。
  • aws.s3.key - AWS S3製品の key プロパティを指します。
  • signalr.connection.status - SignalRネットワークプロトコルの接続状態を示します。

*.system.name（または類似の）属性の値は、定義しているシステム固有の属性で使われるルートの名前空間と一致しなければなりません（MUST）。

例えば、cassandra.consistency.level 属性名と db.system.name=cassandra は、同じシステム名（cassandra）を使っています。

システム固有のメトリクス

あるメトリクスが特定のシステム（プロジェクト、プロバイダー、製品）に固有である場合、対応する計測器名は {system_name}.*.{metric_name} というパターンに従って、システム名で始まるべきです（SHOULD）。

例えば azure.cosmosdb.client.operation.request_charge です。

*.system.name（または類似の）属性の値は、システム固有のメトリクスの名前空間と一致しなければなりません（MUST）。

例えば、azure.cosmosdb.client.operation.request_charge メトリクスと db.system.name=azure.cosmosdb 属性は、同じシステム名（azure.cosmosdb）を使っています。

既知の例外

  • OSやプロセスに関連するシステム運用属性・メトリクスは、system.{os} と process.{os} というパターンに従います。

  • RPC とmessagingのセマンティック規約は、まだこのシステム固有の命名ガイダンスに従っておらず、今後1つずつ更新される予定です。