distributed-tracing
支持分散追踪设计和OpenTelemetry集成技能。体系化追踪结构、跨度设计和验证流程。锚点:• 可观测性工程 / 适用:观测设计 / 目标:确保可观测性一致性• W3C追踪上下文 / 适用:上下文传播 / 目标:遵循标准• OpenTelemetry / 适用:测量和导出 / 目标:实现供应商无关性触发:在设计追踪结构、实施OpenTelemetry工具或验证跨度传播时使用。
name: distributed-tracing description: | 分散トレーシングの設計とOpenTelemetry導入を支援するスキル。 トレース構造、スパン設計、検証手順を体系化する。
Anchors: • Observability Engineering / 適用: 観測設計 / 目的: 可観測性の一貫性確保 • W3C Trace Context / 適用: コンテキスト伝播 / 目的: 標準準拠 • OpenTelemetry / 適用: 計測とエクスポート / 目的: ベンダー非依存化
Trigger: Use when designing trace structures, implementing OpenTelemetry instrumentation, or validating span propagation. distributed tracing, opentelemetry, span, trace context, w3c allowed-tools: - Read - Write - Edit - Bash - Glob - Grep
distributed-tracing
概要
分散トレーシングの設計から検証までを整理し、OpenTelemetry導入を支援する。
ワークフロー
Phase 1: 要件整理
目的: トレーシングの目的とスコープを明確化する。
アクション:
references/Level1_basics.mdで基本概念を確認する。assets/tracing-requirements-template.mdで要件を整理する。references/requirements-index.mdで要件整合を確認する。
Task: agents/analyze-tracing-requirements.md を参照
Phase 2: トレース設計
目的: トレース構造とスパン設計を定義する。
アクション:
references/trace-structure-design.mdで構造設計を確認する。references/span-design-guide.mdでスパン設計を整理する。assets/span-naming-checklist.mdで命名観点を揃える。
Task: agents/design-trace-structure.md を参照
Phase 3: 実装と計測準備
目的: 実装方針と計測設定を整備する。
アクション:
references/w3c-trace-context.mdで伝播仕様を確認する。assets/tracing-config.tsを参照して設定を整理する。- 実装方針メモを作成する。
Task: agents/implement-instrumentation-plan.md を参照
Phase 4: 検証と運用
目的: トレース構造の検証と記録を行う。
アクション:
scripts/analyze-trace.mjsで検証する。assets/trace-evaluation-template.mdで評価を整理する。scripts/log_usage.mjsで記録を更新する。
Task: agents/validate-tracing-setup.md を参照
Task仕様ナビ
| Task | 起動タイミング | 入力 | 出力 |
|---|---|---|---|
| analyze-tracing-requirements | Phase 1開始時 | 目的/制約 | 要件メモ、スコープ整理 |
| design-trace-structure | Phase 2開始時 | 要件メモ | トレース設計、命名方針 |
| implement-instrumentation-plan | Phase 3開始時 | 設計方針 | 実装方針、計測設定 |
| validate-tracing-setup | Phase 4開始時 | 実装方針 | 検証レポート、改善提案 |
詳細仕様: 各Taskの詳細は agents/ ディレクトリを参照
ベストプラクティス
すべきこと
| 推奨事項 | 理由 |
|---|---|
| スパン命名を統一する | 可視化の精度が上がる |
| 伝播仕様を明文化する | 断絶を防ぐ |
| サンプリングを定義する | 負荷を制御できる |
| 検証結果を記録する | 改善が継続する |
避けるべきこと
| 禁止事項 | 問題点 |
|---|---|
| 目的不明の計測 | ノイズが増える |
| 伝播忘れ | トレースが分断される |
| 全量収集のみ | 本番負荷が高い |
リソース参照
scripts/(決定論的処理)
| スクリプト | 機能 |
|---|---|
scripts/analyze-trace.mjs |
トレース構造分析 |
scripts/log_usage.mjs |
使用記録と評価メトリクス更新 |
scripts/validate-skill.mjs |
スキル構造の検証 |
references/(詳細知識)
| リソース | パス | 読込条件 |
|---|---|---|
| レベル1 基礎 | references/Level1_basics.md | 要件整理時 |
| レベル2 実務 | references/Level2_intermediate.md | 設計時 |
| レベル3 応用 | references/Level3_advanced.md | 実装時 |
| レベル4 専門 | references/Level4_expert.md | 改善時 |
| トレース設計 | references/trace-structure-design.md | 構造設計時 |
| スパン設計 | references/span-design-guide.md | スパン設計時 |
| Trace Context | references/w3c-trace-context.md | 伝播設計時 |
| 要求仕様索引 | references/requirements-index.md | 仕様確認時 |
| 旧スキル | references/legacy-skill.md | 互換確認時 |
assets/(テンプレート・素材)
| アセット | 用途 |
|---|---|
assets/tracing-requirements-template.md |
要件整理テンプレート |
assets/span-naming-checklist.md |
スパン命名チェック |
assets/trace-evaluation-template.md |
検証テンプレート |
assets/tracing-config.ts |
設定サンプル |
運用ファイル
| ファイル | 目的 |
|---|---|
EVALS.json |
レベル評価・メトリクス管理 |
LOGS.md |
実行ログの蓄積 |
CHANGELOG.md |
改善履歴の記録 |