API Gateway REST API 또는 WebSocket API 문제 해결을 위해 CloudWatch Logs를 활성화하려면 어떻게 해야 합니까?

최종 업데이트 날짜: 2020년 1월 20일

개발 중인 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에 액세스한 방법에 대한 세부 정보가 포함되어 있으며, 이를 문제 해결에 사용할 수도 있습니다. 각 로깅 유형에 대한 자세한 내용은 API Gateway용 CloudWatch 로그 형식을 참조하십시오.

​해결 방법

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

  1. AWS Identity and Access Management(IAM) 콘솔의 왼쪽 탐색 창에서 [Roles(역할)]을 선택합니다.
  2. [역할] 창에서 [역할 만들기]를 선택합니다.
  3. [역할 만들기] 페이지에서 다음을 수행합니다.
    [Select type of trusted entity]에서 [AWS Service]를 선택합니다.
    [Choose the service that will use this role]에서 [API Gateway]를 선택합니다.
    [Next: Permissions]를 선택합니다.
  4. [Attached permissions policies]에는 [AWS managed policy] [AmazonAPIGatewayPushToCloudWatchLogs]가 기본적으로 선택되어 있습니다. 이 정책에는 필요한 모든 권한이 있습니다.
  5. [Next: Tags]를 선택합니다.
  6. 선택적으로, 원하는 경우 태그를 추가하고 [Next: Review]를 선택합니다.
  7. [Review]에서 다음을 수행합니다.
    [Role name]에 의미 있는 역할 이름을 입력합니다.
    (선택 사항) [Role description]에서 기본 설정에 대한 설명을 편집합니다.
    [Create role]을 선택합니다.
  8. [Roles] 창의 검색 창에 생성한 역할의 이름을 입력한 다음 검색 결과에서 해당 역할을 선택합니다.
  9. [Summary] 창에서 [Role ARN]을 복사합니다. 다음 섹션에서 이 Amazon 리소스 이름(ARN)이 필요합니다.

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

API Gateway 콘솔에서 IAM 역할 추가

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

  1. API Gateway 콘솔API 창에서 생성한 API 이름을 선택합니다.
  2. 왼쪽 탐색 창의 하단에서 [Settings(설정)]을 선택합니다.
  3. [Settings(설정)] 아래 [CloudWatch log 역할 ARN]에 복사한 IAM 역할 ARN을 붙여 넣습니다.
  4. [저장]을 선택합니다.
    참고: 콘솔은 ARN의 저장 여부를 확인하지 않습니다.

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

  1. API Gateway 콘솔에서 API에 대한 [Stage Editor(스테이지 편집기)]를 찾습니다.
  2. [Stage Editor(스테이지 편집기)] 창에서 [Logs/Tracing(로그/추적)] 탭을 선택합니다.
  3. [Logs/Tracing(로그/추적)] 탭의 [CloudWatch Settings(CloudWatch 설정)]에서 다음을 수행하여 실행 로깅을 활성화합니다.
    [Enable CloudWatch Logs(CloudWatch Logs 활성화)] 확인란을 선택합니다.
    [Log level(로그 수준)]에서 [INFO]를 선택하여 모든 요청에 대한 실행 로그를 생성합니다. 또는 오류를 발생시키는 API에 대한 요청에 대해서만 실행 로그를 생성하려면 [ERROR]를 선택합니다.
    REST API에 대해 [Log full requests/responses data(전체 요청/응답 데이터 로그)] 확인란을 선택합니다. 또는 WebSocket API에 대해 [Log full message data(전체 메시지 데이터 로그)] 확인란을 선택합니다.
  4. [Custom Access Logging(사용자 지정 액세스 로깅)]에서 다음을 수행하여 액세스 로깅을 활성화합니다.
    [Enable Access Logging(액세스 로깅 활성화)] 확인란을 선택합니다.
    [Access Log Destination ARN(액세스 로그 대상 ARN)]에 CloudWatch 로그 그룹 또는 Amazon Kinesis Data Firehose 스트림의 ARN을 입력합니다.
    [Log Format(로그 형식)]을 입력합니다. 지침은 CLF, JSON, XML 또는 CSV를 선택하여 해당 형식의 예제를 볼 수 있습니다.
  5. [Save Changes(변경 내용 저장)]를 선택하십시오.
    참고: 콘솔은 이러한 설정이 성공적으로 저장되었는지 확인하지 않습니다.

자세한 내용은 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. [Log Streams(로그 스트림)] 목록에서 최신 Last Event Time이 있는 로그 스트림을 선택하여 요청의 실행 또는 액세스 세부 정보가 포함된 메시지를 확인합니다.

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