SKILL ARTICLE / telemetry-vocabulary-review
観測データの名前と意味を、実装時にそろえる
グラフを増やす前に、名前と意味をそろえる。
リポジトリ内のメトリクス・イベント・属性名を、固定版のOpenTelemetry Semantic Conventionsと社内例外に照らし、意味のずれを根拠付きで報告するSkill案です。
この記事で紹介するSkill案は、参考資料を読んだうえで私が考えたものです。参照先が提供・評価・推奨しているものではありません。
OVERVIEW → CAN DO → BUILD
知ったことをSkillづくりに活かす
共通の語彙はテレメトリを関連づけて利用しやすくするが、仕様内の項目には異なる安定度があり、対象versionと状態を併記する必要がある。
名前だけでなく意味・型・単位・安定度の差を、コード上の場所とともに変更前に確認できる。
同じ仕様内でもStable、Developmentなどの状態が分かれます。Skillには参照したversionと項目ごとの状態を記録させ、Developmentの規則を不変の正解として断定しないようにします。
01 / OVERVIEW
資料の概要
OpenTelemetry Semantic Conventionsは、テレメトリを収集・生成・利用するときに共通の意味を持たせるため、属性、スパン名、メトリクスの種類や単位、名前、型、値などを定義する公式仕様です。共通の命名体系をコードベース、ライブラリ、プラットフォームで使うと、データを関連づけて利用しやすくなると説明されています。
2026年7月28日に確認したversion 1.43.0のNaming文書は、個別に示された箇所を除いてStableです。名前は小文字を基本とし、ドットで名前空間を分け、各要素の複数語にはsnake_caseを使い、曖昧さを避けることが示されています。ただし、同じ文書内でもメトリクスの命名など一部はDevelopmentです。仕様全体を一律に確定済みの規則として扱うことはできません。
02 / CAN DO
できるようになること
OpenTelemetryが提供しているのは共通仕様であり、この記事で考えるリポジトリ監査Skillを提供・評価・推奨しているわけではありません。この記事では、計装コードに書かれたメトリクス、イベント、属性名を抽出し、固定した仕様版の登録済み語彙、命名規則、安定度と照合するSkill案を考えます。
出力には、コード上の場所、現在の名前と意味、対応する公式項目または社内規則、Stable・Developmentなどの状態、差分理由を並べます。適切な公式項目がない場合は、既存のOpenTelemetry名前空間を借用せず、社内用の名前空間候補として分けます。自動で名前を変更するのではなく、ダッシュボードやアラートへの影響を確認できるレビュー材料にします。
活かしやすい場面
- 複数サービスでOpenTelemetryを使っているチーム
- 新しいメトリクスや属性をPRでレビューする場面
- ダッシュボード上で似た名前が増えているリポジトリ
使う前に確認したい場面
- OpenTelemetryを使っていない計装を同仕様だけで正誤判定すること
- 既存のダッシュボードやアラートを調べずに名称を一括変更すること
- Developmentの項目を将来も変わらない規則として固定すること
03 / BUILD
自分たちのSkill作成に活かせること
文章やコードをそのまままねるのではなく、自分たちのSkillに取り入れたい判断基準や工程の分け方を整理しました。
仕様の版と安定度を根拠に含める
同じ仕様内でもStable、Developmentなどの状態が分かれます。Skillには参照したversionと項目ごとの状態を記録させ、Developmentの規則を不変の正解として断定しないようにします。
表記の一致と意味の一致を分ける
小文字やドット区切りに直すだけでは、異なる意味を同じ名前へ寄せる危険があります。名前の形式、値の型、単位、説明、使う信号を別々に確認し、意味を判断できない項目は未確認として返します。
修正案より先に利用箇所を残す
テレメトリ名の変更は、ダッシュボード、アラート、保存済みクエリを壊すことがあります。定義場所だけでなく参照場所も探し、変更候補、互換期間、確認対象を一組にして、人が移行を判断できる出力にします。
04 / WORKFLOW
Skillにするときの流れ
- 01
対象を限定
対象リポジトリ、信号、仕様version、社内規則を確定する。
- 02
語彙を抽出
名前、型、単位、説明、定義場所と参照場所を集める。
- 03
仕様と照合
公式項目、命名規則、安定度を確認し、事実と提案を分ける。
- 04
移行材料を返す
差分理由、影響先、未確認事項を並べ、変更は人の判断に残す。
05 / TRY
試すときに使える依頼文
これは完成したSkillではありません。先に依頼文として試し、期待する結果が返ってくるかを確かめるための試作プロンプトです。
このリポジトリで定義しているメトリクス、イベント、属性名を抽出し、OpenTelemetry Semantic Conventions v1.43.0と社内の命名規則に照らしてください。各項目について、定義場所、現在の名前・型・単位・意味、対応する公式項目と安定度、差分理由、参照場所を示してください。公式項目がないものは誤りと断定せず、社内用名前空間の候補として分けてください。コードは変更しないでください。06 / BUILD BRIEF
試作するときの設計メモ
これは配布済みのSkillではありません。対象を小さく絞り、停止条件と評価ケースを足しながら確かめるための出発点です。
計装コードの語彙をレビューするSkillを作る。
1. 対象リポジトリ、信号、OpenTelemetry Semantic Conventionsのversion、社内規則を入力で固定する。
2. メトリクス、イベント、属性の名前、型、単位、説明、定義場所、参照場所を抽出する。
3. 固定版の公式項目、一般命名規則、項目ごとの安定度と照合する。
4. 一致、意味の不一致、表記のみの不一致、社内規則が必要、未確認に分類する。
5. 出力は根拠URL、コード上の場所、影響先を含め、自動変更は行わない。07 / WATCHOUTS
人が確認するところ
- 本番のテレメトリ値や利用者情報を収集せず、まずコードと設定だけを対象にします。
- 名称変更はダッシュボード、アラート、保存済みクエリへの影響を確認してから行います。
- 仕様のversionと項目ごとの安定度を記録し、Developmentの内容を確定事項として断定しません。