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

# 使用 Amazon CloudWatch 指標監控 REST API 執行
<a name="monitoring-cloudwatch"></a>

您可以使用 CloudWatch 來監控 API 執行，該服務會收集並處理來自 API Gateway 的原始資料，進而將這些資料轉換為便於讀取且幾近即時的指標。這些統計資料會記錄 15 個月的時間，以便您存取歷史資訊，並更清楚 Web 應用程式或服務的執行效能。根據預設，API Gateway 指標資料會自動在一分鐘內傳送給 CloudWatch。如需更多詳細資訊，請參閱《Amazon CloudWatch 使用者指南》**中的[什麼是 Amazon CloudWatch？](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)。

API Gateway 回報的指標可提供資訊，您可透過不同方式加以分析。下列清單顯示指標的一些常見用途，這些用途是協助您開始使用的建議：
+ 監控 **IntegrationLatency** 指標，以測量後端的回應能力。
+ 監控 **Latency** 指標，以測量您 API 呼叫的整體回應能力。
+ 監控 **CacheHitCount** 與 **CacheMissCount** 指標，以最佳化快取容量來達到所需的效能。

**Topics**
+ [Amazon API Gateway 維度和指標](api-gateway-metrics-and-dimensions.md)
+ [使用 API Gateway 中的 API 儀表板檢視 CloudWatch 指標](how-to-api-dashboard.md)
+ [在 CloudWatch 主控台中檢視 API Gateway 指標](metrics_dimensions_view_in_cloud_watch.md)
+ [在 CloudWatch 主控台中檢視 API Gateway 日誌事件](view-cloudwatch-log-events-in-cloudwatch-console.md)
+ [在 AWS 中監控 API Gateway 的工具](monitoring_automated_manual.md)

# Amazon API Gateway 維度和指標
<a name="api-gateway-metrics-and-dimensions"></a>

下面列出 API Gateway 傳送至 Amazon CloudWatch 的指標和維度。如需更多詳細資訊，請參閱 [使用 Amazon CloudWatch 指標監控 REST API 執行](monitoring-cloudwatch.md)。

## API Gateway 指標
<a name="api-gateway-metrics"></a>

Amazon API Gateway 每分鐘都會將指標資料傳送到 CloudWatch。

`AWS/ApiGateway` 命名空間包含下列指標。


| 指標 | 描述 | 
| --- | --- | 
|  4XXError |  在指定期間內擷取的用戶端錯誤數目。 API Gateway 會將修改後的閘道回應狀態碼計入 4XXError 錯誤。 `Sum` 統計資訊代表此指標，即指定期間內的 4XXError 錯誤總數。`Average` 統計資訊代表 4XXError 錯誤率，即期間內的 4XXError 錯誤總數除以要求總數。分母對應至 Count 指標 (下方)。 Unit: Count  | 
|  5XXError  |  在指定期間內擷取的伺服器端錯誤數目。 `Sum` 統計資訊代表此指標，即指定期間內的 5XXError 錯誤總數。`Average` 統計資訊代表 5XXError 錯誤率，即期間內的 5XXError 錯誤總數除以要求總數。分母對應至 Count 指標 (下方)。 Unit: Count  | 
|  CacheHitCount  |  在指定期間內從 API 快取提供的要求數目。 `Sum` 統計資訊代表此指標，即指定期間內的快取命中總數。`Average` 統計資訊代表快取命中率，即期間內的快取命中總數除以要求總數。分母對應至 Count 指標 (下方)。 Unit: Count  | 
|  CacheMissCount  |  啟用 API 快取時，在指定期間內從後端提供的要求數目。 `Sum` 統計資訊代表此指標，即指定期間內的快取未命中總數。`Average` 統計資訊代表快取未命中率，即期間內的快取未命中總數除以要求總數。分母對應至 Count 指標 (下方)。 Unit: Count  | 
|  Count  |  指定期間內的 API 要求總數。 `SampleCount` 統計資訊代表此指標。 Unit: Count  | 
|  IntegrationLatency  |  API Gateway 將請求轉送給後端時與收到來自後端的回應時之間的時間。 Unit: Millisecond  | 
|  Latency  |  API Gateway 收到來自用戶端的請求時與它將回應傳回給用戶端時之間的時間。延遲包含整合延遲與其他 API Gateway 額外負荷。 Unit: Millisecond  | 

## 指標的維度
<a name="api-gateway-metricdimensions"></a>

您可以使用下表中的維度來篩選 API Gateway 指標。

**注意**  
傳送指標至 CloudWatch 前，API Gateway 會從 ApiName 維度移除非 ASCII 字元。如果 APIName 不含 ASCII 字元，API ID 則會做為 ApiName 使用。


| 維度 | 描述 | 
| --- | --- | 
|  ApiName  |  篩選所指定 API 名稱之 REST API 的 API Gateway 指標。  | 
|  ApiName, Method, Resource, Stage  |  篩選所指定 API 名稱、階段、資源與方法之 API 方法的 API Gateway 指標。 除非您已明確啟用詳細的 CloudWatch 指標，否則 API Gateway 不會傳送這類指標。在主控台中選擇某個階段，然後針對**日誌和追蹤**選取**編輯**。選取**詳細指標**，然後選擇**儲存變更**。或者，您可以呼叫 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) AWS CLI 命令，將 `metricsEnabled` 屬性更新為 `true`。 啟用這些指標會產生您帳戶的額外費用。如需定價資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。  | 
|  ApiName, Stage  |  篩選所指定 API 名稱和階段之 API 階段資源的 API Gateway 指標。  | 

# 使用 API Gateway 中的 API 儀表板檢視 CloudWatch 指標
<a name="how-to-api-dashboard"></a>

您可以使用 API Gateway 主控台的 API 儀表板來顯示在 API Gateway 中已部署 API 的 CloudWatch 指標。這些會顯示為 API 活動在一段時間內的摘要。

**Topics**
+ [先決條件](#how-to-api-dashboard-prerequisites)
+ [檢查儀表板中的 API 活動](#how-to-api-dashboard-console)

## 先決條件
<a name="how-to-api-dashboard-prerequisites"></a>

1. 您必須擁有在 API Gateway 中建立的 API。請遵循中的說明進行[在 APIs Gateway 中開發 REST API](rest-api-develop.md)

1. 您必須至少已部署一次 API。請遵循中的說明進行[在 API Gateway 中部署 REST API](how-to-deploy-api.md)

## 檢查儀表板中的 API 活動
<a name="how-to-api-dashboard-console"></a>

1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 選擇一個 API。

1. 在主導覽窗格中，選擇**儀表板**。

1. 針對**階段**，選擇所需的階段。

1. 選擇**日期範圍**以指定日期的範圍。

1. 重新整理 (如需要) 並檢視個別圖形中顯示的個別指標，圖形的標題包括 **API 呼叫**、**延遲**、**整合延遲**、**延遲**、**4xx 錯誤**和 **5xx 錯誤**。
**提示**  
若要檢查方法層級的 CloudWatch 指標，請確定您已在方法層級啟用 CloudWatch Logs。如需設定方法層級記錄的詳細資訊，請參閱[覆寫階段層級設定](set-up-stages.md#how-to-method-override)。

# 在 CloudWatch 主控台中檢視 API Gateway 指標
<a name="metrics_dimensions_view_in_cloud_watch"></a>

指標會先依服務命名空間分組，再依各命名空間內不同的維度組合分類。若要在 API 的方法層級檢視指標，請開啟詳細的指標。如需詳細資訊，請參閱[修改階段設定。](set-up-stages.md#how-to-stage-settings)。

**使用 CloudWatch 主控台檢視 API Gateway 指標**

1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 如有需要，請變更 AWS 區域。從導覽列中，選取 AWS 資源所在的區域。

1. 在導覽窗格中，選擇 **指標**。

1. 在 **All Metrics (所有指標)** 標籤中，選擇 **API Gateway**。

1.  若要依階段檢視指標，請選擇 **By Stage (依階段)** 面板。然後，選取您的 API 和指標名稱。

1. 若要依特定 API 檢視指標，請選擇 **By Api Name (依 API 名稱)** 面板。然後，選取您的 API 和指標名稱。

**使用 AWS CLI 檢視指標**

1. 使用下列 [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) 命令來列出指標：

   ```
   aws cloudwatch list-metrics --namespace "AWS/ApiGateway"
   ```

   建立指標後，最多需要 15 分鐘才會顯示指標。若要更快查看指標統計資料，請使用 [get-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html) 或 [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html)。

1. 使用下列 [get-metrics-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) 命令檢視一段時間內間隔為 5 分鐘的平均值：

   ```
   aws cloudwatch get-metric-statistics --namespace AWS/ApiGateway --metric-name Count --start-time 2011-10-03T23:00:00Z --end-time 2017-10-05T23:00:00Z --period 300 --statistics Average
   ```

# 在 CloudWatch 主控台中檢視 API Gateway 日誌事件
<a name="view-cloudwatch-log-events-in-cloudwatch-console"></a>

下一節說明必要的先決條件，以及如何在 CloudWatch 主控台檢視 API Gateway 日誌事件。

## 先決條件
<a name="view-cloudwatch-log-event-prerequisites"></a>

1. 您必須擁有在 API Gateway 中建立的 API。請遵循中的說明進行[在 APIs Gateway 中開發 REST API](rest-api-develop.md)

1. 您必須至少已部署並調用一次 API。請遵循[在 API Gateway 中部署 REST API](how-to-deploy-api.md)和[在 API Gateway 中調用 REST API](how-to-call-api.md)中的說明進行。

1. 您必須已針對階段啟用 CloudWatch 日誌。請遵循中的說明進行[在 API Gateway 中設定 REST API 的 CloudWatch 記錄功能](set-up-logging.md)

## 使用 CloudWatch 主控台檢視記錄的 API 請求與回應
<a name="view-cloudwatch-log-event"></a>

1. 在 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 如有需要，請變更 AWS 區域。從導覽列中，選取 AWS 資源所在的區域。如需詳細資訊，請參閱 [ 區域與端點](https://docs.aws.amazon.com/general/latest/gr/rande.html)。

1. 在導覽窗格中依序選擇 **Logs** (日誌)、**Log groups** (日誌群組)。

1. 在 **Log Groups (日誌群組)** 資料表下，選擇 **API-Gateway-Execution-Logs\$1\$1rest-api-id\$1/\$1stage-name\$1** 名稱的日誌群組。

1.  在 **Log Streams (日誌串流)** 資料表下，選擇一個日誌串流。您可以使用時間戳記協助尋找感興趣的日誌串流。

1. 選擇 **Text (文字)** 以檢視原始文字，或選擇 **Row (資料列)** 以逐列檢視事件。

**重要**  
 CloudWatch 可讓您刪除日誌群組或串流。不要手動刪除 API Gateway API 日誌群組或串流；讓 API Gateway 管理這些資源。手動刪除日誌群組或串流可能會導致 API 請求與回應不被記錄。如果發生這種情況，您可以刪除 API 的整個日誌群組，然後重新部署 API。這是因為 API Gateway 會針對部署 API 時的 API 階段，來建立日誌群組或日誌串流。

# 在 AWS 中監控 API Gateway 的工具
<a name="monitoring_automated_manual"></a>

AWS 提供各種工具，您可以用來監控 API Gateway。您可以設定其中一些工具為您自動監控，但其他工具則需要手動介入。建議您盡可能自動化監控任務。

## 中的自動化監控工具 AWS
<a name="monitoring_automated_tools"></a>

您可以使用下列自動化監控工具來監看 API Gateway，並在發生錯誤時回報：
+ **Amazon CloudWatch 警示** – 監看指定時段內的單一指標，並根據與多個時段內給定之閾值相對的指標值來執行一或多個動作。此動作是傳送到 Amazon Simple Notification Service (Amazon SNS) 主題或 Amazon EC2 Auto Scaling 政策的通知。CloudWatch 警示不會只因處於特定狀態就調用動作，狀態必須已變更並已維持一段指定的時間。如需詳細資訊，請參閱[使用 Amazon CloudWatch 指標監控 REST API 執行](monitoring-cloudwatch.md)。
+ **Amazon CloudWatch Logs**：監控、存放及存取來自 AWS CloudTrail 或其他來源的日誌檔案。如需更多詳細資訊，請參閱《*Amazon CloudWatch 使用者指南*》中的[什麼是 CloudWatch Logs？](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html)。
+ **Amazon EventBridge (以前稱為 Amazon CloudWatch Events)**：比對事件，並將事件轉送至一或多個目標函式或串流以進行變更、擷取狀態資訊，以及採取修正動作。如需詳細資訊，請參閱《*Amazon EventBridge 使用者指南*》中的[什麼是 Amazon EventBridge？](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html)。
+ **AWS CloudTrail 日誌監控** – 在帳戶之間共用日誌檔案、透過將日誌檔案傳送到 CloudWatch Logs 來即時監控 CloudTrail 日誌檔案、在 Java 中寫入日誌處理應用程式，以及驗證您的日誌檔案在 CloudTrail 交付後並未變更。如需詳細資訊，請參閱《AWS CloudTrail 使用者指南》**中的[使用 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html)。

## 手動監控工具
<a name="monitoring_manual_tools"></a>

監控 API Gateway 的另一個重要部分是手動監控 CloudWatch 警示未涵蓋的項目。API Gateway、CloudWatch 和其他 AWS 主控台儀表板可讓您at-a-glance檢視 AWS 環境的狀態。建議您也檢查 API 執行上的日誌檔。
+ API Gateway 儀表板顯示指定 API 階段在指定時間內的下列統計資料：
  + **API Calls (API 呼叫)**
  + **Cache Hit (快取命中)**，只在啟用 API 快取時。
  + **Cache Miss (快取遺漏)**，只在啟用 API 快取時。
  + **Latency (延遲)**
  + **Integration Latency (整合延遲)**
  + **4XX Error (4XX 錯誤)**
  + **5XX Error (5XX 錯誤)**
+ CloudWatch 首頁會顯示：
  + 目前警示與狀態
  + 警示與資源的圖表
  + 服務運作狀態

  此外，您可以使用 CloudWatch 執行下列動作：
  + 建立[自定儀表板](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)來監控您注重的服務
  + 用於疑難排解問題以及探索驅勢的圖形指標資料。
  + 搜尋和瀏覽您的所有 AWS 資源指標
  + 建立與編輯要通知發生問題的警示

## 建立 CloudWatch 警示來監控 API Gateway
<a name="creating_alarms"></a>

您可以建立 CloudWatch 警報，在警示變更狀態時傳送 Amazon SNS 訊息。警示會監看指定時段內的單一指標，並根據與多個時段內指定閾值相對的指標值來執行一或多個動作。此動作是傳送到 Amazon SNS 主題或 Auto Scaling 政策的通知。警示僅會針對持續狀態變更呼叫動作。CloudWatch 警示不會只因處於特定狀態就調用動作，狀態必須已變更並已維持一段指定的時間。