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

로그 출력을 JSON 키-값 쌍으로 캡처하면 함수를 디버깅할 때 검색과 필터링이 더 쉬워져요. JSON 형식 로그를 사용하면 로그에 태그와 컨텍스트 정보를 추가할 수도 있어요. 이는 대량의 로그 데이터를 자동으로 분석하는 데 도움이 될 수 있어요. 개발 워크플로가 일반 텍스트로 Lambda 로그를 소비하는 기존 도구에 의존하지 않는다면, 로그 형식으로 JSON을 선택하는 것을 권장해요.

Lambda Managed Instances Lambda Managed Instances는 JSON 로그 형식만 지원해요. Managed Instances 함수를 만들면 Lambda가 로그 형식을 자동으로 JSON으로 구성하며 일반 텍스트로 변경할 수 없어요. Managed Instances에 대한 자세한 내용은 Lambda Managed Instances를 참고하세요.

모든 Lambda 관리형 런타임에서 함수의 시스템 로그를 구조화되지 않은 일반 텍스트나 JSON 형식으로 CloudWatch Logs에 보낼지 선택할 수 있어요. 시스템 로그는 Lambda가 생성하는 로그로, 플랫폼 이벤트 로그라고도 해요.

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

지원되는 런타임에서 함수가 지원되는 로깅 라이브러리나 방법을 사용한다면, Lambda가 구조화된 JSON으로 로그를 캡처하기 위해 기존 코드를 변경할 필요가 없어요.

참고(Note) JSON 로그 형식을 사용하면 추가 메타데이터가 추가되고 로그 메시지가 일련의 키-값 쌍을 포함하는 JSON 객체로 인코딩돼요. 이 때문에 함수의 로그 메시지 크기가 커질 수 있어요.

출처: AWS Lambda 개발자 안내서

본문

지원되는 런타임 및 로깅 방법

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

언어	지원 버전
Java	Amazon Linux 1의 Java 8을 제외한 모든 Java 런타임
.NET	.NET 8 이상
Node.js	Node.js 16 이상
Python	Python 3.8 이상
Ruby	Ruby 4.0 이상
Rust	해당 없음

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

Java: LambdaLogger 로거 또는 Log4j2. 자세한 내용은 Java Lambda 함수 로그 및 모니터링을 참고하세요.
.NET: 컨텍스트 객체의 ILambdaLogger 인스턴스. 자세한 내용은 C# Lambda 함수 로그 및 모니터링을 참고하세요.
Node.js – 콘솔 메서드 console.trace, console.debug, console.log, console.info, console.error, console.warn. 자세한 내용은 Node.js Lambda 함수 로그 및 모니터링을 참고하세요.
Python: 표준 Python logging 라이브러리. 자세한 내용은 Python Lambda 함수 로그 및 모니터링을 참고하세요.
Ruby: 표준 Ruby Logger 라이브러리. 자세한 내용은 Ruby Lambda 함수 로그 및 모니터링을 참고하세요.
Rust: tracing 크레이트. 자세한 내용은 Rust Lambda 함수 로그 및 모니터링을 참고하세요.

다른 관리형 Lambda 런타임의 경우 Lambda는 현재 구조화된 JSON 형식으로 시스템 로그를 캡처하는 것을 기본적으로만 지원해요. 다만 Powertools for AWS Lambda처럼 JSON 형식의 로그 출력을 생성하는 로깅 도구를 사용하면 모든 런타임에서 애플리케이션 로그를 구조화된 JSON 형식으로 캡처할 수 있어요.

기본 로그 형식

현재 모든 Lambda 런타임의 기본 로그 형식은 일반 텍스트예요. Lambda Managed Instances의 경우 로그 형식은 항상 JSON이며 변경할 수 없어요.

Powertools for AWS Lambda 같은 로깅 라이브러리를 이미 사용해서 함수 로그를 JSON 구조화 형식으로 생성하고 있다면, JSON 로그 형식을 선택해도 코드를 변경할 필요가 없어요. Lambda는 이미 JSON 인코딩된 로그를 이중 인코딩하지 않으므로 함수의 애플리케이션 로그는 이전과 동일하게 캡처돼요.

시스템 로그의 JSON 형식

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

"time" – 로그 메시지가 생성된 시간
"type" – 로깅되는 이벤트의 유형
"record" – 로그 출력의 내용

"record" 값의 형식은 로깅되는 이벤트 유형에 따라 달라져요. 자세한 내용은 Telemetry 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

예시 구조화된 JSON:

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

참고(Note) Telemetry API를 사용해 확장의 실시간 텔레메트리 데이터 접근은 START와 REPORT 같은 플랫폼 이벤트를 항상 JSON 형식으로 생성해요. Lambda가 CloudWatch로 보내는 시스템 로그의 형식을 구성해도 Lambda Telemetry API 동작에는 영향을 주지 않아요.

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

함수의 로그 형식을 JSON으로 구성하면 지원되는 로깅 라이브러리와 방법으로 작성된 애플리케이션 로그 출력이 다음 키를 가진 키-값 쌍을 포함하는 JSON 객체로 캡처돼요.

"timestamp" – 로그 메시지가 생성된 시간
"level" – 메시지에 할당된 로그 수준
"message" – 로그 메시지의 내용
"requestId"(Python, .NET, Node.js) 또는 "AWSrequestId"(Java) – 함수 호출의 고유 요청 ID

함수가 사용하는 런타임과 로깅 방법에 따라 이 JSON 객체에는 추가 키 쌍이 포함될 수도 있어요. 예를 들어 Node.js에서 함수가 여러 인수를 사용해서 오류 객체를 로깅하기 위해 console 메서드를 사용하면 JSON 객체에는 errorMessage, errorType, stackTrace 키가 있는 추가 키-값 쌍이 포함돼요. 다른 Lambda 런타임의 JSON 형식 로그에 대해 자세히 알아보려면 Python Lambda 함수 로그 및 모니터링, Node.js Lambda 함수 로그 및 모니터링, Java Lambda 함수 로그 및 모니터링을 참고하세요.

참고(Note) Lambda가 타임스탬프 값에 사용하는 키는 시스템 로그와 애플리케이션 로그에서 달라요. 시스템 로그의 경우 Lambda는 Telemetry API와의 일관성을 유지하기 위해 "time" 키를 사용해요. 애플리케이션 로그의 경우 Lambda는 지원되는 런타임의 규칙을 따라 "timestamp"를 사용해요.

비교를 위해 다음 두 예시는 같은 로그 출력을 일반 텍스트와 구조화된 JSON 형식으로 보여줘요.

예시 일반 텍스트:

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

예시 구조화된 JSON:

{
    "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 리소스, CloudFormation AWS::Lambda::Function 리소스로 함수의 로그 형식을 구성할 수 있어요.

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

함수의 로그 형식을 JSON으로 변경하고 로그 수준을 설정하지 않으면 Lambda가 함수의 애플리케이션 로그 수준과 시스템 로그 수준을 자동으로 INFO로 설정해요. 즉 Lambda는 INFO 수준 이하의 로그 출력만 CloudWatch Logs로 보내요. 애플리케이션 및 시스템 로그 수준 필터링에 대해 자세히 알아보려면 로그 수준 필터링을 참고하세요.

참고(Note) Python 런타임의 경우 함수의 로그 형식이 일반 텍스트로 설정되어 있으면 기본 로그 수준 설정은 WARN이에요. 즉 Lambda는 WARN 수준 이하의 로그 출력만 CloudWatch Logs로 보내요. 함수의 로그 형식을 JSON으로 변경하면 이 기본 동작이 바뀌어요. Python 로깅에 대해 자세히 알아보려면 Python Lambda 함수 로그 및 모니터링을 참고하세요.

임베디드 메트릭 형식(EMF) 로그를 생성하는 Node.js 함수의 경우 함수의 로그 형식을 JSON으로 변경하면 CloudWatch가 메트릭을 인식하지 못할 수 있어요.

중요(Important) 함수가 Powertools for AWS Lambda(TypeScript)나 오픈 소스 EMF 클라이언트 라이브러리를 사용해 EMF 로그를 생성한다면 Powertools와 EMF 라이브러리를 최신 버전으로 업데이트해서 CloudWatch가 로그를 계속 올바르게 파싱할 수 있게 하세요. JSON 로그 형식으로 전환하면 함수의 임베디드 메트릭과의 호환성을 보장하기 위해 테스트도 수행하는 것을 권장해요. EMF 로그를 생성하는 Node.js 함수에 대한 추가 조언은 구조화된 JSON 로그와 함께 임베디드 메트릭 형식(EMF) 클라이언트 라이브러리 사용을 참고하세요.

함수의 로그 형식 구성(콘솔)

Lambda 콘솔의 Functions 페이지를 열어요.
함수를 선택해요.
함수 구성 페이지에서 Monitoring and operations tools을 선택해요.
Logging configuration 창에서 Edit을 선택해요.
Log content의 Log format에서 Text 또는 JSON을 선택해요.
Save를 선택해요.

기존 함수의 로그 형식 변경(AWS CLI)

기존 함수의 로그 형식을 변경하려면 update-function-configuration 명령을 사용해요. LoggingConfig의 LogFormat 옵션을 JSON 또는 Text로 설정해요.
```
aws lambda update-function-configuration \
  --function-name myFunction \
  --logging-config LogFormat=JSON
```

함수를 만들 때 로그 형식 설정(AWS CLI)

새 함수를 만들 때 로그 형식을 구성하려면 create-function 명령의 --logging-config 옵션을 사용해요. LogFormat을 JSON 또는 Text로 설정해요. 다음 예시 명령은 구조화된 JSON으로 로그를 출력하는 Node.js 함수를 만들어요.

함수를 만들 때 로그 형식을 지정하지 않으면 Lambda는 선택한 런타임 버전의 기본 로그 형식을 사용해요. 기본 로그 형식에 대한 정보는 기본 로그 형식을 참고하세요.
```
aws lambda create-function \ 
  --function-name myFunction \ 
  --runtime nodejs24.x \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --role arn:aws:iam::123456789012:role/LambdaRole \
  --logging-config LogFormat=JSON
```

더 알아보기 (Learn more)

시스템 및 애플리케이션 로그 수준 필터링에 대한 자세한 내용은 로그 수준 필터링을 참고하세요.