本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用動態檢測對應用程式進行偵錯
<a name="CloudWatch-Application-Signals-DynamicInstrumentation"></a>

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

## 概念
<a name="Application-Signals-DI-Concepts"></a>

中斷點  
自動過期的暫時檢測。預設過期時間為 24 小時，可設定為 5 分鐘到 24 小時。使用中斷點進行偵錯和調查。

探查  
永久檢測會持續存在，直到明確刪除為止。使用探查來持續觀察。

快照  
程式狀態的point-in-time擷取，包括本機變數、引數、傳回值、例外狀況和堆疊追蹤。動態檢測會將快照作為日誌記錄發送到 CloudWatch Logs。

Location  
套用檢測的程式碼位置。必要欄位因語言而異。

## 支援的語言
<a name="Application-Signals-DI-Languages"></a>
+ Java
+ Python
+ JavaScript 或 TypeScript

## 先決條件
<a name="Application-Signals-DI-Prerequisites"></a>

若要使用動態檢測，請根據您的部署類型，將檢測元件更新至最新版本：
+ **Amazon EKS 客戶** — 將 Amazon CloudWatch 可觀測性 EKS 附加元件更新為最新版本。附加元件包含 ADOT SDK 和 CloudWatch Agent。如需詳細資訊，請參閱[安裝 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 環境不支援動態檢測。

## 將動態檢測新增至您的應用程式
<a name="Application-Signals-DI-Add"></a>

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

1. **要監控的程式碼中的位置** — 套用中斷點或探查的程式碼位置。

1. **要擷取的資料** — 執行中斷點或探查時擷取的執行時間狀態。

**注意**  
根據預設，動態檢測只會擷取有限的資料。若要最大化此功能的值，請考慮使用中所述的選項擴展擷取組態[擷取限制](#Application-Signals-DI-Limits)。

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

### 使用 CLI 或 SDK 建立組態
<a name="Application-Signals-DI-Create"></a>

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

#### 指定程式碼位置
<a name="Application-Signals-DI-Create-Location"></a>

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


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

#### 設定要擷取的資料
<a name="Application-Signals-DI-Create-Capture"></a>

擷取組態會控制檢測觸發時收集的執行時間狀態。可用選項：
+ `CaptureArguments` — 要擷取的方法引數名稱清單。
+ `CaptureReturn` — 擷取傳回值 （布林值）。
+ `CaptureStackTrace` — 擷取堆疊追蹤 （布林值）。
+ `CaptureLocals` — 要擷取的本機變數名稱清單。
+ `CaptureLimits` — 控制擷取深度和大小 （請參閱 [擷取限制](#Application-Signals-DI-Limits))。

#### 組態參數
<a name="Application-Signals-DI-Create-Params"></a>

建立組態時的關鍵參數：
+ `instrumentation-type` — `BREAKPOINT`或 `PROBE`
+ `service` — Application Signals 報告的服務名稱
+ `environment` — 環境名稱
+ `signal-type` — `SNAPSHOT`
+ `location` — 程式碼位置欄位 （請參閱上述）
+ `capture-configuration` — 擷取選項 （請參閱上述）

#### 範例
<a name="Application-Signals-DI-Create-Example"></a>

下列範例會在 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 伺服器建立組態
<a name="Application-Signals-DI-MCP"></a>

使用動態檢測的建議方法是透過 CloudWatch Application Signals MCP （模型內容通訊協定） 伺服器。MCP 可讓 IDE 中的 AI 編碼助理和客服人員直接從開發環境建立、管理和查詢動態檢測組態。

使用 MCP，您的 AI 助理可以：
+ 在特定程式碼位置建立中斷點和探查，而不離開編輯器。
+ 查詢擷取的快照，以檢查執行時間變數值和呼叫路徑。
+ 自動將快照資料與您正在處理的程式碼建立關聯，以建議修正。
+ 管理檢測組態的生命週期 （檢視狀態、刪除過期的中斷點）。

如需設定和使用說明，請參閱 GitHub 網站上的 [Application Signals MCP 伺服器](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。

## 資料儲存
<a name="Application-Signals-DI-DataStorage"></a>

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

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

## 檢視和管理組態
<a name="Application-Signals-DI-Manage"></a>

在 CloudWatch 主控台中，導覽至服務詳細資訊頁面，然後選擇**檢測**索引標籤。
+ 在**中斷點**和**探查**之間切換，依類型檢視組態。
+ 檢視組態詳細資訊，包括描述、擷取組態、位置、ARN 和過期時間。
+ 檢視狀態歷史記錄以追蹤轉換：準備作用中到錯誤/停用。
+ 刪除不再需要的組態。

## 了解狀態
<a name="Application-Signals-DI-Status"></a>

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


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

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


| 錯誤原因 | 說明 | 
| --- | --- | 
| FILE\_NOT\_FOUND | 指定的檔案路徑不存在於應用程式中。 | 
| METHOD\_NOT\_FOUND | 指定的方法不存在於目標類別或模組中。 | 
| LINE\_NOT\_EXECUTABLE | 指定的行號未對應至可執行的陳述式。 | 
| OVERLOADED\_METHODS | 多種方法符合指定的名稱。提供其他位置詳細資訊以識別正確的方法。 | 
| LANGUAGE\_MISMATCH | 位置欄位與執行中應用程式的語言不相符。 | 
| RUNTIME\_ERROR | 套用檢測時發生非預期的錯誤。 | 

## 擷取限制
<a name="Application-Signals-DI-Limits"></a>

擷取限制控制擷取資料的大小和深度。在擷取組態的 `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 次擷取。