# 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 | 메서드 응답 상태입니다. |