183-java-observability-tracing-opentelemetry について
Java 開発者向けに、OpenTelemetry による分散トレーシングの実装を支援するスキルです。アプリケーションとインフラの経路を対象に、スパン設計、コンテキスト伝播、プライバシー保護属性、サンプリング、エンドツーエンド検証を扱います。
主な機能
- 01OpenTelemetry トレーシングの基礎
- 02スパン境界と命名
- 03非同期経路のコンテキスト伝播
- 04セマンティック規約と属性
- 05サンプリングとプライバシー制御
- 06トレースのテストと検証
活用シーン
- 01Java サービスへのトレーシング追加
- 02HTTP とメッセージ間のコンテキスト伝播
- 03スパン内の機密情報や高カーディナリティデータの確認
- 04テストでトレースの連続性を検証
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/183-java-observability-tracing-opentelemetryを入力して読み込まれたか確認します。
同梱ファイルreferences/183-java-observability-tracing-opentelemetry.md
詳細
OpenTelemetry を使用した Java 分散トレーシング
意味のあるスパンをモデル化し、コンテキスト伝搬を維持し、重要なビジネス処理およびインフラストラクチャの経路を低オーバーヘッドかつプライバシーに配慮したテレメトリーで計装することで、Java における堅牢な分散トレーシングを実装します。
このスキルの対象範囲
- Java サービスにおける OpenTelemetry トレーシングの基礎
- スパンの設計：境界、親子関係、操作名
- HTTP、メッセージング、非同期タスク、スレッド境界をまたぐコンテキスト伝搬
- セマンティック規約と安定した属性名
- エラー、ステータス、イベントの記録に関するベストプラクティス
- サンプリング戦略とパフォーマンス／コストのトレードオフ
- トレース属性のプライバシーおよびセキュリティ制御
- トレース伝搬とスパンの正確性のテストおよび検証
範囲： 診断容易性、一貫性、運用上の安全性に重点を置いた、アプリケーション層および統合層における分散トレーシングの品質です。
制約
トレーシングの計装では、コンテキストを正しく伝搬し、機密データの漏えいを防ぐ必要があります。過剰な計装やカーディナリティの高い属性は、コストとシグナル品質に悪影響を及ぼす可能性があります。
- 伝搬を最優先：追加のスパン詳細を加える前に、すべての同期／非同期境界でコンテキストが伝搬されることを確認します
- 機密データを含めない：シークレット、認証情報、トークン、生のペイロード、PII をスパン属性／イベントに保存しないでください
- カーディナリティの低い属性を使用：集計／検索に使用する属性では、上限のない値を避けます
- 検証：トレーシングの変更を適用した後、
./mvnw clean verifyまたはmvn clean verifyを実行します
このスキルを使用する場面
- トレーシングを改善する
- OpenTelemetry トレーシングを適用する
- 分散トレーシングを追加する
- トレーシングの計装をリファクタリングする
- OpenTelemetry のスパンを使用して Java サービスを計装する
ワークフロー
- トレースモデルと重要なフローを定義する
価値の高いリクエストおよび非同期フローを特定し、操作の境界を定義して、セマンティック規約に沿ったスパン名／属性を選択します。
- 計装してコンテキストを伝搬する
重要な境界に OpenTelemetry のスパンを追加し、HTTP クライアント／サーバー、メッセージング、エグゼキューターを使用する非同期処理をまたいでトレースコンテキストが伝搬されるようにします。
- スパンデータとサンプリングを強化する
ステータス／エラー／イベントを一貫して記録し、機密データを削除して属性のカーディナリティを制御し、環境の要件に応じてサンプリング／エクスポーターを設定します。
- エンドツーエンドでトレースを検証する
テストと実行時チェックを通じて、親子関係、伝搬の継続性、バックエンドでの可視性を確認します。
リファレンス
詳細なガイダンス、例、制約については、references/183-java-observability-tracing-opentelemetry.md を参照してください。