액세스 로그로 일반 API 게이트웨이 오류 디버깅

액세스 로깅을 활성화하고 기본 로그 개체에 오류 메시지를 추가하면 API 게이트웨이 오류 디버깅을 더 쉽게 할 수 있습니다. 이 작은 트릭은 일반적인 오류 메시지를 받을 때 종종 도움이 됩니다.

1. 문제 진술

나는 요 전에 Amazon API Gateway HTTP API을 가지고 놀고 있었고 (자세한 내용은 향후 게시물에서) 경로 중 하나에 Lambda integration을 추가했습니다.

경로는 /pets/{proxy+} 형식이어야 합니다.

Postman 에서 API를 호출했을 때 일반 500 Internal server error 을 받았습니다.

다른 AWS 오류와 마찬가지로 이 메시지도 도움이 되지 않았습니다.

2. 디버깅 프로세스

함수의 Lambda 로그 그룹에 아무것도 표시되지 않았기 때문에 요청이 CloudWatch 통합을 호출하지 않았습니다.

API 게이트웨이 내부(가능성이 낮음) 또는 게이트웨이와 함수 사이에 문제가 발생했을 것입니다.

2.1. 로그 그룹 생성

특히 개발 단계에 있을 때 API에 대한 액세스 로깅을 켜는 것이 좋습니다.

먼저 로그 그룹이 필요하므로 API Gateway가 액세스 로그를 보낼 CloudWatch에서 살펴보겠습니다create one.

2.2. 액세스 로깅 켜기

AWS 콘솔의 왼쪽 메뉴 하단에서 액세스 로깅을 켤 수 있습니다.



슬라이더로 액세스 로깅을 켠 후 위에서 생성한 로그 그룹의 ARN을 추가해야 합니다. 사용 가능한 로그 형식 중에서 JSON을 선택합니다.



API Gateway는 다음 객체를 CloudWatch에 기록합니다.

{
  "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"
}

기본 로깅 변수입니다.

2.3. 오류 메시지 추가

이 개체는 우리가 이미 알고 있는 대부분의 기본 정보만 제공합니다.

그러나 context 개체에는 더 많은 속성이 포함되어 있습니다. 그 중 두 가지가 특히 유용하다는 것을 알았습니다.
$context.integration.error 속성은 통합(이 경우 Lambda 함수)의 오류 메시지를 반환합니다. 요청이 함수 호출을 트리거하지 않더라도 Lambda는 여전히 오류를 반환할 수 있습니다. API Gateway는 여기에 해당 오류를 기록합니다.

두 번째로 추가한 오류는 $context.error.message 키의 값으로, API Gateway 자체에서 오류 메시지를 반환합니다.

그래서 로그 JSON에 다음 속성을 추가했습니다.

{
  "integrationError": "$context.integration.error",
  "apiGatewayError": "$context.error.message"
}

실제로 다음 호출에서 문제가 드러났습니다.

2.4. 한 번에 전체 경로 생성

apiGatewayError 반환 Internal Server Error , 그것은 나에게 새로운 것이 아니었다.

그러나 integrationError 속성은 실제 문제를 보여주었습니다.

The IAM role configured on the integration or API Gateway doesn't have
permission to call the integration. Check the permissions and try again.

처음에는 HTTP API 경로에 대한 Lambda 통합을 생성할 때 API Gateway가 함수를 호출하는 데 필요한 권한을 생성하기 때문에 오류 메시지가 이상했습니다. 보다 정확하게는 Lambda 함수의 리소스 기반 정책에 다음 정책을 추가합니다.

{
  "Effect": "Allow",
  "Principal": {
    "Service": "apigateway.amazonaws.com",
  },
  "Action": "lambda:InvokeFunction",
  "Resource": "arn:aws:lambda:us-east-1:ACCOUNT_ID:function:FUNCTION_NAME",
  "Condition": {
    "ArnLike": {
      // /{proxy+} is missing from the end!!!
      "AWS:SourceArn": "arn:aws:execute-api:us-east-1:ACCOUNT_ID:API_ID/*/*/pets"
    }
  }
}

문제는 Condition 블록에 있습니다. /{proxy+}가 ARN 끝에서 누락되었습니다. 그래서 /pets/SOMETHING를 호출했을 때 Lambda는 오류로 응답했습니다.

그 이유는 /pets 경로에 대한 통합을 먼저 생성했기 때문에 API Gateway는 리소스 기반 정책에 해당 권한을 추가했습니다. 그런 다음 이 방법이 나에게 적합하지 않다는 것을 깨닫고 경로를 편집하고 /{proxy}를 추가했습니다. 물론 API Gateway는 권한을 업데이트하지 않았습니다.

해결 방법은 Lambda 권한에 누락된 비트를 수동으로 추가하거나 API Gateway에서 최종 형식으로 경로를 생성하거나 권한을 생성하고 업데이트하는 Infrastructure as Code을 사용하는 것입니다.

액세스 로그를 사용하면 근본 원인을 찾는 것이 훨씬 쉬웠습니다. 다른 문제도 발견할 수 있으며 문제의 원인을 찾는 데 소요되는 시간을 절약할 수 있습니다. 시도해 볼 가치가 있습니다!

3. 요약

API Gateway 액세스 로깅은 일반적인 오류 메시지를 디버깅해야 할 때 유용할 수 있습니다.

로그 개체에는 사용 가능한 속성의 일부만 포함되어 있습니다. context 개체에서 오류 메시지를 추출하여 액세스 로그에 오류 메시지를 추가할 수 있습니다.

4. 추가 자료

Customizing HTTP API access logs - 더 많은 사용 가능한 로깅 변수

The Missing Guide to AWS API Gateway Access Logs - REST API의 액세스 로그에 대한 Alex DeBrie의 탁월한 가이드