API Gateway REST API 또는 WebSocket API의 문제를 해결하기 위해 CloudWatch Logs를 활성화하려면 어떻게 해야 하나요?

4분 분량

개발 중인 Amazon API Gateway REST API 또는 WebSocket API 오류를 디버깅해야 합니다. API 문제를 해결하기 위해 로깅을 활성화하려면 어떻게 해야 합니까?

간략한 설명

API Gateway REST API 또는 WebSocket API의 문제를 해결하려면 Amazon CloudWatch Logs를 사용해 액세스 로깅과 실행 로깅을 활성화합니다.

참고: HTTP API는 현재 액세스 로깅만 지원하며 이러한 API의 로깅 설정은 다릅니다. 자세한 내용은 HTTP API에 대한 로깅 구성을 참조하세요.

실행 로그에는 대부분의 API 오류를 식별하고 해결하는 데 사용할 수 있는 정보가 포함되어 있습니다. 예를 들어 다음과 같습니다.

API가 수신하는 요청
API의 통합 백엔드 응답
AWS Lambda Authorizer가 제공하는 응답
AWS 통합 엔드포인트의 requestId
제공된 API 키가 승인되었는지 여부에 대한 정보

액세스 로그에는 API에 액세스한 사용자 및 API에 액세스한 방법에 대한 세부 정보가 포함되어 있습니다. 또한 로그를 사용하여 API 오류 문제를 해결할 수 있습니다. 각 로깅 유형에 대한 자세한 내용은 API Gateway용 CloudWatch 로그 형식을 참조하세요.

해결 방법

CloudWatch에 로깅하기 위한 IAM 역할 생성

1. AWS Identity and Access Management(IAM) 콘솔의 탐색 창에서 [역할]을 선택합니다.

2. 역할 창에서 역할 만들기를 선택합니다.

3. 역할 생성(Create role) 페이지에서 다음을 수행합니다.
신뢰할 수 있는 엔터티(Trusted entity) 유형에서 **AWS 서비스(AWS Service)**를 선택합니다.
**사용 사례(use case)**에서 API Gateway를 선택합니다.
API Gateway 라디오 버튼을 선택합니다.
**다음(Next)**을 선택합니다.

4. **권한 정책(Permissions Policies)**에는 AWS 관리형 정책(AWS managed policy) AmazonAPIGatewayPushToCloudWatchLogs가 기본적으로 선택되어 있습니다. 이 정책에는 필요한 모든 권한이 있습니다.

5. [Next(다음)]를 선택합니다.

6. 이름, 검토 및 생성 아래에서 다음을 수행합니다.
역할 이름에 해당 역할의 이름을 입력합니다.
(선택 사항) 역할 설명에서 기본 설정에 대한 설명을 편집합니다.
(선택 사항) 태그(tags)를 추가합니다.
**역할 생성(Create role)**을 선택합니다.

7. 역할(Roles) 창의 검색 창에 생성한 역할의 이름을 입력합니다. 그런 다음, 검색 결과에서 역할을 선택합니다.

8. 요약 창에서 역할 ARN을 복사합니다. 다음 섹션에서 이 Amazon 리소스 이름(ARN)이 필요합니다.

자세한 내용은 CloudWatch 로깅에 대한 권한을 참조하세요.

API Gateway 콘솔에서 IAM 역할 추가

참고: 서로 다른 AWS 리전에서 여러 API를 개발하는 경우 각 리전에서 다음 단계를 완료하세요.

1. API Gateway 콘솔의 API 창에서 생성한 API 이름을 선택합니다. 이는 REST API 또는 WebSocket API(HTTP API 아님) 입니다.

2. 왼쪽 탐색 창의 아래쪽에 있는클라이언트 인증서 섹션에서 설정을 선택합니다.

3. [설정(Settings)] 아래 [CloudWatch 로그 역할 ARN]에 복사한 IAM 역할 ARN을 붙여 넣습니다.

4. [저장(Save)]을 선택합니다.
참고: 콘솔은 ARN의 저장 여부를 확인하지 않습니다.

API 및 단계에 대한 로깅 활성화

1. API Gateway 콘솔의 API 창에서 생성한 API 이름을 선택합니다.

2. 좌측 탐색 창에서 스테이지를 선택합니다. 그런 다음 원하는 스테이지 이름을 선택합니다.

3. 로그/추적 탭을 선택합니다.

4. 로그/추적 탭의 CloudWatch 설정에서 다음을 수행하여 실행 로깅을 활성화합니다.
[CloudWatch Logs 활성화(Enable CloudWatch Logs)] 확인란을 선택합니다.
[로그 수준(Log level)]에서 [INFO]를 선택하여 모든 요청에 대한 실행 로그를 생성합니다. 또는 오류를 발생시키는 API에 대한 요청에 대해서만 실행 로그를 생성하려면 [ERROR]를 선택합니다.
REST API에 대해 [전체 요청/응답 데이터 로깅(Log full requests/responses data)] 확인란을 선택합니다. 또는 WebSocket API에 대해 전체 메시지 데이터 로깅 확인란을 선택합니다.

5. 사용자 지정 액세스 로깅에서 다음을 수행하여 액세스 로깅을 활성화합니다.
[액세스 로깅 활성화] 확인란을 선택합니다.
액세스 로그 대상 ARN의 경우, Amazon Kinesis Data Firehose(REST API에서만 지원됨) 또는 CloudWatch 로그 그룹의 ARN을 입력합니다.

[로그 형식]을 입력합니다. 지침의 경우 CLF, JSON, XML 또는 CSV를 선택하여 해당 형식의 예제를 볼 수 있습니다.

6. 변경 사항 저장을 선택합니다.
참고: 콘솔은 설정이 저장되었는지 확인하지 않습니다.

자세한 내용은 API Gateway 콘솔을 사용하여 CloudWatch API 로깅 설정을 참조하세요.

로깅 설정 테스트

1. 클라이언트 애플리케이션 또는 Postman 앱이나 wscat(WebSocket API용) 같은 도구를 사용하여 API에 새 요청을 전송합니다.

2. CloudWatch 콘솔의 왼쪽 탐색 창에서 [로그(Logs)] 아래 [**로그 그룹(Log Groups)]**을 선택합니다.

3. [로그 그룹(Log Groups)] 목록에서 디버깅하려는 API의 로그 그룹을 선택합니다.
REST API의 경우 로그 그룹의 이름은 API-Gateway-Execution-Logs_apiId/stageName 형식입니다.
WebSocket API의 경우 로그 그룹의 이름은 /aws/apigateway/apiId/stageName 형식입니다.
참고: 액세스 로그는 액세스 로깅을 활성화할 때 지정한 ARN의 로그 그룹에 위치합니다.

4. [로그 스트림] 목록에서 최신 마지막 이벤트 시간의 로그 스트림을 선택합니다. 이 옵션을 선택하면 요청의 실행 또는 액세스 세부 정보가 포함된 메시지를 볼 수 있습니다.

자세한 내용은 CloudWatch 콘솔에서 API Gateway 로그 이벤트 확인을 참조하세요.