로그 수준 필터링
로그 수준 필터링 (Log-level filtering)
Lambda는 함수의 로그를 필터링해 일정 상세 수준 이하의 로그만 CloudWatch Logs로 보내도록 할 수 있습니다. 함수의 시스템 로그(Lambda가 생성하는 로그)와 애플리케이션 로그(함수 코드가 생성하는 로그)에 대해 로그 수준 필터링을 별도로 구성할 수 있습니다.
지원되는 런타임과 로깅 방법의 경우 Lambda가 함수의 애플리케이션 로그를 필터링하도록 함수 코드를 변경할 필요가 없습니다.
그 외의 모든 런타임과 로깅 방법의 경우 함수 코드는 "level" 키를 가진 키-값 쌍이 포함된 JSON 형식 객체로 로그 이벤트를 stdout이나 stderr에 출력해야 합니다. 예를 들어 Lambda는 다음 stdout 출력을 DEBUG 수준 로그로 해석합니다.
print('{"level": "debug", "msg": "my debug log", "timestamp": "2024-11-02T16:51:31.587199Z"}')
"level" 값 필드가 유효하지 않거나 없으면 Lambda는 로그 출력에 INFO 수준을 할당합니다. Lambda가 timestamp 필드를 사용하려면 유효한 RFC 3339 타임스탬프 형식으로 시간을 지정해야 합니다. 유효한 타임스탬프를 제공하지 않으면 Lambda는 로그에 INFO 수준을 할당하고 타임스탬프를 추가합니다.
timestamp 키 이름을 지정할 때는 사용 중인 런타임의 규칙을 따르세요. Lambda는 관리형 런타임이 사용하는 대부분의 일반적인 명명 규칙을 지원합니다.
참고
로그 수준 필터링을 사용하려면 함수가 JSON 로그 형식을 사용하도록 구성되어야 합니다. 모든 Lambda 관리형 런타임의 기본 로그 형식은 현재 일반 텍스트입니다. 함수의 로그 형식을 JSON으로 구성하는 방법을 알아보려면 함수의 로그 형식 설정을 참조하세요.
애플리케이션 로그(함수 코드가 생성하는 로그)의 경우 다음 로그 수준 중에서 선택할 수 있습니다:
| 로그 수준 | 표준 용도 |
|---|---|
| TRACE (가장 상세) | 코드 실행 경로를 추적하는 데 사용되는 가장 세분화된 정보 |
| DEBUG | 시스템 디버깅을 위한 상세 정보 |
| INFO | 함수의 정상 작동을 기록하는 메시지 |
| WARN | 해결하지 않으면 예기치 않은 동작으로 이어질 수 있는 잠재적 오류에 대한 메시지 |
| ERROR | 코드가 예상대로 수행되지 못하게 하는 문제에 대한 메시지 |
| FATAL (가장 덜 상세) | 애플리케이션이 작동을 멈추게 하는 심각한 오류에 대한 메시지 |
로그 수준을 선택하면 Lambda는 해당 수준 이하의 로그를 CloudWatch Logs로 보냅니다. 예를 들어 함수의 애플리케이션 로그 수준을 WARN으로 설정하면 Lambda는 INFO와 DEBUG 수준의 로그 출력을 보내지 않습니다. 로그 필터링의 기본 애플리케이션 로그 수준은 INFO입니다.
Lambda가 함수의 애플리케이션 로그를 필터링할 때 수준이 없는 로그 메시지에는 INFO 로그 수준이 할당됩니다.
시스템 로그(Lambda 서비스가 생성하는 로그)의 경우 다음 로그 수준 중에서 선택할 수 있습니다:
| 로그 수준 | 용도 |
|---|---|
| DEBUG (가장 상세) | 시스템 디버깅을 위한 상세 정보 |
| INFO | 함수의 정상 작동을 기록하는 메시지 |
| WARN (가장 덜 상세) | 해결하지 않으면 예기치 않은 동작으로 이어질 수 있는 잠재적 오류에 대한 메시지 |
로그 수준을 선택하면 Lambda는 해당 수준 이하의 로그를 보냅니다. 예를 들어 함수의 시스템 로그 수준을 INFO로 설정하면 Lambda는 DEBUG 수준의 로그 출력을 보내지 않습니다.
기본적으로 Lambda는 시스템 로그 수준을 INFO로 설정합니다. 이 설정으로 Lambda는 "start"와 "report" 로그 메시지를 CloudWatch로 자동으로 보냅니다. 더 상세하거나 덜 상세한 시스템 로그를 받으려면 로그 수준을 DEBUG나 WARN으로 변경하세요. Lambda가 서로 다른 시스템 로그 이벤트를 매핑하는 로그 수준 목록을 보려면 시스템 로그 수준 이벤트 매핑을 참조하세요.
본문
로그 수준 필터링 구성
함수에 대한 애플리케이션 및 시스템 로그 수준 필터링을 구성하려면 Lambda 콘솔이나 AWS Command Line Interface(AWS CLI)를 사용할 수 있습니다. 또한 CreateFunction 및 UpdateFunctionConfiguration Lambda API 명령, AWS Serverless Application Model(AWS SAM)의 AWS::Serverless::Function 리소스, CloudFormation의 AWS::Lambda::Function 리소스로 함수의 로그 수준을 구성할 수 있습니다.
코드에서 함수의 로그 수준을 설정하면 이 설정이 구성하는 다른 모든 로그 수준 설정보다 우선합니다. 예를 들어 Python logging의 setLevel() 메서드로 함수의 로깅 수준을 INFO로 설정하면 이 설정은 Lambda 콘솔에서 구성한 WARN 설정보다 우선합니다.
기존 함수의 애플리케이션 또는 시스템 로그 수준 구성 (콘솔):
- Lambda 콘솔의 Functions(함수) 페이지를 엽니다.
- 함수를 선택합니다.
- 함수 구성 페이지에서 Monitoring and operations tools(모니터링 및 운영 도구) 를 선택합니다.
- Logging configuration(로깅 구성) 창에서 Edit(편집) 을 선택합니다.
- Log content(로그 콘텐츠) 아래에서 Log format(로그 형식) 이 JSON으로 선택되어 있는지 확인합니다.
- 라디오 버튼을 사용해 함수에 대해 원하는 Application log level(애플리케이션 로그 수준) 과 System log level(시스템 로그 수준) 을 선택합니다.
- Save(저장) 를 선택합니다.
기존 함수의 애플리케이션 또는 시스템 로그 수준 구성 (AWS CLI):
기존 함수의 애플리케이션 또는 시스템 로그 수준을 변경하려면 update-function-configuration 명령을 사용합니다. --logging-config로 SystemLogLevel을 DEBUG, INFO, WARN 중 하나로 설정합니다. ApplicationLogLevel을 DEBUG, INFO, WARN, ERROR, FATAL 중 하나로 설정합니다.
aws lambda update-function-configuration \
--function-name myFunction \
--logging-config LogFormat=JSON,ApplicationLogLevel=ERROR,SystemLogLevel=WARN
함수를 만들 때 로그 수준 필터링 구성:
새 함수를 만들 때 로그 수준 필터링을 구성하려면 --logging-config를 사용해 create-function 명령에서 SystemLogLevel과 ApplicationLogLevel 키를 설정합니다. SystemLogLevel을 DEBUG, INFO, WARN 중 하나로 설정합니다. ApplicationLogLevel을 DEBUG, INFO, WARN, ERROR, FATAL 중 하나로 설정합니다.
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,ApplicationLogLevel=ERROR,SystemLogLevel=WARN
시스템 로그 수준 이벤트 매핑
Lambda가 생성하는 시스템 수준 로그 이벤트에 대해 다음 표는 각 이벤트에 할당된 로그 수준을 정의합니다. 표에 나열된 이벤트에 대해 자세히 알아보려면 Lambda Telemetry API 이벤트 스키마 참조를 참조하세요.
| 이벤트 이름 | 조건 | 할당된 로그 수준 |
|---|---|---|
| initStart | runtimeVersion이 설정됨 | INFO |
| initStart | runtimeVersion이 설정되지 않음 | DEBUG |
| initRuntimeDone | status=success | DEBUG |
| initRuntimeDone | status!=success | WARN |
| initReport | initializationType!=on-demand | INFO |
| initReport | initializationType=on-demand | DEBUG |
| initReport | status!=success | WARN |
| restoreStart | runtimeVersion이 설정됨 | INFO |
| restoreStart | runtimeVersion이 설정되지 않음 | DEBUG |
| restoreRuntimeDone | status=success | DEBUG |
| restoreRuntimeDone | status!=success | WARN |
| restoreReport | status=success | INFO |
| restoreReport | status!=success | WARN |
| start | - | INFO |
| runtimeDone | status=success | DEBUG |
| runtimeDone | status!=success | WARN |
| report | status=success | INFO |
| report | status!=success | WARN |
| extension | state=success | INFO |
| extension | state!=success | WARN |
| logSubscription | - | INFO |
| telemetrySubscription | - | INFO |
| logsDropped | - | WARN |
참고
Telemetry API를 통한 확장 기능용 실시간 원격 측정 데이터 액세스는 항상 전체 플랫폼 이벤트 세트를 내보냅니다. Lambda가 CloudWatch로 보내는 시스템 로그의 수준을 구성해도 Lambda Telemetry API 동작에는 영향을 주지 않습니다.
사용자 지정 런타임을 사용한 애플리케이션 로그 수준 필터링
함수에 대해 애플리케이션 로그 수준 필터링을 구성하면 백그라운드에서 Lambda는 AWS_LAMBDA_LOG_LEVEL 환경 변수로 런타임에 애플리케이션 로그 수준을 설정합니다. Lambda는 또한 AWS_LAMBDA_LOG_FORMAT 환경 변수로 함수의 로그 형식을 설정합니다. 이러한 변수를 사용해 Lambda 고급 로깅 제어를 사용자 지정 런타임에 통합할 수 있습니다.
Lambda 콘솔, AWS CLI, Lambda API로 사용자 지정 런타임을 사용하는 함수의 로깅 설정을 구성하려면 사용자 지정 런타임이 이 환경 변수의 값을 확인하도록 구성하세요. 그런 다음 선택한 로그 형식과 로그 수준에 따라 런타임의 로거를 구성할 수 있습니다.
더 알아보기 (Learn more)
- Lambda 고급 로깅 제어
- Lambda 함수의 로그 형식 설정
- Lambda Telemetry API