API Gateway 로그를 사용하여 API 문제를 해결하려면 어떻게 해야 합니까?

4분 분량

Amazon API Gateway 로그를 사용하여 API 문제를 해결하고 싶습니다.

간략한 설명

API Gateway REST API 또는 WebSocket API 문제를 해결하려면 실행 로깅을 활성화한 후 Amazon CloudWatch Logs를 사용하여 로그에 액세스하십시오. API Gateway AWS Identity and Access Management(IAM) 역할에 필요한 모든 권한을 연결해야 합니다. 설명은 API Gateway REST API 또는 WebSocket API의 문제 해결을 위해 CloudWatch Logs를 활성화하려면 어떻게 해야 합니까?를 참조하십시오.

참고: HTTP API는 액세스 로깅만 지원합니다. 이러한 API에 대한 로깅을 구성하는 방법에 대한 자세한 내용은 API Gateway에서 HTTP API에 대한 로깅 구성을 참조하십시오.

해결 방법

로깅을 활성화하면 API Gateway가 **API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}**이라는 CloudWatch 로그 그룹을 자동으로 만듭니다. 이 그룹을 사용하여 문제를 추가로 해결할 수 있습니다. 자세한 내용은 API Gateway용 CloudWatch 로그 형식을 참조하십시오.

권한 부여 오류 확인

API에 대해 AWS Lambda Authorizer를 활성화하면 로그에 요청이 승인되었는지 여부가 표시되고 권한 부여자 및 요청 ID가 포함됩니다.

승인된 로그의 예:

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

무단 로그의 예:

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

이 문제를 해결하려면 Lambda Authorizer를 만든 후 API Gateway ‘401 Unauthorized’ 오류가 발생하는 이유는 무엇입니까?를 참조하십시오.

사용량 계획 구성 업데이트

Lambda Authorizer가 로깅하면 API Gateway는 API 요청의 사용량 계획을 확인합니다. 사용량 계획을 구성하지 않으면 API 요청이 스로틀링 한도에 포함되지 않습니다.

사용량 계획 로그의 예:

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

API 키로 API를 구성했는데 X-API-Key 헤더가 없는 경우 로그는 다음 메시지와 비슷한 오류를 반환합니다.

"API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present"

이 문제를 해결하려면 API 구성을 검토하십시오. API 키를 필수 사용량 계획과 연결해야 하며 키를 올바른 값과 함께 X-API-KEY 헤더로 요청에 포함해야 합니다.

헤더에 올바른 API 키를 추가하고 API Gateway가 요청을 스로틀링하면 로그에 다음 메시지와 비슷한 오류가 반환됩니다.

"API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt. Limit: 5.00 Burst: 0
Method completed with status: 429"

이 문제를 해결하려면 API Gateway를 사용하는 API의 ‘429 Too Many Requests’ 또는 ‘Limited Exceeded’ 오류를 해결하려면 어떻게 해야 합니까?의 단계를 완료하십시오.

요청 로그 유형

데이터 추적과 오류 및 정보 로그를 활성화하면 API Gateway 로그에 문제 해결에 도움이 되는 세부 정보가 포함됩니다. API Gateway 요청이 실패한 위치를 확인하려면 다음 로그 유형에서 자세한 내용을 검토하십시오.

참고: 요청 로그의 경우 CloudWatch 로그 드롭다운 메뉴에서 오류 및 정보 로그를 선택해야 합니다. 그런 다음, 실행 로그에 대한 데이터 추적을 활성화합니다. 데이터를 추적하면 민감한 데이터가 기록될 수 있으므로 프로덕션 API에 대해서는 데이터 추적을 활성화하지 않는 것이 좋습니다.

메서드 요청 로그

메서드 요청 로그에는 요청 경로, 쿼리 파라미터, 요청 헤더, 요청 본문을 포함하여 API 요청이 수신하는 세부 정보가 포함됩니다.

메서드 요청 로그 예시:

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

엔드포인트 요청 로그

엔드포인트 요청 로그에는 URI, 요청 헤더, 요청 본문을 포함하여 API 요청이 수신하는 세부 정보가 포함됩니다.

엔드포인트 요청 로그의 예:

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

엔드포인트 요청에 포함된 데이터는 추가 처리를 위해 백엔드 통합으로 전송됩니다.

엔드포인트 응답 로그

엔드포인트 응답 로그에는 상태 코드, 헤더, 본문, 통합 지연 시간을 포함하여 백엔드 통합이 반환하는 데이터가 포함됩니다.

엔드포인트 응답 로그의 예:

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

메서드 응답 로그

메서드 응답 로그에는 변환 후 클라이언트에 전송된 헤더와 본문이 포함됩니다.

메서드 응답 로그의 예:

(####) Method response body after transformations: ...
(####) Method response headers: {...}

중요: API Gateway는 1,024바이트로 로그 이벤트를 제한합니다. API Gateway는 CloudWatch 로그에 로그가 제출되기 전에 요청 및 응답 본문과 같이 1,024바이트보다 큰 로그 이벤트를 잘라냅니다.