概念支援的語言先決條件將動態檢測新增至您的應用程式資料儲存檢視和管理組態了解狀態擷取限制

使用動態檢測對應用程式進行偵錯

使用動態檢測，您可以從即時應用程式擷取執行期狀態，而無需重新啟動或重新部署。執行期狀態包括變數值、方法引數、傳回值和堆疊追蹤。您可以定義檢測組態，指定程式碼中要擷取資料的位置，而執行中的代理程式會在執行時間檢測應用程式。

概念

中斷點: 自動過期的暫時檢測。預設過期時間為 24 小時，可設定為 5 分鐘到 24 小時。使用中斷點進行偵錯和調查。
探查: 永久檢測會持續存在，直到明確刪除為止。使用探查來持續觀察。
快照: 程式狀態的point-in-time擷取，包括本機變數、引數、傳回值、例外狀況和堆疊追蹤。動態檢測會將快照作為日誌記錄發送到 CloudWatch Logs。
Location: 套用檢測的程式碼位置。必要欄位因語言而異。

支援的語言

Java
Python
JavaScript 或 TypeScript

先決條件

若要使用動態檢測，請根據您的部署類型，將檢測元件更新至最新版本：

Amazon EKS 客戶 — 將 Amazon CloudWatch 可觀測性 EKS 附加元件更新為最新版本。附加元件包含 ADOT SDK 和 CloudWatch Agent。如需詳細資訊，請參閱安裝 CloudWatch 可觀測性 EKS 附加元件。
所有其他客戶 — 更新下列兩個元件：
- 適用於您的語言 (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 環境不支援動態檢測。

將動態檢測新增至您的應用程式

檢測應用程式之後（請參閱先決條件)，您可以建立檢測組態，指定要引入動態遙測的程式碼部分。每個組態定義兩件事：

要監控的程式碼中的位置 — 套用中斷點或探查的程式碼位置。
要擷取的資料 — 執行中斷點或探查時擷取的執行時間狀態。

注意

根據預設，動態檢測只會擷取有限的資料。若要最大化此功能的值，請考慮使用中所述的選項擴展擷取組態擷取限制。

您可以使用 AWS CLI 或 SDK 建立組態，或使用模型內容通訊協定 (MCP) 伺服器搭配 IDE 中的 AI 編碼助理。

使用 CLI 或 SDK 建立組態

使用 AWS CLI 或 AWS SDK 以程式設計方式建立檢測組態。

指定程式碼位置

位置會定義在程式碼中套用檢測的位置。必要欄位因語言而異：

Language	必要欄位	選用欄位
Java	`CodeUnit` （套件）`ClassName`、、`MethodName`、 `FilePath`	`LineNumber`
Python	`CodeUnit` （模組）`MethodName`、、 `FilePath`	`LineNumber`, `ClassName`
JavaScript 或 TypeScript	`FilePath`, `LineNumber`	無。僅支援線路層級中斷點。不支援探查和函數層級中斷點。當您提供來源映射時，支援 TypeScript。

設定要擷取的資料

擷取組態會控制檢測觸發時收集的執行時間狀態。可用選項：

CaptureArguments — 要擷取的方法引數名稱清單。
CaptureReturn — 擷取傳回值（布林值）。
CaptureStackTrace — 擷取堆疊追蹤（布林值）。
CaptureLocals — 要擷取的本機變數名稱清單。
CaptureLimits — 控制擷取深度和大小（請參閱擷取限制)。

組態參數

建立組態時的關鍵參數：

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 伺服器。

資料儲存

當中斷點或探查觸發時，動態檢測會使用字首 /aws/application-signals/service-name（其中 service-name 是您的OTEL_SERVICE_NAME環境變數的值）在 CloudWatch Logs 中建立日誌群組，並將擷取的快照作為日誌記錄寫入該日誌群組。

如果日誌群組尚未存在，Dynamic Instrumentation 會在第一次發出快照時自動建立日誌群組。您需要按標準 CloudWatch Logs 費率支付日誌擷取和儲存的費用。

檢視和管理組態

在 CloudWatch 主控台中，導覽至服務詳細資訊頁面，然後選擇檢測索引標籤。

在中斷點和探查之間切換，依類型檢視組態。
檢視組態詳細資訊，包括描述、擷取組態、位置、ARN 和過期時間。
檢視狀態歷史記錄以追蹤轉換：準備作用中到錯誤/停用。
刪除不再需要的組態。

了解狀態

每個檢測組態都有一個狀態，指出其目前狀態。

狀態	說明
就緒	代理程式收到組態。
ACTIVE	代理程式會將檢測套用至執行中的應用程式。
ERROR	檢測無法套用。如需詳細資訊，請參閱錯誤原因。
DISABLED	檢測已過期，或已將其移除。

當檢測進入 ERROR 狀態時，可能會報告下列原因：

錯誤原因	說明
FILE_NOT_FOUND	指定的檔案路徑不存在於應用程式中。
METHOD_NOT_FOUND	指定的方法不存在於目標類別或模組中。
LINE_NOT_EXECUTABLE	指定的行號未對應至可執行的陳述式。
OVERLOADED_METHODS	多種方法符合指定的名稱。提供其他位置詳細資訊以識別正確的方法。
LANGUAGE_MISMATCH	位置欄位與執行中應用程式的語言不相符。
RUNTIME_ERROR	套用檢測時發生非預期的錯誤。

擷取限制

擷取限制控制擷取資料的大小和深度。在擷取組態的 capture-limits 欄位中設定這些值。

限制	預設	範圍	說明
maxStringLength	255	1–255	每個字串值擷取的字元數上限。
maxCollectionWidth	20	1–20	每個集合或陣列擷取的元素上限。
maxObjectDepth	3	1–5	巢狀物件周遊的最大深度。
maxFieldsPerObject	20	1–20	每個物件擷取的欄位上限。
maxStackFrames	20	1–20	擷取的堆疊影格上限。
maxHits	100	1–1000	自動停用前的擷取上限。僅限中斷點。

每個檢測點的速率限制為每秒 5 次擷取。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

監控服務事件

疑難排解 Application Signals 安裝