# API Gateway에서 HTTP API 모니터링 CloudWatch 지표와 CloudWatch Logs를 사용하여 HTTP API를 모니터링할 수 있습니다. 로그와 지표를 결합하여 오류를 기록하고 API의 성능을 모니터링할 수 있습니다. **참고** API Gateway는 다음과 같은 경우 로그 및 지표를 생성하지 않을 수 있습니다. 413 요청 엔터티가 너무 큼 오류가 발생한 경우 429개 초과로 요청이 너무 많음 오류가 발생한 경우 API 매핑이 없는 사용자 지정 도메인으로 보낸 요청에서 400개의 연속 오류가 발생한 경우 내부 오류로 인해 500개의 연속 오류가 발생한 경우 **Topics** + [API Gateway에서 HTTP API에 대한 CloudWatch 지표 모니터링](http-api-metrics.md) + [API Gateway에서 HTTP API 로깅 구성](http-api-logging.md) # API Gateway에서 HTTP API에 대한 CloudWatch 지표 모니터링 API Gateway에서 원시 데이터를 수집하고 읽기 가능한 실시간에 가까운 지표로 처리하는 CloudWatch를 사용하여 API 실행을 모니터링할 수 있습니다. 이러한 통계는 15개월 간 기록되므로 기록 정보에 액세스하고 웹 애플리케이션이나 서비스가 어떻게 수행되고 있는지 전체적으로 더 잘 파악할 수 있습니다. 기본적으로 API Gateway 지표 데이터는 1분 간격으로 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 | 지정한 기간 내에 캡처된 서버 측 오류 수. | | 개수 | 지정된 기간 동안의 총 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, Method, Resource, Stage | 지정한 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`로 업데이트하면 됩니다. 또는 [update-stage](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 Management Console 또는 AWS CLI를 사용하여 로그 그룹을 생성하고 액세스 로깅을 활성화할 수 있습니다. ------ #### [ AWS Management Console ] 1. 로그 그룹 생성. 콘솔을 사용하여 로그 그룹을 생성하는 방법을 알아보려면 [Amazon CloudWatch Logs 사용 설명서의 로그 그룹 생성](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)을 참조하세요. 1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다. 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 리소스 이름(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`([Common Log Format](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) 단원을 참조하십시오. | 파라미터 | 설명 | | --- | --- | | \$1context.accountId | API 소유자의 AWS 계정 ID입니다. | | \$1context.apiId | 식별자 API Gateway가 API에 할당합니다. | | \$1context.authorizer.claims.property | 메서드 호출자가 성공적으로 인증된 후 JWT(JSON Web Token)에서 반환된 클레임의 속성(예: `$context.authorizer.claims.username`)입니다. 자세한 내용은 [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 | 요청에 서명한 호출자의 보안 주체 ID입니다. 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 | 리소스 액세스에 대해 권한을 부여할 사용자의 보안 주체 ID입니다. 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 | 인증 후 식별된 실제 사용자의 ARN(Amazon Resource Name)입니다. 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 프록시 통합의 경우 백엔드 Lambda 함수 코드가 아니라 AWS Lambda에서 반환된 상태 코드입니다. | | \$1context.integration.latency | 통합 지연 시간(ms)입니다. \$1context.integrationLatency와 동일합니다. | | \$1context.integration.requestId | AWS 엔드포인트의 요청 ID입니다. \$1context.awsEndpointRequestId와 동일합니다. | | \$1context.integration.status | 통합에서 반환된 상태 코드입니다. Lambda 프록시 통합의 경우 Lambda 함수 코드에서 반환된 상태 코드입니다. | | \$1context.integrationErrorMessage | 통합 오류 메시지가 포함된 문자열입니다. | | \$1context.integrationLatency | 통합 지연 시간(ms)입니다. | | \$1context.integrationStatus | Lambda 프록시 통합의 경우 이 파라미터는 백엔드 Lambda 함수가 아니라 AWS 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 | 응답 지연 시간(ms)입니다. | | \$1context.responseLength | 바이트로 된 응답 페이로드 길이입니다. | | \$1context.routeKey | API 요청의 경로 키입니다(예: `/pets`). | | \$1context.stage | API 요청의 개발 단계입니다(예: `beta` 또는 `prod`). | | \$1context.status | 메서드 응답 상태입니다. |