API Gateway에서 WebSocket API 로깅 구성 - Amazon API Gateway

API Gateway에서 WebSocket API 로깅 구성

로깅을 활성화하여 CloudWatch Logs에 로그를 기록할 수 있습니다. CloudWatch의 API 로깅에는 실행 로깅과 액세스 로깅이라는 두 가지 유형이 있습니다. 실행 로깅에서 API Gateway는 CloudWatch Logs를 관리합니다. 이 프로세스에는 로그 그룹 및 로그 스트림을 생성하는 작업과 호출자의 요청 및 응답을 로그 스트림에 보고하는 작업이 포함됩니다.

액세스 로깅에서 API 개발자가 원하는 것은 누가 API에 액세스했고 호출자가 API에 어떻게 액세스했는지 로깅하는 것입니다. 자체 로그 그룹을 생성하거나 API Gateway에서 관리할 수 있는 기존 로그 그룹을 선택할 수 있습니다. 액세스 세부 정보를 지정하려면 $context 변수(선택한 형식으로 표현)를 선택하고 로그 그룹을 대상으로 선택합니다.

CloudWatch 로깅을 설정하는 자세한 방법은 API Gateway 콘솔을 사용하여 CloudWatch API 로깅 설정 단원을 참조하십시오.

로그 형식을 지정할 때 기록할 컨텍스트 변수를 선택할 수 있습니다. 다음 변수가 지원됩니다.

파라미터 설명
$context.apiId

식별자 API Gateway가 API에 할당합니다.
$context.authorize.error 권한 부여 오류 메시지입니다.
$context.authorize.latency 권한 부여 지연 시간(ms)입니다.
$context.authorize.status 권한 부여 시도에서 반환된 상태 코드입니다.
$context.authorizer.error 권한 부여자로부터 반환된 오류 메시지입니다.
$context.authorizer.integrationLatency Lambda 권한 부여자 지연 시간(ms)입니다.
$context.authorizer.integrationStatus Lambda 권한 부여자로부터 반환된 상태 코드입니다.
$context.authorizer.latency 권한 부여자 지연 시간(ms)입니다.
$context.authorizer.requestId AWS 엔드포인트의 요청 ID입니다.
$context.authorizer.status 권한 부여자로부터 반환된 상태 코드입니다.
$context.authorizer.principalId

클라이언트가 전송한 토큰에 연결되고 API Gateway Lambda 권한 부여자 Lambda 함수에서 반환되는 보안 주체 사용자 ID입니다. (이전에는 Lambda를 사용자 지정 권한 부여자라고도 함).
$context.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" 문자열이 반환됩니다.
$context.authenticate.error 인증 시도에서 반환된 오류 메시지입니다.
$context.authenticate.latency 인증 지연 시간(ms)입니다.
$context.authenticate.status 인증 시도에서 반환된 상태 코드입니다.
$context.connectedAt

Epoch 형식 연결 시간입니다.
$context.connectionId

클라이언트에 대한 콜백을 만드는 데 사용할 수 있는 고유한 연결 ID입니다.
$context.domainName

WebSocket API의 도메인 이름입니다. 이 이름은 하드 코딩된 값 대신에 클라이언트를 콜백하는 데 사용할 수 있습니다.
$context.error.message

API Gateway 오류 메시지가 포함된 문자열입니다.
$context.error.messageString $context.error.message의 따옴표 붙은 값, 즉 "$context.error.message"입니다.
$context.error.responseType

오류 응답 유형.
$context.error.validationErrorString

자세한 유효성 검사 오류 메시지가 포함된 문자열입니다.
$context.eventType

이벤트 유형: CONNECT, MESSAGE 또는 DISCONNECT.
$context.extendedRequestId $context.requestId와 동일합니다.
$context.identity.accountId

요청과 연결된 AWS 계정 ID입니다.
$context.identity.apiKey

키가 활성화된 API 요청에 연결된 API 소유자 키입니다.
$context.identity.apiKeyId 키가 활성화된 API 요청에 연결된 API 키 ID입니다.
$context.identity.caller

요청에 서명한 호출자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다.
$context.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 개발자 안내서의 페더레이션 자격 증명 사용을 참조하세요.
$context.identity.cognitoAuthenticationType

요청을 작성한 호출자의 Amazon Cognito 인증 유형입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다. 가능한 값에는 인증 자격 증명에 대한 authenticated 및 미인증 자격 증명에 대한 unauthenticated이(가) 포함됩니다.
$context.identity.cognitoIdentityId

요청을 작성한 호출자의 Amazon Cognito 자격 증명 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다.
$context.identity.cognitoIdentityPoolId

요청을 작성한 호출자의 Amazon Cognito 자격 증명 풀 ID입니다. Amazon Cognito 자격 증명으로 요청을 서명한 경우에만 사용할 수 있습니다.
$context.identity.principalOrgId

AWS 조직 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다.
$context.identity.sourceIp

API 게이트웨이에 대한 요청을 작성한 TCP 연결의 소스 IP 주소입니다.
$context.identity.user

리소스 액세스에 대해 권한을 부여할 사용자의 보안 주체 ID입니다. IAM 권한 부여를 사용하는 라우팅에 대해 지원됩니다.
$context.identity.userAgent

API 호출자의 사용자 에이전트입니다.
$context.identity.userArn

인증 후 식별된 실제 사용자의 ARN(Amazon Resource Name)입니다.
$context.integration.error 통합에서 반환된 오류 메시지입니다.
$context.integration.integrationStatus Lambda 프록시 통합의 경우 백엔드 Lambda 함수 코드가 아니라 AWS Lambda에서 반환된 상태 코드입니다.
$context.integration.latency 통합 지연 시간(ms)입니다. $context.integrationLatency와 동일합니다.
$context.integration.requestId AWS 엔드포인트의 요청 ID입니다. $context.awsEndpointRequestId와 동일합니다.
$context.integration.status 통합에서 반환된 상태 코드입니다. Lambda 프록시 통합의 경우 Lambda 함수 코드에서 반환된 상태 코드입니다. $context.integrationStatus와 동일합니다.
$context.integrationLatency 통합 지연 시간(밀리초)으로서 액세스 로깅에만 사용할 수 있습니다.
$context.messageId

메시지의 고유 서버 측 ID. $context.eventType이 MESSAGE인 경우에만 사용 가능합니다.
$context.requestId

$context.extendedRequestId와 동일합니다.
$context.requestTime CLF 형식 요청 시간(dd/MMM/yyyy:HH:mm:ss +-hhmm)입니다.
$context.requestTimeEpoch Epoch 형식 요청 시간(밀리초)입니다.
$context.routeKey

선택한 라우팅 키.
$context.stage

API 호출의 개발 단계입니다(예: 베타 또는 프로덕션).
$context.status

응답 상태입니다.
$context.waf.error 에서 반환된 오류 메시지입니다AWS WAF
$context.waf.latency AWS WAF 지연 시간(ms)입니다.
$context.waf.status AWS WAF에서 반환된 상태 코드입니다.

일반적으로 사용되는 몇 가지 액세스 로그 형식의 예가 API Gateway 콘솔에 표시되며 다음과 같이 나열됩니다.

  • CLF(Common Log Format):

    $context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId

    연속 문자(\)는 시각적 보조 수단으로 사용됩니다. 로그 형식은 한 줄이어야 합니다. 로그 형식의 끝에 줄바꿈 문자(\n)를 추가하여 각 로그 항목의 끝에 줄바꿈 문자를 포함할 수 있습니다.

  • JSON: 

    {
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}

    연속 문자(\)는 시각적 보조 수단으로 사용됩니다. 로그 형식은 한 줄이어야 합니다. 로그 형식의 끝에 줄바꿈 문자(\n)를 추가하여 각 로그 항목의 끝에 줄바꿈 문자를 포함할 수 있습니다.

  • XML: 

    <request id="$context.requestId"> \
 <ip>$context.identity.sourceIp</ip> \
 <caller>$context.identity.caller</caller> \
 <user>$context.identity.user</user> \
 <requestTime>$context.requestTime</requestTime> \
 <eventType>$context.eventType</eventType> \
 <routeKey>$context.routeKey</routeKey> \
 <status>$context.status</status> \
 <connectionId>$context.connectionId</connectionId> \
</request>

    연속 문자(\)는 시각적 보조 수단으로 사용됩니다. 로그 형식은 한 줄이어야 합니다. 로그 형식의 끝에 줄바꿈 문자(\n)를 추가하여 각 로그 항목의 끝에 줄바꿈 문자를 포함할 수 있습니다.

  • CSV(쉼표로 분리된 값):

    $context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId

    연속 문자(\)는 시각적 보조 수단으로 사용됩니다. 로그 형식은 한 줄이어야 합니다. 로그 형식의 끝에 줄바꿈 문자(\n)를 추가하여 각 로그 항목의 끝에 줄바꿈 문자를 포함할 수 있습니다.