View a markdown version of this page

REST API에 대한 실행 로깅 - Amazon API Gateway
표준 실행 로깅실행 로그에 대한 Amazon CloudWatch Logs 전송

REST API에 대한 실행 로깅

실행 로깅은 API Gateway가 API 요청을 처리하기 위해 수행하는 작업을 기록합니다. 로깅된 데이터에는 오류, 실행 추적, 요청 및 응답 파라미터 값 또는 페이로드, Lambda 권한 부여자가 사용하는 데이터, API 키가 필요한지 여부, 사용량 계획이 활성화되는지 여부 등이 포함됩니다. API Gateway는 로깅된 데이터에서 권한 부여 헤더, API 키 값 및 유사한 민감한 요청 파라미터를 삭제합니다.

보안 태세를 개선하려면 ERROR 또는 INFO 수준에서 실행 로깅을 사용하는 것이 좋습니다. 다양한 규정 준수 프레임워크를 준수하기 위해 이 작업을 수행해야 할 수 있습니다. 자세한 내용은 AWS Security Hub 사용 설명서에서 Amazon API Gateway 제어를 참조하세요.

표준 실행 로깅

스테이지에서 실행 로깅을 활성화하면 API Gateway가 CloudWatch Logs 로그 그룹을 자동으로 생성하고 관리합니다. 로그 그룹의 이름은 API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}입니다. 로그는 각 로그 그룹 내에서 로그 스트림으로 나뉘며, 마지막 이벤트 시간 기준으로 정렬됩니다.

표준 실행 로깅 사용 시:

  • 로그 이벤트는 1KB에서 잘립니다.

  • API Gateway는 로그 그룹 이름을 관리합니다. 로그 그룹 이름을 선택하거나 Amazon S3 또는 Firehose로 직접 로그를 전송할 수 없습니다.

표준 실행 로깅을 활성화하려면 스테이지의 loggingLevel을 ERROR 또는 INFO로 설정합니다. 추가 구성이 필요하지 않습니다.

권한

CloudWatch Logs를 활성화하려면 계정의 CloudWatch에 로그를 읽고 쓸 수 있는 권한을 API Gateway에 부여해야 합니다. AmazonAPIGatewayPushToCloudWatchLogs 관리형 정책에는 필요한 모든 권한이 있습니다.

신뢰할 수 있는 엔터티로 apigateway.amazonaws.com이 포함된 IAM 역할을 생성하고, 이전 정책을 연결한 다음, 계정의 cloudWatchRoleArn 속성에서 IAM 역할 ARN을 설정합니다. CloudWatch Logs를 활성화하려는 각 AWS 리전에 대해 이 속성을 개별적으로 설정해야 합니다.

참고

API Gateway는 IAM 역할을 수임하기 위해 AWS Security Token Service를 직접 호출하므로 AWS STS가 해당 리전에 대해 활성화되어 있는지 확인하세요. 자세한 내용은 AWS 리전에서 AWS STS 관리를 참조하세요.

실행 로깅 활성화(콘솔)

시작하기 전에 API를 스테이지에 배포하고 계정에 적합한 CloudWatch Logs 역할 ARN을 구성합니다.

  1. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

  2. 기본 탐색 창에서 설정을 선택한 다음 로깅에서 편집을 선택합니다.

  3. CloudWatch 로그 역할 ARN에서 적절한 권한이 있는 IAM 역할의 ARN을 입력합니다. API Gateway를 사용하여 API를 생성하는 AWS 계정마다 이 작업을 한 번씩 수행해야 합니다.

  4. 기본 탐색 창에서 API를 선택하고 REST API를 선택한 다음 스테이지를 선택합니다.

  5. 스테이지를 선택한 다음 로그 및 추적 섹션에서 편집을 선택합니다.

  6. CloudWatch Logs 드롭다운 메뉴에서 로깅 수준을 선택합니다.

    • 꺼짐 – API Gateway는 이 스테이지에 대한 요청을 로깅하지 않습니다.

    • 오류만 해당 – API Gateway는 오류만 로깅합니다.

    • 오류 및 정보 로그 – API Gateway는 모든 이벤트를 로깅합니다.

  7. (선택 사항) 전체 요청 및 응답 데이터를 로깅하려면 데이터 추적을 선택합니다. 이로 인해 민감한 데이터가 로깅될 수 있습니다.

    참고

    프로덕션 API에는 데이터 추적을 사용하지 않는 것이 좋습니다.

  8. (선택 사항) 세부 지표를 선택하여 CloudWatch 세부 지표를 활성화합니다. 자세한 내용은 섹션을 참조하세요Amazon CloudWatch 지표를 사용한 REST API 실행 모니터링

  9. 변경 사항 저장을 선택합니다.

스테이지 설정을 업데이트할 때 API를 다시 배포할 필요가 없습니다.

실행 로깅 활성화(CloudFormation)

스테이지 리소스의 MethodSettings 속성을 사용하여 실행 로깅을 활성화합니다.

  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO

CloudWatch Logs를 활성화하려면 계정의 CloudWatch에 로그를 읽고 쓸 수 있는 권한을 API Gateway에 부여해야 합니다. 자세한 내용은 AWS CloudFormation 사용 설명서의 계정과 IAM 역할 연결을 참조하세요.

실행 로그에 대한 Amazon CloudWatch Logs 전송

Amazon CloudWatch Logs 전송은 실행 로그에 대한 대체 경로를 제공합니다. API Gateway 관리형 로그 그룹에 쓰는 대신 소유하고 제어하는 대상으로 실행 로그를 보내는 전송을 구성합니다.

Amazon CloudWatch Logs 전송 사용 시:

  • 로그 이벤트는 최대 1MB까지 가능하며, 더 완전한 요청 및 응답 데이터를 캡처할 수 있습니다. 1MB를 초과하는 페이로드는 계속 잘립니다.

  • 대상을 선택하는 경우: CloudWatch Logs 로그 그룹, Amazon S3 버킷 또는 Firehose 스트림을 소유합니다.

  • 여러 대상으로 동시에 로그를 전송할 수 있습니다.

  • 이름 지정 및 보존을 포함하여 로그 그룹 구성을 제어합니다.

중요

CloudWatch Logs 전송은 표준 실행 로깅을 대체합니다. 전송을 구성하면 API Gateway가 자동 관리형 로그 그룹에 대한 쓰기를 중지합니다. 동일한 스테이지에서 두 경로를 동시에 사용할 수는 없습니다.

전송을 생성하면 API Gateway는 자동 관리형 로그 그룹 대신 구성된 대상으로 실행 로그를 라우팅합니다. 전송을 삭제하면 실행 로그가 자동 관리형 로그 그룹으로 자동으로 다시 흐르기 시작합니다. loggingLevel을 ERROR 또는 INFO로 설정하는 사전 조건 외에는 API Gateway 구성 변경이 필요하지 않습니다.

참고

로그 전송은 최선의 작업을 기반으로 이루어집니다. 드문 경우지만 일부 로그 이벤트가 전송되지 않을 수 있습니다.

주의

로그 전송을 활성화하기 전에 자동 관리형 로그 그룹(API-Gateway-Execution-Logs_{rest-api-id}/{stage_name})을 참조하는 대시보드, 경보 또는 구독 필터를 업데이트합니다. 전송이 활성화되면 해당 로그 그룹은 더 이상 새 이벤트를 수신하지 않습니다.

다음 표에서는 표준 실행 로깅을 Amazon CloudWatch Logs 전송과 비교합니다.

표준 실행 로깅 Amazon CloudWatch Logs 전송
최대 로그 이벤트 크기 1KB 1MB
대상 CloudWatch Logs(관리형 로그 그룹) CloudWatch Logs, Amazon S3, Firehose(자체 리소스)
여러 대상 아니요 예
로그 그룹 이름 API Gateway에서 수정 직접 선택
설정 로깅이 활성화된 경우 자동 Amazon CloudWatch Logs 전송 생성 필요
사전 조건 loggingLevel을 ERROR 또는 INFO로 설정 loggingLevel을 ERROR 또는 INFO로 설정
참고

전송을 구성한 후 loggingLevel을 OFF로 설정하면 실행 로그가 생성되지 않거나 전송되지 않습니다. 전송 대상은 구성된 상태로 유지되지만 데이터를 수신하지 않습니다.

전송을 생성하려면 REST API 실행 로그에 대한 로그 전송 생성를 참조하세요.