# 動的計装を使用したアプリケーションのデバッグ
Dynamic Instrumentation を使用すると、再起動または再デプロイすることなく、ライブアプリケーションからランタイム状態をキャプチャできます。ランタイム状態には、変数値、メソッド引数、戻り値、スタックトレースが含まれます。コード内のデータをキャプチャする場所を指定する計装設定を定義し、実行中のエージェントはランタイム時にアプリケーションを計測します。
## 概念
ブレークポイント
自動期限切れになる一時的な計装。デフォルトの有効期限は 24 時間で、5 分から 24 時間まで設定できます。デバッグと調査にはブレークポイントを使用します。
プローブ
明示的に削除されるまで保持される永続的な計装。プローブを使用して継続的なオブザーバビリティを実現します。
Snapshot
ローカル変数、引数、戻り値、除外、スタックトレースを含むプログラム状態のポイントインタイムキャプチャ。動的計装は、スナップショットをログレコードとして CloudWatch Logs に出力します。
場所
計装が適用されるコードの場所。必須フィールドは言語によって異なります。
## サポートされている言語
+ Java
+ Python
+ JavaScript または TypeScript
## 前提条件
動的計装を使用するには、デプロイタイプに基づいて計装コンポーネントを最新バージョンに更新します。
+ **Amazon EKS のお客様** — Amazon CloudWatch オブザーバビリティ EKS アドオンを最新バージョンに更新してください。アドオンには ADOT SDK と CloudWatch エージェントが含まれています。詳細については、「[CloudWatch オブザーバビリティ EKS アドオンをインストールする](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html)」を参照してください。
+ **他のすべてのお客様** — 次のコンポーネントの両方を更新してください。
+ ご使用の言語 (Java、Python、または Node.js) の AWS Distro for OpenTelemetry (ADOT) 計装 SDK。
+ CloudWatch エージェントを最新バージョンにします。
さらに次の制約を満たす必要があります。
+ CloudWatch Application Signals は、対象のアプリケーションに対して有効にする必要があります。
+ アプリケーションの環境変数 `OTEL_AWS_DYNAMIC_INSTRUMENTATION_ENABLED=true` を設定します。
+ 環境変数 `OTEL_SERVICE_NAME` をサービス名に設定します。
+ `OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name={{my_deployment_env_name}}` 環境変数を設定します。既存の Application Signals ユーザーの場合、値は Application Signals コンソールに表示されるサービスの環境名と一致する必要があります。
+ CloudWatch Agent は Application Signals 設定で実行されている必要があります。
+ 動的計装は、Lambda 環境ではサポートされていません。
## 動的計装のアプリケーションへの追加
アプリケーションを計装した後 (「[前提条件](#Application-Signals-DI-Prerequisites)」を参照)、コードのどの部分に動的テレメトリを導入するかを指定する計装設定を作成します。各設定では次の 2 つを定義します。
1. **コード内のモニタリング対象位置** — ブレークポイントまたはプローブが適用されるコード位置。
1. **キャプチャするデータ** — ブレークポイントまたはプローブの実行時にキャプチャされたランタイム状態。
**注記**
デフォルトでは、動的計装は制限されたデータのみをキャプチャします。この機能の価値を最大化するには、「[キャプチャ制限](#Application-Signals-DI-Limits)」で説明されているオプションを使用してキャプチャ設定を拡張することを検討してください。
AWS CLI または SDK を使用するか、IDE の AI コーディングアシスタントでモデルコンテキストプロトコル (MCP) サーバーを使用して設定を作成できます。
### CLI または SDK を使用した設定の作成
AWS CLI または AWS SDK を使用して、プログラムで計装設定を作成します。
#### コード位置の指定
この位置は、コード内において計装が適用される位置を定義します。必須フィールドは言語によって異なります。
| 言語 | 必須フィールド | オプションのフィールド |
| --- | --- | --- |
| Java | CodeUnit (パッケージ)、ClassName、MethodName、FilePath | LineNumber |
| Python | CodeUnit (モジュール)、MethodName、FilePath | LineNumber, ClassName |
| JavaScript または TypeScript | FilePath, LineNumber | なし。行レベルのブレークポイントのみがサポートされています。プローブと関数レベルのブレークポイントはサポートされていません。TypeScript は、ソースマップを提供するときにサポートされます。 |
#### キャプチャするデータの設定
キャプチャ設定は、計器の起動時に収集されるランタイム状態を制御します。利用可能なオプション:
+ `CaptureArguments` — キャプチャするメソッド引数名のリスト。
+ `CaptureReturn` — 戻り値 (ブール値) をキャプチャする。
+ `CaptureStackTrace` — スタックトレースをキャプチャする (ブール値)。
+ `CaptureLocals` — キャプチャするローカル変数名のリスト。
+ `CaptureLimits` — キャプチャの深さとサイズを制御する ([キャプチャ制限](#Application-Signals-DI-Limits) を参照)。
#### 設定パラメータ
設定を作成するときの主なパラメータ:
+ `instrumentation-type` - `BREAKPOINT` または `PROBE`
+ `service` — Application Signals によって報告されたサービス名
+ `environment` — 環境名
+ `signal-type` — `SNAPSHOT`
+ `location` — コード位置フィールド (上記を参照)
+ `capture-configuration` — キャプチャオプション (上記を参照)
#### 例
次の例では、Java メソッドのブレークポイントを作成します。
```
aws application-signals create-instrumentation-configuration \
--instrumentation-type BREAKPOINT \
--service "my-service" \
--environment "production" \
--signal-type SNAPSHOT \
--location '{
"CodeLocation": {
"Language": "Java",
"CodeUnit": "com.example.service",
"ClassName": "OrderController",
"MethodName": "processOrder",
"FilePath": "OrderController.java"
}
}' \
--capture-configuration '{
"CodeCapture": {
"CaptureArguments": ["orderId", "user"],
"CaptureReturn": true,
"CaptureStackTrace": true,
"CaptureLimits": {
"MaxHits": 100,
"MaxStringLength": 255,
"MaxCollectionWidth": 20,
"MaxObjectDepth": 3,
"MaxFieldsPerObject": 20,
"MaxStackFrames": 20
}
}
}'
```
### MCP サーバーを使用した設定の作成
動的計装を使用するための推奨アプローチは、CloudWatch Application Signals MCP (モデルコンテキストプロトコル) サーバーを使用することです。MCP を使用すると、IDE 内の AI コーディングアシスタントとエージェントは、動的計装設定の作成と管理とクエリを開発環境から直接行うことができます。
MCP を使用すると、AI アシスタントは以下を実行できます。
+ エディタを離れることなく、特定のコードの場所にブレークポイントとプローブを作成します。
+ キャプチャされたスナップショットをクエリして、ランタイム変数値と呼び出しパスを検査します。
+ スナップショットデータを、修正を提案するために作業中のコードと自動的に関連付けます。
+ 計装設定のライフサイクルを管理します (ステータスの表示、期限切れのブレークポイントの削除)。
セットアップと使用手順については、GitHub ウェブサイトの「[Application Signals MCP サーバー](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)」を参照してください。
## データストレージ
ブレークポイントまたはプローブが起動すると、Dynamic Instrumentation はプレフィックス `/aws/application-signals/{{service-name}}` ({{service-name}} は `OTEL_SERVICE_NAME` 環境変数の値) を使用して CloudWatch Logs にロググループを作成し、キャプチャされたスナップショットをログレコードとしてそのロググループに書き込みます。
ロググループがまだ存在しない場合、動的計装はスナップショットが最初に出力されたときにロググループを自動的に作成します。ログの取り込みと保存には、標準の CloudWatch Logs 料金が請求されます。
## 設定の表示と管理
CloudWatch コンソールで、サービス詳細ページに移動し、**[計装]** タブを選択します。
+ **[ブレークポイント]** と **[プローブ]** を切り替えて、タイプ別に設定を表示します。
+ 説明、キャプチャ設定、場所、ARN、有効期限など、設定の詳細を表示します。
+ ステータス履歴を表示し、[準備完了]から、[アクティブ]、[エラー/無効] までの遷移を追跡します。
+ 不要になった設定を削除します。
## ステータスの理解
各計装設定には、現在の状態を示すステータスがあります。
| ステータス | 説明 |
| --- | --- |
| 準備完了 | エージェントが設定を受け取りました。 |
| アクティブ | エージェントが実行中のアプリケーションに計装を適用しました。 |
| エラー | 計装の適用に失敗しました。詳細についてはエラー原因を参照してください。 |
| 無効 | 計装の有効期限が切れたか、計装を削除しました。 |
計装が ERROR 状態になると、次の原因が報告される可能性があります。
| エラー原因 | 説明 |
| --- | --- |
| FILE\_NOT\_FOUND | 指定されたファイルパスがアプリケーションに存在しません。 |
| METHOD\_NOT\_FOUND | 指定されたメソッドがターゲットのクラスまたはモジュールに存在しません。 |
| LINE\_NOT\_EXECUTABLE | 指定された行番号が実行可能ステートメントに対応していません。 |
| OVERLOADED\_METHODS | 指定された名前と一致するメソッドが複数存在します。正しいメソッドを特定するためにさらに詳しい場所情報を入力してください。 |
| LANGUAGE\_MISMATCH | 場所フィールドが実行中のアプリケーションの言語と一致しません。 |
| RUNTIME\_ERROR | 計装の適用中に不測のエラーが発生しました。 |
## キャプチャ制限
キャプチャ制限は、キャプチャされたデータのサイズと深さを制御する機能です。キャプチャ設定の `capture-limits` フィールドで制限値を設定します。
| 制限 | デフォルト | Range | 説明 |
| --- | --- | --- | --- |
| maxStringLength | 255 | 1～255 | 文字列値ごとにキャプチャされる文字数の上限。 |
| maxCollectionWidth | 20 | 1～20 | コレクションまたは配列ごとにキャプチャされる要素数の上限。 |
| maxObjectDepth | 3 | 1～5 | ネストされたオブジェクトトラバーサルの深度の上限。 |
| maxFieldsPerObject | 20 | 1～20 | オブジェクトごとにキャプチャされるフィールド数の上限。 |
| maxStackFrames | 20 | 1～20 | キャプチャされたスタックフレーム数の上限。 |
| maxHits | 100 | 1～1000 | 自動無効化前のキャプチャ数の上限。ブレークポイントのみ。 |
各計装ポイントは、1 秒あたりのキャプチャが 5 回に制限されます。