otel-semantic-conventions

OpenTelemetry セマンティック規約

命名、属性、コンプライアンスチェックについて、リリース済みのセマンティック規約に関するガイダンスが必要な場合に、このスキルを使用します。

ワークフロー

1. モデルの記憶ではなく、リリース済みのセマンティック規約から始めます。

• セマンティック規約の仕様全体をコンテキストに読み込まないでください
• バンドルされている検索スクリプトを使い、必要なリリース済みのグループまたは属性だけを検索してください
• チェックアウト済みの上流リポジトリに対してローカルで検証する場合は、OTEL_SEMCONV_REPO=/path/to/semantic-conventions を設定してください

2. カスタムキーを作る前に、最も近いリリース済みのグループを選びます。

• http、db、messaging、rpc、network などの境界の種類を特定します
• まず主要なグループを1つ選び、必要なコンテキストを追加する場合にのみ関連グループを加えます
• gen_ai.*、OpenAI、または MCP の規約については、open-telemetry/semantic-conventions-genai を使用してください。2026-10-25時点でタグ付きリリースがないため、コミットを明記し、ガイダンスが未リリースであることを示してください（検索スクリプトの対象外です）。コアリポジトリには、v1.42.0以降、非推奨となったGenAI時代のスタブのみが残されています
• references/semconv-selection.md を参照してください
• 言語の semconv パッケージが実際に公開しているバージョンを対象にする場合（オフラインで動作し、日付が付いています）は、references/sdk-semconv-packages.md を参照してください

3. 必要なリリース済みのガイダンスのみを検索します。

• グループ一覧：./scripts/query-otel-semantic-conventions.sh --groups
• グループの確認：./scripts/query-otel-semantic-conventions.sh http
• 種類の確認：./scripts/query-otel-semantic-conventions.sh http spans
• 特定の属性または項目の確認：./scripts/query-otel-semantic-conventions.sh http http.request.method
• references/otel-semantic-conventions.md を参照してください
• パーサーを変更した後は、OTEL_SEMCONV_REPO=/path/to/semantic-conventions bash ./scripts/test-query-otel-semantic-conventions.sh を実行してください

4. リリース済みの命名規則と属性規則をそのまま適用します。

• オプションの属性より先に、必須属性と推奨属性を使用してください
• semconv によって規定されるスパン名は、リリース済みの命名規則から直接導出してください
• semconv によって規定されるスパン名の前後に、プロトコルのラベル、ホスト名、製品名、ビジネス上のヒント、その他の独自の説明を追加しないでください
• リリース済みの命名規則にカーディナリティの低い対象が示されていない場合は、その規約で許可される、よりシンプルな代替案を使用してください
• リリース済みのキーが存在しない場合は、安定したカスタム名前空間を使用し、値の範囲を限定してください

5. 出典のコンテキストを正確に添えて結果を返します。

• スクリプトの出力に含まれるグループ名、リリースバージョン、ソース URL を記載してください
• 実装がリリース済みのガイダンスに完全には準拠できない場合は、具体的な互換性の制限を明記してください