telemetry-foundations

テレメトリーの基礎

概要

HVE Core のエージェント間でオブザーバビリティに関する用語を統一します。このスキルでは、テレメトリーデータの種類とその命名方法について説明します。使用する SDK やベンダーは対象ではありません。計画成果物（ADR、PRD、セキュリティ／RAI 計画、コードレビュー報告書）を作成するエージェントと、ユーザー向けアプリケーションコードを作成するエージェントがこのスキルを参照することで、後続のパイプライン（トレース、メトリクス、ログ）で OpenTelemetry に準拠した一貫性のある用語を使用できます。

適用する状況

次の状況でこのスキルを適用します。

• スパン、メトリクス、または構造化ログを出力するユーザー向けアプリケーションコードを作成するエージェント。
• オブザーバビリティ、モニタリング、監査ログに関するアーキテクチャ決定記録。
• テレメトリーの不足、一貫性のないスパン名、または上限のないメトリクスのカーディナリティを指摘するコードレビュー報告書。
• 監査ログ、トレーサビリティ、または証拠の連鎖に言及するセキュリティまたは責任ある AI の計画。
• サービステレメトリーで表現される成功指標を定める製品またはビジネス要件文書。

基本原則

このスキルの用語は、次の 5 つの原則に従います。

• 規定的ではなく、宣言的であること。名前と形式を定義し、SDK、エクスポーター、バックエンドの選択は実装チームに委ねます。
• OpenTelemetry に準拠していること。トレース、メトリクス、ログのモデルには OTel のデータモデルを採用し、成果物のポータビリティを保ちます。
• セマンティック規約を優先すること。ドメイン（HTTP、RPC、データベース、メッセージング、GenAI、FaaS）に OTel のセマンティック規約が存在する場合は、独自の属性よりもそちらを優先します。
• PII はデニーリスト方式で扱うこと。references/pii-denylist.md のデニーリストに従い、PII は既定で拒否します。リストに記載されたフィールドを出力するには、明示的な秘匿化戦略が必要です。
• ベンダーに依存しないこと。用語を単一のバックエンドに結び付けないようにします。ワイヤープロトコルには OTLP を想定します。

トレースの用語

スパンは、作業単位と他の作業との因果関係を表します。

スパンの種類：

• server - このサービスが処理する受信リクエスト。
• client - このサービスが発行する送信リクエスト。
• producer - キューまたはトピックにパブリッシュされる非同期メッセージ。
• consumer - キューまたはトピックから受信する非同期メッセージ。
• internal - リモートピアを持たないプロセス内の操作。

すべてのスパンで必須のリソーススコープ属性：

• service.name
• service.version
• deployment.environment

スパン名のパターン：小文字のトークンをドットで区切った <verb>.<resource>。動詞は操作（get、create、publish、consume、query）を表し、リソースは対象のエンティティ（order、customer、payment.intent）を表します。例：get.order、publish.order.created、query.customer.by_email。

OTel のセマンティック規約があるドメイン（HTTP、RPC、データベース、メッセージング、GenAI、FaaS）では、上記の汎用パターンではなく、その規約のスパン命名ガイダンスを使用します。

メトリクスの用語

メトリクスは、時間の経過に伴う集約測定値を表します。

計測器の種類：

• counter - 単調増加し、加算可能です（リクエスト数、送信バイト数）。
• up-down-counter - 単調ではなく、加算可能です（キューの深さ、アクティブな接続数）。
• histogram - 値の分布を表します（リクエスト時間、ペイロードサイズ）。
• gauge - 最後にサンプリングされた値で、加算できません（CPU 温度、使用中のメモリ）。
• observable-counter、observable-up-down-counter、observable-gauge - SDK がポーリングする非同期版です。

単位の規約はUCUMに準拠します。例：s（秒）、ms（ミリ秒）、By（バイト）、1（無次元の数）。OTel の HTTP セマンティック規約に合わせるため、期間はデフォルトで秒（s）単位のヒストグラムとして表します。

メトリクスの命名パターン：小文字のトークンをドットで区切った <domain>.<entity>.<measure>。例：http.server.request.duration、db.client.connections.usage、messaging.publish.duration。

カーディナリティの管理：メトリクスに付与される属性はそれぞれ、時系列の数を増加させます。カーディナリティの高いディメンション（ユーザー ID、リクエスト ID、自由形式の文字列）は、発生元で上限を設けるか、エグザンプラーやトレースに移してください。

ログの用語

構造化ログには、重大度とコンテキストを伴う個別のイベントが記録されます。

重大度レベル（OTel ログデータモデル）：

• TRACE - 詳細な診断情報。デフォルトでは無効です。
• DEBUG - 開発中に役立つ診断情報です。
• INFO - 通常の運用イベントです。
• WARN - 操作を妨げない予期しない状態です。
• ERROR - 操作が失敗し、呼び出し元にも失敗が通知された可能性があります。
• FATAL - プロセスが終了しようとしています。

すべてのログレコードに推奨される構造化フィールド：

• timestamp（ISO-8601、UTC）。
• severity_text と severity_number。
• body（人が読めるメッセージ。構造化データは attributes に格納します）。
• attributes.*（このイベントに対応する型付きのキーと値のペア）。
• resource.*（生成元のサービスから継承されます）。

トレースとの相関：アクティブなスパン内でログレコードを出力する場合は、trace_id と span_id を挿入して、下流でトレースとログを適切に関連付けられるようにします。OTel のコンテキストプロパゲーターと連携するロギングライブラリでは、これが自動的に行われます。

PII の取り扱い

個人を特定できる情報（PII）は、拒否リストに基づいて取り扱います。正規のリストは references/pii-denylist.md にあります。このリストにあるフィールドは、デフォルトで拒否対象として扱ってください。明示的なマスキング戦略がない限り、スパン属性、メトリクスのディメンション、ログフィールドとして出力してはいけません。

マスキングパターン：

• ハッシュ化 - イベント間で関連付けられる状態を保ちつつ、人が読み取れないようにする必要があるフィールドには、一方向ハッシュ（SHA-256。必要に応じて切り詰め）を使用します。
• 破棄 - フィールドを完全に省略します。
• トークン化 - 別のアクセス制御されたストアを通じてのみ解決できる、不透明なトークンに置き換えます。

識別子の規約：テレメトリで安定したユーザー参照が必要な場合は、正規のユーザー識別子を不透明なハッシュにした値を user.id に使用し、生のメールアドレス、電話番号、外部アカウント ID は決して使用しないでください。

PII を含む可能性がある新しい属性を導入する場合は、まず拒否リストに追加し、出力する前にマスキング戦略を選択してください。

サンプリングとコスト

サンプリングは、下流のコレクターに送信されるテレメトリの量を制御します。

サンプリング戦略：

• ヘッドベース - スパンの開始時に決定し、その判断をトレース全体に伝播させます。低コストでシンプルですが、後から判明する特性（エラーなど）を基準に選別できません。
• テールベース - トレースの完了後、通常はコレクターで決定します。コストは高くなりますが、「すべてのエラートレースを保持する」「遅いトレースを保持する」といったポリシーを設定できます。

デフォルト：

• 親ベースのサンプラーを使用し、子スパンが親のサンプリング判断を継承することで、トレース全体を保持します。
• テールベースのサンプリングが利用できる場合は、エラートレースと、成功したトレースの代表的なサンプルを優先して保持します。

メトリクスとログのサンプリング：メトリクスは事前に集計されるため、サンプリングされることはほとんどありません。ログは通常、サンプリングではなく重大度ごとのレート制限を行います。

リソース属性

リソース属性は、テレメトリーを生成するエンティティを記述し、SDK によってすべてのスパン、メトリクス、ログレコードに自動的に付与されます。

必須：

• service.name
• service.version
• deployment.environment
• telemetry.sdk.name
• telemetry.sdk.language
• telemetry.sdk.version

該当する場合に推奨：

• cloud.*（クラウドプロバイダー、リージョン、アカウント ID）。
• k8s.*（クラスター名、名前空間、ポッド名）。
• host.*（ホスト名、アーキテクチャ、OS タイプ）。

正規の属性名については、OTel のリソースのセマンティック規約に従ってください。

判断フロー

計装するかどうか、またどのように計装するかを選ぶ際は、次の簡易フローを使用してください。

1. ユーザー向け、またはユーザーに表示されるフローの一部ですか？ いいえの場合は、DEBUG ログを優先し、キャパシティプランニングに必要な場合を除いてスパンやメトリクスの出力を省略してください。
2. 提案する属性のカーディナリティは制限されていますか？ いいえの場合は、無制限のフィールドをメトリクスのディメンションではなく、ログ属性またはトレースのエグザンプラーに移してください。
3. データに references/pii-denylist.md のフィールドが含まれている、またはそのフィールドから派生していますか？ はいの場合は、出力前に秘匿化の方針を適用してください。
4. 操作はサービス境界（ネットワーク、キュー、プロセス）をまたぎますか？ はいの場合は、対応する server、client、producer、または consumer の種類でスパンを出力し、コンテキストを伝搬してください。
5. 操作のボリュームは大きいですか？ はいの場合は、親ベースのサンプリングと（利用可能な場合は）テールベースのポリシーを利用してください。計装そのものを無効にしないでください。
6. OpenTelemetry のセマンティック規約でこのドメインが扱われていますか？ はいの場合は、その属性名とスパン命名の指針を使用してください。いいえの場合は、このスキルの命名パターンに従い、references/proposed-additions.md に新しい項目を提案してください。

参考資料

権威ある外部資料：

• OpenTelemetry セマンティック規約 v1.41.0
• W3C トレースコンテキスト
• OpenTelemetry プロトコル（OTLP）仕様
• OpenTelemetry ログデータモデル
• OpenTelemetry FaaS セマンティック規約

一部は OpenTelemetry セマンティック規約を基に改変しています。（C）OpenTelemetry Authors、ライセンス：CC BY 4.0。

内部資料：

• references/pii-denylist.md - 秘匿化の方針を含む、正式な PII 拒否リスト。
• references/proposed-additions.md - 新しい用語の提案を受け付ける場所。