本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 對失敗的 Canary 進行故障診斷
如果 Canary 失敗，請檢查以下內容進行故障診斷。
**一般性問題的故障診斷**
+ 使用 Canary 詳細資訊頁面來尋找更多資訊。在 CloudWatch 主控台中，選擇導覽窗格中的 ** Canary**，然後選擇 Canary 的名稱以開啟 Canary 詳細資訊頁面。在**可用性**索引標籤中，檢查 ** SuccessPercent** 指標，以查看問題是持續還是間歇性。
依然在 **Availability** (可用性) 標籤上，選擇失敗的資料點，以查看該失敗執行的螢幕擷取畫面、日誌和步驟報告 (如可用)。
如果因為步驟屬於指令碼的一部分而提供步驟報告，請檢查哪個步驟失敗，並查看相關的螢幕擷取畫面，以查看客戶看到的問題。
您也可以檢查 HAR 檔案，以查看是否有一或多個請求失敗。您可以使用日誌來深入探索失敗的請求和錯誤。最後，您可將這些成品與成功的金絲雀部署執行的成品進行比較，以確定問題。
根據預設，CloudWatch Synthetics 會擷取 UI Canary 中每個步驟的螢幕擷取畫面。不過，您的指令碼可能會設定為停用螢幕擷取畫面。在偵錯期間，您可能想要再次啟用螢幕擷取畫面。同樣，對於 API Canary，您可能希望在偵錯過程中查看 HTTP 請求和回應標頭與內文。如需如何在報告內包含此資料的相關資訊，請參閱 [executeHttpStep(stepName, requestOptions, [callback], [stepConfig])](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_executeHttpStep)。
+ 如果您最近有部署到您的應用程式，請將其轉返，然後稍後再進行偵錯。
+ 手動連接到您的端點，看看是否可以重現相同的問題。
**Topics**
+ [Canary 在 Lambda 環境更新後失敗](#Troubleshoot_upgradeLambda)
+ [我的 Canary 被 封鎖 AWS WAF](#Canary_Blocked_WAF)
+ [等待元素出現](#CloudWatch_Synthetics_Canaries_Troubleshoot_waiting)
+ [節點不可見或不是 page.click() 的 HTMLElement](#CloudWatch_Synthetics_Canaries_Troubleshoot_notvisible)
+ [無法上傳成品到 S3，例外狀況：無法擷取 S3 儲存貯體位置：拒絕存取](#CloudWatch_Synthetics_Canaries_Troubleshoot_noupload)
+ [錯誤：通訊協定錯位 (Runtime.callFunctionOn)：目標關閉。](#CloudWatch_Synthetics_Canaries_Troubleshoot_protocolError)
+ [Canary 失敗。錯誤：沒有資料點 - Canary 顯示逾時錯誤](#CloudWatch_Synthetics_Canaries_Troubleshoot_nodatapoint)
+ [嘗試存取內部端點](#CloudWatch_Synthetics_Canaries_Troubleshoot_internalendpoint)
+ [Canary 執行時間版本升級和降級問題](#CloudWatch_Synthetics_Canaries_Troubleshoot_upgradeissues)
+ [跨來源請求共享 (CORS) 問題](#CloudWatch_Synthetics_Canaries_CORS)
+ [Canary 競爭條件問題](#CloudWatch_Synthetics_Canaries_RaceCondition)
+ [對 VPC 上的 Canary 進行故障診斷](#CloudWatch_Synthetics_Canaries_VPC_troubleshoot)
+ [對自動重試 Canary 進行疑難排解](#CloudWatch_Synthetics_Canaries_autoretry)
## Canary 在 Lambda 環境更新後失敗
CloudWatch Synthetics Canary 會在您的帳戶中實作為 Lambda 函式。這些 Lambda 函式會受到定期 Lambda 執行時期更新的影響，包含安全性更新、錯誤修正和其他改善。Lambda 致力於提供與現有函式回溯相容的執行時期更新。但是與軟體修補一樣，在極少數情況下，執行階段更新可能會對現有函數產生負面影響。如果您認為 Canary 受到 Lambda 執行時期更新的影響，可以使用 Lambda 執行時期管理手動模式 (在支援的區域中) 暫時復原 Lambda 執行時期版本。這可讓您的 Canary 函式保持正常運作並將中斷時間縮到最短，這樣便有時間在改回最新執行時期版本之前，修正不相容的情況。
如果您的 Canary 在 Lambda 執行時期更新後失敗，最佳解決方案是升級至最新的 Synthetics 執行時期之一。如需有關最新執行時期的詳細資訊，請參閱 [Synthetics 執行時間版本](CloudWatch_Synthetics_Canaries_Library.md)。
作為替代解決方案，在提供 Lambda 執行時期管理控制的區域中，您可以使用手動模式進行執行時期管理控制，將 Canary 還原至較舊的 Lambda 受管執行時期。您可以使用 AWS CLI 或使用 Lambda 主控台，使用下列各節中的步驟來設定手動模式。
**警告**
當您將執行時期設定變更為手動模式時，您的 Lambda 函式不會收到自動安全性更新，直到還原為自動模式為止。在此期間，您的 Lambda 函式可能容易受到安全漏洞的影響。
**先決條件**
+ 安裝 [ jq](https://jqlang.github.io/jq/)
+ 安裝最新版本的 AWS CLI。如需詳細資訊，請參閱 [AWS CLI 安裝和更新說明](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions)。
### 步驟 1：取得 Lambda 函式 ARN
執行下列命令，從回應中擷取 `EngineArn` 欄位。這個 `EngineArn` 是與 Canary 關聯之 Lambda 函式的 ARN。您會在後續步驟中用到此 ARN。
```
aws synthetics get-canary --name my-canary | jq '.Canary.EngineArn'
```
`EngingArn` 的輸出範例：
```
"arn:aws:lambda:us-west-2:123456789012:function:cwsyn-my-canary-dc5015c2-db17-4cb5-afb1-EXAMPLE991:8"
```
### 步驟 2：取得最後一個有效的 Lambda 執行時期版本 ARN
為協助了解您的 Canary 是否受到 Lambda 執行時期更新的影響，請檢查日誌中 Lambda 執行時期版本 ARN 變更的時間點，是否與您觀察到的 Canary 環境受影響的時間點相符。如果不相符，問題很可能並非由 Lambda 執行時期更新所導致。
如果您的 Canary 受到 Lambda 執行時期更新的影響，您必須識別先前使用之正常運作 Lambda 執行時期版本的 ARN。依循[識別執行時期版本變更](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-update.html#runtime-management-identify.html)中的說明，尋找先前執行時期的 ARN。記錄執行時期版本 ARN，並繼續執行步驟 3：設定執行時期管理組態。
如果您的 Canary 尚未受到 Lambda 環境更新的影響，您可以找到目前正在使用之 Lambda 執行時期版本的 ARN。執行下列命令，從回應中擷取 Lambda 函式的 `RuntimeVersionArn`。
```
aws lambda get-function-configuration \
--function-name "arn:aws:lambda:us-west-2:123456789012:function:cwsyn-my-canary-dc5015c2-db17-4cb5-afb1-EXAMPLE991:8" | jq '.RuntimeVersionConfig.RuntimeVersionArn'
```
`RuntimeVersionArn` 的輸出範例：
```
"arn:aws:lambda:us-west-2::runtime:EXAMPLE647b82f490a45d7ddd96b557b916a30128d9dcab5f4972911ec0f"
```
### 步驟 3：更新 Lambda 執行時期管理組態
您可以使用 AWS CLI 或 Lambda 主控台來更新執行時間管理組態。
**使用 AWS CLI設定 Lambda 執行時期管理組態手動模式**
輸入下列命令，將 Lambda 函式的執行時期管理變更為手動模式。請務必使用您在步驟 1 中找到的值，將 {{function-name}} 和{{限定詞}}分別取代為 Lambda 函數 ARN 和 Lambda 函數版本編號。也請將 {{ runtime-version-arn}} 取代為您在步驟 2 中找到的版本 ARN。
```
aws lambda put-runtime-management-config \
--function-name "{{arn:aws:lambda:us-west-2:123456789012:function:cwsyn-my-canary-dc5015c2-db17-4cb5-afb1-EXAMPLE991}}" \
--qualifier {{8}} \
--update-runtime-on "Manual" \
--runtime-version-arn "{{arn:aws:lambda:us-west-2::runtime:a993d90ea43647b82f490a45d7ddd96b557b916a30128d9dcab5f4972911ec0f}}"
```
**使用 Lambda 主控台將 Canary 變更為手動模式**
1. 在 https：//[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 開啟 AWS Lambda 主控台。
1. 選擇**版本**索引標籤，選擇與您的 ARN 對應的版本編號連結，然後選擇**程式碼**索引標籤。
1. 向下捲動至**執行時期設定**，展開**執行時期管理組態**，然後複製**執行時期版本 ARN**。
1. 選擇**編輯執行時間管理組態**，選擇**手動**，將您先前複製的執行時間版本 ARN 貼到**執行時間版本 ARN** 欄位。然後選擇 **Save** (儲存)。
## 我的 Canary 被 封鎖 AWS WAF
若要允許 Canary 流量通過 AWS WAF，請建立 AWS WAF 字串比對條件，以允許您指定的自訂字串。如需詳細資訊，請參閱 AWS WAF 文件中的[使用字串比對條件](https://docs.aws.amazon.com/waf/latest/developerguide/classic-web-acl-string-conditions.html)。
我們強烈建議您使用自己的自訂使用者代理程式字串，而非使用預設值。這可以更好地控制 AWS WAF 篩選並提升安全性。
若要設定自訂使用者代理程式字串，請執行下列動作：
+ 對於 Playwright 執行時間，您可以使用 Synthetics 組態檔案附加 AWS WAF 已核准的自訂使用者代理程式字串。如需詳細資訊，請參閱[CloudWatch Synthetics 組態](Synthetics_WritingCanary_Nodejs_Playwright.md#Synthetics_canary_configure_Playwright_script)。
+ 對於 Puppeteer 或 Selenium 執行時期，您可以使用支援的程式庫函式新增自訂使用者代理程式字串。如需了解 Puppeteer 執行時期，請參閱 [async addUserAgent(page, userAgentString);](CloudWatch_Synthetics_Canaries_Library_Nodejs.md#CloudWatch_Synthetics_Library_addUserAgent)。如需了解 Selenium 執行時期，請參閱 [add\_user\_agent(user\_agent\_str)](CloudWatch_Synthetics_Canaries_Library_Python.md#CloudWatch_Synthetics_Library_add_user_agent)。
## 等待元素出現
分析日誌和螢幕擷取畫面後，如果您看到指令碼正在等待元素出現在螢幕上並逾時，請檢查相關的螢幕擷取畫面，看看元素是否出現在頁面上。確認您的 `xpath`，以確保它正確無誤。
對於 Puppetteer 相關問題，請檢查 [Puppeteer 的 GitHub 頁面](https://github.com/puppeteer/puppeteer/issues)或網際網路論壇。
## 節點不可見或不是 page.click() 的 HTMLElement
如果節點不可見或不是 `page.click()` 的 `HTMLElement`，首先驗證您正在使用的 `xpath`，以按一下元素。另外，如果元素位於屏幕底部，請調整檢視區。CloudWatch Synthetics 預設使用的檢視區是 1920 \* 1080。您可以在啟動瀏覽器或使用 Puppeteer 函數 `page.setViewport` 時，設定不同的檢視區。
## 無法上傳成品到 S3，例外狀況：無法擷取 S3 儲存貯體位置：拒絕存取
如果您的 Canary 因 Simple Storage Service (Amazon S3) 錯誤而失效，則 CloudWatch Synthetics 會因為許可問題而無法上傳為 Canary 建立的螢幕擷取畫面、日誌或報告。請檢查以下內容：
+ 檢查 Canary 的 IAM 角色是否具有 `s3:ListAllMyBuckets` 許可、正確 Simple Storage Service (Amazon S3) 儲存貯體的 `s3:GetBucketLocation` 許可，以及 Canary 存放其成品之儲存貯體的 `s3:PutObject` 許可。如果 Canary 執行視覺監控，則角色也需要儲存貯體的 ` s3:GetObject` 許可。如果 Canary 部署在具有 VPC 端點的 VPC 中，則 Amazon VPC S3 閘道端點政策也需要這些相同的許可。
+ 如果 Canary 使用 AWS KMS 客戶受管金鑰進行加密，而不是標準 AWS 受管金鑰 （預設），則 Canary 的 IAM 角色可能沒有使用該金鑰加密或解密的許可。如需詳細資訊，請參閱[加密 Canary 成品](CloudWatch_Synthetics_artifact_encryption.md)。
+ 您的儲存貯體政策可能不允許 Canary 使用的加密機制。例如，如果您的儲存貯體政策要求使用特定的加密機制或 KMS 金鑰，則您必須為 Canary 選取相同的加密模式。
如果 Canary 執行視覺監控，請參閱 [使用視覺監控時更新成品位置和加密](CloudWatch_Synthetics_artifact_encryption.md#CloudWatch_Synthetics_artifact_encryption_visual) 以了解詳細資訊。
## 錯誤：通訊協定錯位 (Runtime.callFunctionOn)：目標關閉。
如果頁面或瀏覽器關閉後存在某些網路請求，就會出現此錯誤。您可能忘記等待非同步操作。執行您的指令碼後，CloudWatch Synthetics 會關閉瀏覽器。瀏覽器關閉後執行任何非同步操作可能會導致 `target closed error`。
## Canary 失敗。錯誤：沒有資料點 - Canary 顯示逾時錯誤
這意味著您的 Canary 執行超過逾時時間。在 CloudWatch Synthetics 發布成功百分比 CloudWatch 指標或更新成品 (例如 HAR 檔案、日誌和螢幕擷取畫面) 之前，Canary 執行已停止。如果您的逾時太低，您可以增加它。
預設情況下，Canary 逾時值等於其頻率。您可以手動將逾時值調整為小於或等於 Canary 頻率。如果您的 Canary 頻率很低，則必須增加頻率以增加逾時。當您使用 CloudWatch Synthetics 主控台建立或更新 Canary 時，您可於 **Schedule** (排程) 之下調整頻率和逾時值。
請確定您的逾時值不短於 15 秒，以允許 Lambda 冷啟動和啟動 canary 儀器所需的時間。
發生此錯誤時，無法在 CloudWatch Synthetics 主控台中檢視 Canary 成品。您可以使用 CloudWatch Logs 來查看 Canary 的日誌。
**若要使用 CloudWatch Logs 查看 Canary 的日誌**
1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在左側導覽窗格中，選擇 **Log groups** (日誌群組)。
1. 在篩選條件方塊中輸入 Canary 名稱，以尋找日誌群組。Canary 的日誌群組具有名稱 **/aws/lambda/cwsyn-{{canaryName}} -randomId**。
## 嘗試存取內部端點
如果您希望 Canary 存取內部網路上的端點，我們建議您將 CloudWatch Synthetics 設定為使用 VPC。如需詳細資訊，請參閱[在 VPC 上執行 Canary](CloudWatch_Synthetics_Canaries_VPC.md)。
## Canary 執行時間版本升級和降級問題
如果您最近將 Canary 從執行時間版本 `syn-1.0` 升級至最新版本，它可能是跨來源請求共享 (CORS) 問題。如需詳細資訊，請參閱[跨來源請求共享 (CORS) 問題](#CloudWatch_Synthetics_Canaries_CORS)。
如果您最近將 Canary 降級到較舊的執行時間版本，請檢查以確定您正在使用的 CloudWatch Synthetics 函數在您降級到較舊的執行時間版本中可用。例如，`executeHttpStep` 函數可用於執行時間版本 `syn-nodejs-2.2` 和更新版本。若要檢查函數的可用性，請參閱 [撰寫 Canary 指令碼](CloudWatch_Synthetics_Canaries_WritingCanary.md)。
**注意**
當您計劃升級或降級 Canary 的執行時期版本時，我們建議您先複製 Canary 並更新所複製 Canary 中的執行時期版本。一旦您驗證了含新版執行時間的複製 Canary 可運作，您可以更新原始 Canary 的執行時間版本並刪除複製的 Canary。
## 跨來源請求共享 (CORS) 問題
在 UI Canary 中，如果某些網絡請求失敗並顯示 `403` 或 ` net::ERR_FAILED`，請檢查 Canary 是否已啟用作用中追蹤，並使用 Puppeteer 函數 `page.setExtraHTTPHeaders` 以新增標頭。如果是這樣，失敗的網路請求可能是跨來源請求共享 (CORS) 限制所造成。您可以藉由停用作用中追蹤或移除額外的 HTTP 標頭來確認是否會發生這種情況。
**為什麼會出現這種情況？**
使用作用中追蹤時，會將額外的標頭新增至所有傳出要求，以追蹤呼叫。透過新增追蹤標頭或使用 Puppeteer 的 `page.setExtraHTTPHeaders` 會導致 XMLHttpRequest (XHR) 請求的 CORS 檢查。
如果您不想停用作用中追蹤或移除額外的標題，則可以更新 Web 應用程式以允許跨來源存取，或者您可以在您的指令碼中啟動 Chrome 瀏覽器時使用 `disable-web-security` 旗標。
您可以覆寫 CloudWatch Synthetics 使用的啟動參數，並使用 CloudWatch Synthetics 啟動函數傳遞其他 ` disable-web-security` 旗標參數。如需詳細資訊，請參閱[適用於使用 Puppeteer 之 Node.js Canary 指令碼的程式庫函式](CloudWatch_Synthetics_Canaries_Library_Nodejs.md)。
**注意**
當您使用執行時間版本 `syn-nodejs-2.1` 或更新版本時，您可以覆寫 CloudWatch Synthetics 使用的啟動參數。
## Canary 競爭條件問題
為獲得最佳的 CloudWatch Synthetics 使用體驗，請確保為 Canary 編寫的程式碼具有冪等性。否則，在極少數情況下， Canary 執行可能會遇到競態條件，即 Canary 在不同執行中與同一資源交互時發生衝突。
## 對 VPC 上的 Canary 進行故障診斷
如果您在建立或更新 VPC 上的 Canary 後發生問題，下列其中一個章節可能可以協助您對問題進行故障診斷。
### 處於錯誤狀態的新 Canary 或 Canary 無法更新
如果您建立要在 VPC 上執行的 Canary，而且它立即進入錯誤狀態，或您無法更新要在 VPC 上執行的 Canary，Canary 的角色可能不具備適當的許可。若要在 VPC 上執行，Canary 必須具有 ` ec2:CreateNetworkInterface`、`ec2:DescribeNetworkInterfaces` 和 ` ec2:DeleteNetworkInterface` 許可。這些許可都包含在 ` AWSLambdaVPCAccessExecutionRole` 受管政策中。如需詳細資訊，請參閱[執行角色和使用者許可](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc.html#vpc-permissions)。
如果此問題是在您建立 Canary 時發生，您必須刪除 Canary，然後建立新的 Canary。如果您使用 CloudWatch 主控台建立新的 Canary，請在 **Access Permissions** (存取許可)，選取 **Create a new role** (建立新角色)。系統會建立包含執行 Canary 所需之所有許可的新角色。
如果此問題是在您更新 Canary 時發生，您可以再次更新 Canary，並提供具備必要許可的新角色。
### 「No test result returned」(未傳回測試結果) 錯誤
如果 Canary 顯示「no test result returned」(未傳回測試結果) 錯誤，則原因可能是下列其中一個問題：
+ 如果 VPC 沒有網際網路存取權，您必須使用 VPC 端點來讓 Canary 存取 CloudWatch 和 Simple Storage Service (Amazon S3)。您必須在 VPC 中啟用 **DNS resolution (DNS 解析)** 和 **DNS hostname (DNS 主機名稱)** 選項，才能正確解析這些端點位址。如需詳細資訊，請參閱[搭配 VPC 使用 DNS](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html) 和[搭配介面 VPC 端點使用 CloudWatch 和 CloudWatch Synthetics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-and-interface-VPC.html)。
+ Canary 必須在 VPC 內的私有子網路中執行。若要檢查此問題，請在 VPC 主控台中開啟**子網路**頁面。檢查您在設定 Canary 時所選取的子網路。如果子網路具有網際網路閘道 (**igw-**) 的路徑，則不是私有子網路。
為協助您對這些問題進行故障診斷，請參閱 Canary 的日誌。
**如何查看來自 Canary 的日誌事件**
1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在導覽窗格中，選擇 **Log groups** (日誌群組)。
1. 選擇 Canary 日誌群組的名稱。日誌群組名稱開頭為 ` /aws/lambda/cwsyn-{{canary-name}}`。
## 對自動重試 Canary 進行疑難排解
若要了解 Canary 失敗的原因或分析特定嘗試為何失敗，請依循這些疑難排解步驟。
1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在導覽窗格中，依序選擇 **Application Signals**、**Synthetics Canary**。
1. 選擇 **Canary**。
1. 在**可用性**索引標籤下，您可以採用以下任一方法，檢查執行詳細資訊：
+ 在 Canary Runs 圖形上選取特定點
+ 在**問題**下，選取記錄。請注意，重試嘗試會加上標籤，並與排程的執行共用時間戳記
您可以在**步驟**、**螢幕擷取畫面**、**日誌**、**HAR 檔案**或**追蹤 （如果啟用主動追蹤）** 下檢視其他資訊。
1. 在 **Canary 成品和 Amazon S3 位置**下，可以存取成品，並透過可用的連結導覽至 Amazon S3 資料夾或儲存貯體。
1. **Canary 執行**圖形使用不同的彩色點來表示各種狀態：
+ 藍點 – 表示成功排程的執行，一致性值為 100%
+ 紅點 – 顯示排程執行與所有重試均失敗，標記為 0%
+ 橘點 – 顯示 0% 或 100%。0% 表示先前嘗試失敗後持續重試，100% 表示重試後成功