otel-semantic-conventions

OpenTelemetry セマンティック規約

このスキルは、OpenTelemetry セマンティック規約の仕様に従って、テレメトリー属性とメトリクス計測器を適切に選択、配置、検証するためのものです。 スパン名、スパン種別、スパンステータスコードについては、otel-instrumentation スキルを参照してください。

属性レジストリは、定義済みのすべての属性の唯一の情報源です。

ルール

ルール	説明	ユースケース
attributes	属性レジストリ、選択、配置、ドメイン別の共通属性	属性の選択またはレビュー、HTTP／DB／メッセージング／RPC 属性、属性の配置（リソースとスパン）
versioning	Semconv のバージョン管理、安定性、移行	Semconv のバージョン移行
dash0	Dash0 の派生属性と機能依存関係	Dash0 の派生属性

公式ドキュメント

• 属性レジストリ
• セマンティック規約の仕様
• セマンティック規約リポジトリ
• Dash0 セマンティック規約
• Dash0 セマンティック規約の解説

適切な属性の選び方

1. まずレジストリを検索する — 属性レジストリで概念を検索します。標準名が存在する場合は、それを使用してください（例：カスタムの custom.http.verb より http.request.method を優先します）。カスタム名はクエリを分断し、ツールの動作を妨げます。概念に該当するレジストリエントリがない場合に限り、カスタム属性を作成してください。
2. 安定性を確認する — stable 属性を優先し、変更される可能性のある experimental 属性があれば留意してください。versioning を参照してください。
3. 適切なレベルに配置する — リソース属性はテレメトリーを生成するエンティティを記述し、スパン／ログ属性は個々の操作を記述します。レベルをまたいで重複させないでください。属性を特定のレベルに配置したら、すべてのサービスで一貫してそのレベルに配置してください。
4. カーディナリティを確認する — メトリクス属性の値は、カーディナリティの低い（範囲が限定された）値にする必要があります。変動するデータ（ユーザー ID、パラメーター付きのリクエストパス）は、メトリクス属性ではなくスパン属性に含めてください。
5. カスタム属性は最後の手段とする — 概念に該当するレジストリエントリがない場合に限り、カスタム属性を作成してください。判断の根拠を記録し、org.namespace.attribute_name の命名パターンに従ってください。

例：適切な属性選択と不適切な属性選択

# Correct — uses registry attribute for HTTP method
span.set_attribute("http.request.method", "GET")

# Incorrect — invents a custom attribute for a concept already in the registry
span.set_attribute("custom.http.verb", "GET")

例：リソース属性とスパン属性の配置

# Correct — service identity is a resource attribute
resource = Resource({"service.name": "checkout-service", "service.version": "2.1.0"})

# Correct — operation-specific data is a span attribute
span.set_attribute("http.request.method", "POST")
span.set_attribute("http.response.status_code", 201)

# Incorrect — placing a resource-level attribute on every span
span.set_attribute("service.name", "checkout-service")  # belongs on the resource

例：メトリクス属性におけるカーディナリティ違反

# Correct — metric attribute uses a bounded, low-cardinality value
histogram.record(duration_ms, {"http.request.method": "GET", "http.response.status_code": 200})

# Incorrect — unbounded values as metric attributes explode storage and query cost
histogram.record(duration_ms, {"user.id": "u-839201", "url.path": "/orders/839201"})
# Fix: move high-cardinality values to span attributes instead
span.set_attribute("user.id", "u-839201")
span.set_attribute("url.path", "/orders/839201")