本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 API Gateway 中監控 HTTP API 您可以使用 CloudWatch 指標和 CloudWatch Logs 來監控 HTTP API。藉由結合日誌和指標，您可以記錄錯誤並監控 API 的效能。 **注意** 在下列情況下，API Gateway 可能無法產生日誌和指標： 413 請求實體過大錯誤 過多的 429 請求過多錯誤 400 系列錯誤，來自傳送至沒有 API 映射自訂網域的要求 由於內部失敗造成的 500 系列錯誤 **Topics** + [在 API Gateway 中監控 HTTP API 的 CloudWatch 指標](http-api-metrics.md) + [在 API Gateway 中設定 HTTP API 的日誌](http-api-logging.md) # 在 API Gateway 中監控 HTTP API 的 CloudWatch 指標 您可以使用 CloudWatch 來監控 API 執行，該服務會收集並處理來自 API Gateway 的原始資料，進而將這些資料轉換為便於讀取且幾近即時的指標。這些統計資料會記錄 15 個月的時間，以便您存取歷史資訊，並更清楚 Web 應用程式或服務的執行效能。根據預設，API Gateway 指標資料會自動在一分鐘內傳送給 CloudWatch。若要監控您的指標，請為您的 API 建立 CloudWatch 儀表板。如需如何建立 CloudWatch 儀表板的詳細資訊，請參閱《Amazon CloudWatch 使用者指南》**中的[建立 CloudWatch 儀表板](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create_dashboard.html)。如需更多詳細資訊，請參閱《Amazon CloudWatch 使用者指南》**中的[什麼是 Amazon CloudWatch？](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)。 HTTP API 支援下列指標。您也可以啟用詳細指標，將路由層級的指標寫入 Amazon CloudWatch。 | 指標 | 描述 | | --- | --- | | 4xx | 在指定期間內擷取的用戶端錯誤數目。 | | 5xx | 在指定期間內擷取的伺服器端錯誤數目。 | | Count | 指定期間內的 API 要求總數。 | | IntegrationLatency | API Gateway 將請求轉送給後端時與收到來自後端的回應時之間的時間。 | | Latency | API Gateway 收到來自用戶端的請求時與它將回應傳回給用戶端時之間的時間。延遲包含整合延遲與其他 API Gateway 額外負荷。 | | DataProcessed | 處理的資料量 (以位元組為單位)。 | 您可以使用下表中的維度來篩選 API Gateway 指標。 | 維度 | 描述 | | --- | --- | | ApiId | 篩選具指定 API ID 之 API 的 API Gateway 指標。 | | ApiId、階段 | 篩選具指定 API ID 與階段 ID 之 API 階段的 API Gateway 指標。 | | ApiId、方法、資源、階段 | 篩選具指定 API ID、階段 ID、資源路徑和路由 ID 之 API 方法的 API Gateway 指標。 除非您已明確啟用詳細的 CloudWatch 指標，否則 API Gateway 不會傳送這類指標。您可以透過呼叫 API Gateway V2 REST API 的 [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) 動作，將 `detailedMetricsEnabled` 屬性更新為 `true`。或者，您可以呼叫[更新階段](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) AWS CLI 命令，將 `DetailedMetricsEnabled` 屬性更新為 `true`。啟用這類指標會產生您帳戶的額外費用。如需定價資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。 | # 在 API Gateway 中設定 HTTP API 的日誌 您可以開啟記錄功能，將日誌寫入 CloudWatch Logs。您可以使用[記錄變數](http-api-logging-variables.md)來自訂日誌的內容。 為了改善您的安全狀態，建議您將 HTTP API 所有階段的日誌寫入 CloudWatch Logs。您可能需要這樣做，才能符合各種合規架構。如需詳細資訊，請參閱《AWS Security Hub 使用者指南》**中的 [Amazon API Gateway 控制項](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html)。 若要開啟 HTTP API 的記錄功能，您必須執行下列動作。 1. 確定您的使用者具有啟用記錄所需的許可。 1. 建立 CloudWatch Logs 日誌群組。 1. 為 API 的某個階段提供 CloudWatch Logs 日誌群組的 ARN。 ## 用以啟用記錄的許可。 若要開啟 API 的記錄功能，您的使用者必須具有下列許可。 **Example** **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:GetLogEvents", "logs:FilterLogEvents" ], "Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogDelivery", "logs:PutResourcePolicy", "logs:UpdateLogDelivery", "logs:DeleteLogDelivery", "logs:CreateLogGroup", "logs:DescribeResourcePolicies", "logs:GetLogDelivery", "logs:ListLogDeliveries" ], "Resource": "*" } ] } ``` ## 建立日誌群組並啟動 HTTP API 的記錄 您可以使用 AWS 管理主控台 或 建立日誌群組並啟用存取記錄 AWS CLI。 ------ #### [ AWS 管理主控台 ] 1. 建立 日誌群組 如要了解如何使用主控台建立日誌群組，請參閱《Amazon CloudWatch Logs 使用者指南》中的[建立日誌群組](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html) 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 選擇一個 HTTP API。 1. 在主導覽面板中的 **Monitor** (監視器) 標籤下，選擇 **Logging** (記錄)。 1. 選取要啟動記錄的階段，然後選擇 **Select** (選取)。 1. 選擇 **Edit** (編輯) 以啟動存取記錄。 1. 開啟 **Access logging** (存取記錄功能)，輸入 CloudWatch Logs，然後選取日誌格式。 1. 選擇**儲存**。 ------ #### [ AWS CLI ] 以下 [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html) 命令會建立日誌群組： ``` aws logs create-log-group --log-group-name my-log-group ``` 您需要日誌群組的 Amazon Resource Name (ARN) 才能啟用記錄。ARN 格式為 arn:aws:logs:*region*:*account-id*:log-group:*log-group-name*。 下列 [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) 命令會啟動 HTTP API 的 `$default` 階段的記錄功能： ``` aws apigatewayv2 update-stage --api-id abcdef \ --stage-name '$default' \ --access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}' ``` ------ ## 日誌格式範例 一些常用存取日誌格式範例會顯示在 API Gateway 主控台中，並列出如下。 + `CLF` ([通用日誌格式](https://httpd.apache.org/docs/current/logs.html#common))： ``` $context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId ``` + `JSON`: ``` { "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" } ``` + `XML`: ``` $context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId ``` + `CSV` (逗號分隔值)： ``` $context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId ``` # 自訂 HTTP API 存取日誌 您可以使用下列變數來自訂 HTTP API 存取日誌。要進一步了解 HTTP API 的存取日誌，請參閱[在 API Gateway 中設定 HTTP API 的日誌](http-api-logging.md)。 | 參數 | Description | | --- | --- | | \$1context.accountId | API 擁有者 AWS 的帳戶 ID。 | | \$1context.apiId | API Gateway 指派給您 API 的識別碼。 | | \$1context.authorizer.claims.property | 成功驗證方法發起人 (例如 `$context.authorizer.claims.username`) 之後，從 JSON Web Token (JWT) 傳回之宣告的屬性。如需詳細資訊，請參閱[使用 API Gateway 中的 JWT 授權方來控制對 HTTP API 的存取](http-api-jwt-authorizer.md)。 呼叫 `$context.authorizer.claims` 會傳回 null。 | | \$1context.authorizer.error | 從授權方傳回的錯誤訊息。 | | \$1context.authorizer.property | API Gateway Lambda 授權方函數所傳回 `context` 對應之指定索引鍵/值對的值。例如，如果授權方傳回下列 `context` 映射： 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
呼叫 `$context.authorizer.key` 會傳回 `"value"` 字串，呼叫 `$context.authorizer.numKey` 會傳回 `1`，而呼叫 `$context.authorizer.boolKey` 會傳回 `true`。 | | \$1context.awsEndpointRequestId | 來自 `x-amz-request-id`或 `x-amzn-requestId`標頭的 AWS 端點請求 ID。 | | \$1context.awsEndpointRequestId2 | 來自 `x-amz-id-2`標頭的 AWS 端點請求 ID。 | | \$1context.customDomain.basePathMatched | 傳入請求相符的 API 映射路徑。適用於用戶端使用自訂網域名稱來存取 API 時。例如，如果用戶端向 `https://api.example.com/v1/orders/1234` 傳送請求，並且請求讓 API 映射與路徑 `v1/orders` 相符，則該值為 `v1/orders`。如需進一步了解，請參閱[將 API 階段映射至 HTTP API 的自訂網域名稱](http-api-mappings.md)。 | | \$1context.dataProcessed | 處理的資料量 (以位元組為單位)。 | | \$1context.domainName | 用來叫用 API 的完整網域名稱。這應該與傳入的 `Host` 標頭相同。 | | \$1context.domainPrefix | `$context.domainName` 的第一個標籤。 | | \$1context.error.message | 包含 API Gateway 錯誤訊息的字串。 | | \$1context.error.messageString | \$1context.error.message 的引用值，即 "\$1context.error.message"。 | | \$1context.error.responseType | `GatewayResponse` 的類型。如需詳細資訊，請參閱 [使用 CloudWatch 指標監控 WebSocket API 執行](apigateway-websocket-api-logging.md) 和 [設定閘道回應以自訂錯誤回應](api-gateway-gatewayResponse-definition.md#customize-gateway-responses)。 | | \$1context.extendedRequestId | 等同於 \$1context.requestId。 | | \$1context.httpMethod | 使用的 HTTP 方法。有效值包含：`DELETE`、`GET`、`HEAD`、`OPTIONS`、`PATCH`、`POST` 和 `PUT`。 | | \$1context.identity.accountId | 與請求相關聯的 AWS 帳戶 ID。支援使用 IAM 授權的路由。 | | \$1context.identity.caller | 已簽署請求之發起人的主體識別符。支援使用 IAM 授權的路由。 | | \$1context.identity.cognitoAuthenticationProvider | 提出請求的發起人所使用的所有 Amazon Cognito 驗證提供者清單 (以逗號分隔)。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 例如，適用於 Amazon Cognito 使用者集區的身分，`cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 如需有關 Amazon Cognito 驗證提供者的詳細資訊，請參閱《[Amazon Cognito 開發人員指南](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)》中的*使用聯合身分*。 | | \$1context.identity.cognitoAuthenticationType | 提出請求的發起人的 Amazon Cognito 驗證類型。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。可能的值包括用於已驗證身分的 `authenticated` 和未經驗證身分的 `unauthenticated`。 | | \$1context.identity.cognitoIdentityId | 提出請求的發起人的 Amazon Cognito 身分 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 | | \$1context.identity.cognitoIdentityPoolId | 提出請求的發起人的 Amazon Cognito 身分集區 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 | | \$1context.identity.principalOrgId | [AWS 組織 ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html)。支援使用 IAM 授權的路由。 | | \$1context.identity.clientCert.clientCertPem | 用戶端在交互 TLS 驗證期間所呈現的 PEM 編碼用戶端憑證。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。 | | \$1context.identity.clientCert.subjectDN | 用戶端提供之憑證主體的辨別名稱。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。 | | \$1context.identity.clientCert.issuerDN | 用戶端提供之憑證發行者的辨別名稱。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。 | | \$1context.identity.clientCert.serialNumber | 憑證的序號。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。 | | \$1context.identity.clientCert.validity.notBefore | 憑證無效之前的日期。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。 | | \$1context.identity.clientCert.validity.notAfter | 憑證無效之後的日期。當用戶端使用已啟用交互 TLS 的自訂網域名稱存取 API 時會顯示。 | | \$1context.identity.sourceIp | 對 API Gateway 提出請求之即時 TCP 連線的來源 IP 地址。 | | \$1context.identity.user | 將針對資源存取授權之使用者的主體識別符。支援使用 IAM 授權的路由。 | | \$1context.identity.userAgent | API 發起人的 [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 標頭。 | | \$1context.identity.userArn | 身分驗證之後識別之有效使用者的 Amazon Resource Name (ARN)。支援使用 IAM 授權的路由。如需更多詳細資訊，請參閱 [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)。 | | \$1context.integration.error | 從整合傳回的錯誤訊息。等同於 \$1context.integrationErrorMessage。 | | \$1context.integration.integrationStatus | 對於 Lambda 代理整合，從 傳回的狀態碼 AWS Lambda，而不是從後端 Lambda 函數程式碼傳回的狀態碼。 | | \$1context.integration.latency | 整合延遲 (以毫秒為單位)。等同於 \$1context.integrationLatency。 | | \$1context.integration.requestId | AWS 端點的請求 ID。等同於 \$1context.awsEndpointRequestId。 | | \$1context.integration.status | 從整合傳回的狀態碼。對於 Lambda 代理整合而言，這是您的 Lambda 函數程式碼傳回的狀態碼。 | | \$1context.integrationErrorMessage | 包含整合錯誤訊息的字串。 | | \$1context.integrationLatency | 整合延遲 (以毫秒為單位)。 | | \$1context.integrationStatus | 對於 Lambda 代理整合，此參數代表從 傳回的狀態碼 AWS Lambda，而不是從後端 Lambda 函數傳回的狀態碼。 | | \$1context.path | 請求路徑。例如，/\$1stage\$1/root/child。 | | \$1context.protocol | 請求通訊協定，例如 HTTP/1.1。 API Gateway API 可以接受 HTTP/2 請求，但 API Gateway 會使用 HTTP/1.1 將請求傳送至後端整合。因此，即使用戶端傳送使用 HTTP/2 的請求，請求通訊協定也會記錄為 HTTP/1.1。 | | \$1context.requestId | API Gateway 指派給 API 請求的 ID。 | | \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 格式化請求時間 (dd/MMM/yyyy:HH:mm:ss \$1-hhmm)。 | | \$1context.requestTimeEpoch | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 格式化請求時間。 | | \$1context.responseLatency | 回應延遲 (以毫秒為單位)。 | | \$1context.responseLength | 回應承載長度 (以位元組為單位)。 | | \$1context.routeKey | API 請求的路由金鑰，例如 `/pets`。 | | \$1context.stage | API 請求的部署階段 (例如，`beta` 或 `prod`)。 | | \$1context.status | 方法回應狀態。 |