JSON 및 일반 텍스트 로그 형식 구성

로그 출력을 JSON 키 값 쌍으로 캡처하면 함수를 디버깅할 때 더 쉽게 검색하고 필터링할 수 있습니다. JSON 형식의 로그를 사용하면 로그에 태그와 컨텍스트 정보를 추가할 수도 있습니다. 이를 통해 대량의 로그 데이터를 자동으로 분석할 수 있습니다. 개발 워크플로가 Lambda 로그를 일반 텍스트로 사용하는 기존 도구를 사용하지 않는 한, 로그 형식으로 JSON을 선택하는 것이 좋습니다.

모든 Lambda 관리형 런타임의 경우, 함수의 시스템 로그를 구조화되지 않은 일반 텍스트와 JSON 형식 중 어떻게 CloudWatch Logs에 보낼지 선택할 수 있습니다. 시스템 로그는 Lambda가 생성하는 로그이며 플랫폼 이벤트 로그라고도 합니다.

지원되는 런타임의 경우, 지원되는 내장 로깅 방법 중 하나를 사용하면 Lambda는 함수의 애플리케이션 로그(함수 코드가 생성하는 로그)를 구조화된 JSON 형식으로 출력할 수도 있습니다. 이러한 런타임에 대해 함수의 로그 형식을 구성할 때 선택한 구성이 시스템 및 애플리케이션 로그 모두에 적용됩니다.

지원되는 런타임의 경우 함수가 지원되는 로깅 라이브러리 또는 메서드를 사용하는 경우 구조화된 JSON으로 로그를 캡처하기 위해 Lambda의 기존 코드를 변경할 필요가 없습니다.

지원되는 런타임 및 로깅 메서드

Lambda는 현재 다음 런타임에 대해 JSON 구조화된 애플리케이션 로그를 출력하는 옵션을 지원합니다.

Lambda가 함수의 애플리케이션 로그를 구조화된 JSON 형식으로 CloudWatch에 보내려면 함수가 다음과 같은 내장 로깅 도구를 사용하여 로그를 출력해야 합니다.

지원되는 런타임으로 고급 로깅 컨트롤을 사용하는 방법에 대한 자세한 내용은 Java Lambda 함수 로깅 및 모니터링, Node.js Lambda 함수 로깅 및 모니터링 및 Python Lambda 함수 로깅 및 모니터링을 참조하십시오.

다른 관리형 Lambda 런타임의 경우, Lambda는 현재 구조화된 JSON 형식의 시스템 로그 캡처만 기본적으로 지원합니다. 하지만 JSON 형식의 로그 출력 출력에 대해 AWS Lambda용 Powertools와 같은 로깅 도구를 사용하면 모든 런타임에서 구조화된 JSON 형식으로 애플리케이션 로그를 캡처할 수 있습니다.

기본 로그 형식

현재 모든 Lambda 런타임의 기본 로그 형식은 일반 텍스트입니다.

이미 AWS Lambda용 Powertools과 같은 로깅 라이브러리를 사용하여 함수 로그를 JSON 구조 형식으로 생성하고 있다면 JSON 로그 형식 지정을 선택하면 코드를 변경할 필요가 없습니다. Lambda는 이미 JSON으로 인코딩된 로그를 이중 인코딩하지 않으므로 함수의 애플리케이션 로그는 이전과 같이 계속 캡처됩니다.

시스템 로그의 JSON 형식

함수의 로그 형식을 JSON으로 구성하면 각 시스템 로그 항목(플랫폼 이벤트)이 다음 키가 있는 키 값 쌍을 포함하는 JSON 객체로 캡처됩니다.

"record" 값 형식은 로그되는 이벤트 유형에 따라 달라집니다. 자세한 내용은 텔레메트리 API Event 객체 유형을 참조하세요. 시스템 로그 이벤트에 할당된 로그 수준에 대한 자세한 내용은 시스템 로그 수준 이벤트 매핑을 참조하세요.

비교를 위해 다음 두 예제는 일반 텍스트 형식과 구조화된 JSON 형식 모두에서 동일한 로그 출력을 보여줍니다. 대부분의 경우 시스템 로그 이벤트는 JSON 형식으로 출력할 때 일반 텍스트로 출력할 때보다 더 많은 정보를 포함합니다.

2024-03-13 18:56:24.046000 fbe8c1   INIT_START  Runtime Version: python:3.12.v18  Runtime Version ARN: arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0

{
  "time": "2024-03-13T18:56:24.046Z",
  "type": "platform.initStart",
  "record": {
    "initializationType": "on-demand",
    "phase": "init",
    "runtimeVersion": "python:3.12.v18",
    "runtimeVersionArn": "arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0"
  }
}

애플리케이션 로그의 JSON 형식

함수의 로그 형식을 JSON으로 구성하면 지원되는 로깅 라이브러리 및 메서드를 사용하여 작성된 애플리케이션 로그 출력이 다음 키와 함께 키 값 페어를 포함하는 JSON 객체로 캡처됩니다.

함수에서 사용하는 런타임 및 로깅 방법에 따라 이 JSON 객체에 추가 키 페어가 포함될 수도 있습니다. 예를 들어 Node.js에서 함수가 console 메서드를 통해 여러 인수를 사용하여 오류 객체를 기록하는 경우 JSON 객체에는 키 errorMessage, errorType, stackTrace와 함께 추가 키 값 페어가 포함됩니다. 다양한 Lambda 런타임에서 JSON 형식 로그에 대한 자세한 내용은 Python Lambda 함수 로깅 및 모니터링, Node.js Lambda 함수 로깅 및 모니터링, Java Lambda 함수 로깅 및 모니터링 섹션을 참조하세요.

비교를 위해 다음 두 예제는 일반 텍스트 형식과 구조화된 JSON 형식 모두에서 동일한 로그 출력을 보여줍니다.

2024-10-27T19:17:45.586Z 79b4f56e-95b1-4643-9700-2807f4e68189 INFO some log message

{
    "timestamp":"2024-10-27T19:17:45.586Z",
    "level":"INFO",
    "message":"some log message",
    "requestId":"79b4f56e-95b1-4643-9700-2807f4e68189"
}

함수의 로그 형식 설정

함수의 로그 형식을 구성하려면 Lambda 콘솔 또는 AWS Command Line Interface(AWS CLI)을 사용할 수 있습니다. CreateFunction 및 UpdateFunctionConfiguration Lambda API 명령, AWS Serverless Application Model(AWS SAM) AWS::Serverless::Function 리소스, AWS CloudFormation AWS::Lambda::Function 리소스를 사용하여 함수의 로그 형식을 구성할 수도 있습니다.

함수의 로그 형식을 변경해도 CloudWatch Logs에 저장된 기존 로그에는 영향을 주지 않습니다. 새 로그만 업데이트된 형식을 사용합니다.

함수의 로그 형식을 JSON으로 변경하고 로그 수준을 설정하지 않으면 Lambda는 함수의 애플리케이션 로그 수준과 시스템 로그 수준을 정보로 자동 설정합니다. 즉, Lambda는 정보 수준 이하의 로그 출력만 CloudWatch Logs로 전송합니다. 애플리케이션 및 시스템 로그 수준 필터링에 대한 자세한 내용은 로그 수준 필터링 섹션을 참조하세요.

임베디드 지표 형식 (EMF) 로그를 내보내는 Node.js 함수의 경우 함수의 로그 형식을 JSON으로 변경하면 CloudWatch에서 지표를 인식하지 못할 수 있습니다.