動的計装を使用したアプリケーションのデバッグ

Dynamic Instrumentation を使用すると、再起動または再デプロイすることなく、ライブアプリケーションからランタイム状態をキャプチャできます。ランタイム状態には、変数値、メソッド引数、戻り値、スタックトレースが含まれます。コード内のデータをキャプチャする場所を指定する計装設定を定義し、実行中のエージェントはランタイム時にアプリケーションを計測します。

概念

サポートされている言語

前提条件

動的計装を使用するには、デプロイタイプに基づいて計装コンポーネントを最新バージョンに更新します。

さらに次の制約を満たす必要があります。

動的計装のアプリケーションへの追加

アプリケーションを計装した後 (「前提条件」を参照)、コードのどの部分に動的テレメトリを導入するかを指定する計装設定を作成します。各設定では次の 2 つを定義します。

AWS CLI または SDK を使用するか、IDE の AI コーディングアシスタントでモデルコンテキストプロトコル (MCP) サーバーを使用して設定を作成できます。

CLI または SDK を使用した設定の作成

AWS CLI または AWS SDK を使用して、プログラムで計装設定を作成します。

コード位置の指定

この位置は、コード内において計装が適用される位置を定義します。必須フィールドは言語によって異なります。

キャプチャするデータの設定

キャプチャ設定は、計器の起動時に収集されるランタイム状態を制御します。利用可能なオプション:

設定パラメータ

設定を作成するときの主なパラメータ:

例

次の例では、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 サーバー」を参照してください。

データストレージ

ブレークポイントまたはプローブが起動すると、Dynamic Instrumentation はプレフィックス /aws/application-signals/service-name (service-name は OTEL_SERVICE_NAME 環境変数の値) を使用して CloudWatch Logs にロググループを作成し、キャプチャされたスナップショットをログレコードとしてそのロググループに書き込みます。

ロググループがまだ存在しない場合、動的計装はスナップショットが最初に出力されたときにロググループを自動的に作成します。ログの取り込みと保存には、標準の CloudWatch Logs 料金が請求されます。

設定の表示と管理

CloudWatch コンソールで、サービス詳細ページに移動し、[計装] タブを選択します。

ステータスの理解

各計装設定には、現在の状態を示すステータスがあります。

計装が ERROR 状態になると、次の原因が報告される可能性があります。

キャプチャ制限

キャプチャ制限は、キャプチャされたデータのサイズと深さを制御する機能です。キャプチャ設定の capture-limits フィールドで制限値を設定します。

各計装ポイントは、1 秒あたりのキャプチャが 5 回に制限されます。