Node.js Lambda 함수 로그 및 모니터링

Node.js Lambda 함수 로그 및 모니터링 (Log and monitor Node.js Lambda functions)

AWS Lambda는 사용자를 대신해 Lambda 함수를 자동으로 모니터링하고 로그를 Amazon CloudWatch로 보냅니다. Lambda 함수에는 함수의 각 인스턴스에 대한 CloudWatch Logs 로그 그룹과 로그 스트림이 있습니다. Lambda 런타임 환경은 각 호출에 대한 세부 정보를 로그 스트림으로 보내고 함수 코드의 로그와 기타 출력을 중계합니다. 자세한 내용은 Lambda 함수 로그를 CloudWatch Logs로 보내기를 참조하세요.

이 페이지는 Lambda 함수 코드에서 로그 출력을 생성하고 AWS Command Line Interface, Lambda 콘솔 또는 CloudWatch 콘솔을 사용해 로그에 액세스하는 방법을 설명합니다.

출처: AWS Lambda 개발자 안내서

본문

로그를 반환하는 함수 만들기

함수 코드에서 로그를 출력하려면 console 객체의 메서드 또는 stdout이나 stderr에 쓰는 로깅 라이브러리를 사용할 수 있습니다. 다음 예제는 환경 변수와 이벤트 객체의 값을 기록합니다.

참고

입력을 기록할 때는 입력 검증과 출력 인코딩 같은 기법을 사용할 것을 권장합니다. 입력 데이터를 직접 기록하면 공격자가 코드를 사용해 변조를 감지하기 어렵게 만들거나, 로그 항목을 위조하거나, 로그 모니터를 우회할 수 있습니다. 자세한 내용은 Common Weakness Enumeration의 로그에 대한 부적절한 출력 중화를 참조하세요.

예시 index.js 파일 – 로깅:

exports.handler = async function(event, context) {
  console.log("ENVIRONMENT VARIABLES\n" + JSON.stringify(process.env, null, 2))
  console.info("EVENT\n" + JSON.stringify(event, null, 2))
  console.warn("Event not processed.")
  return context.logStreamName
}

로그 형식 예시:

START RequestId: c793869b-ee49-115b-a5b6-4fd21e8dedac Version: $LATEST
2019-06-07T19:11:20.562Z	c793869b-ee49-115b-a5b6-4fd21e8dedac	INFO	ENVIRONMENT VARIABLES
{
  "AWS_LAMBDA_FUNCTION_VERSION": "$LATEST",
  "AWS_LAMBDA_LOG_GROUP_NAME": "/aws/lambda/my-function",
  "AWS_LAMBDA_LOG_STREAM_NAME": "2019/06/07/[$LATEST]e6f4a0c4241adcd70c262d34c0bbc85c",
  "AWS_EXECUTION_ENV": "AWS_Lambda_nodejs12.x",
  "AWS_LAMBDA_FUNCTION_NAME": "my-function",
  "PATH": "/var/lang/bin:/usr/local/bin:/usr/bin/:/bin:/opt/bin",
  "NODE_PATH": "/opt/nodejs/node10/node_modules:/opt/nodejs/node_modules:/var/runtime/node_modules",
  ...
}
2019-06-07T19:11:20.563Z	c793869b-ee49-115b-a5b6-4fd21e8dedac	INFO	EVENT
{
  "key": "value"
}
2019-06-07T19:11:20.564Z	c793869b-ee49-115b-a5b6-4fd21e8dedac	WARN	Event not processed.
END RequestId: c793869b-ee49-115b-a5b6-4fd21e8dedac
REPORT RequestId: c793869b-ee49-115b-a5b6-4fd21e8dedac	Duration: 128.83 ms	Billed Duration: 296 ms	Memory Size: 128 MB	Max Memory Used: 74 MB	Init Duration: 166.62 ms	XRAY TraceId: 1-5d9d007f-0a8c7fd02xmpl480aed55ef0	SegmentId: 3d752xmpl1bbe37e	Sampled: true

Node.js 런타임은 각 호출에 대해 START, END, REPORT 줄을 기록합니다. 함수가 기록하는 각 항목에 타임스탬프, 요청 ID, 로그 수준을 추가합니다. REPORT 줄은 다음 세부 정보를 제공합니다.

REPORT 줄 데이터 필드:

• RequestId — 호출의 고유 요청 ID입니다.
• Duration — 함수의 핸들러 메서드가 이벤트를 처리하는 데 보낸 시간입니다.
• Billed Duration — 호출에 청구된 시간입니다.
• Memory Size — 함수에 할당된 메모리 양입니다.
• Max Memory Used — 함수가 사용한 메모리 양입니다. 호출이 실행 환경을 공유하면 Lambda는 모든 호출에서 사용된 최대 메모리를 보고합니다. 이 동작으로 인해 보고된 값이 예상보다 높을 수 있습니다.
• Init Duration — 제공된 첫 번째 요청에 대해 런타임이 함수를 로드하고 핸들러 메서드 밖의 코드를 실행하는 데 걸린 시간입니다.
• XRAY TraceId — 추적된 요청의 AWS X-Ray 추적 ID입니다.
• SegmentId — 추적된 요청의 X-Ray 세그먼트 ID입니다.
• Sampled — 추적된 요청의 샘플링 결과입니다.

Lambda 콘솔, CloudWatch Logs 콘솔 또는 명령줄에서 로그를 볼 수 있습니다.

Node.js에서 Lambda 고급 로깅 제어 사용

함수 로그가 캡처, 처리, 소비되는 방식을 더 잘 제어하기 위해 지원되는 Node.js 런타임에 대해 다음 로깅 옵션을 구성할 수 있습니다:

• 로그 형식 — 함수 로그에 대해 일반 텍스트와 구조화된 JSON 형식 중에서 선택합니다.
• 로그 수준 — JSON 형식 로그의 경우 Lambda가 Amazon CloudWatch로 보내는 로그의 상세 수준(예: ERROR, DEBUG, INFO)을 선택합니다.
• 로그 그룹 — 함수가 로그를 보낼 CloudWatch 로그 그룹을 선택합니다.

이러한 로깅 옵션과 함수에서 사용하도록 구성하는 방법에 대한 자세한 내용은 Lambda 함수에 대한 고급 로깅 제어 구성을 참조하세요.

로그 형식과 로그 수준 옵션을 Node.js Lambda 함수에서 사용하려면 다음 섹션의 지침을 참조하세요.

Node.js에서 구조화된 JSON 로그 사용

함수의 로그 형식으로 JSON을 선택하면 Lambda는 console.trace, console.debug, console.log, console.info, console.error, console.warn의 console 메서드를 사용해 출력된 로그를 구조화된 JSON으로 CloudWatch에 보냅니다. 각 JSON 로그 객체에는 다음 키가 있는 최소 4개의 키-값 쌍이 포함됩니다:

• "timestamp" — 로그 메시지가 생성된 시간
• "level" — 메시지에 할당된 로그 수준
• "message" — 로그 메시지 내용
• "requestId" — 함수 호출의 고유 요청 ID

함수가 사용하는 로깅 메서드에 따라 이 JSON 객체는 추가 키 쌍을 포함할 수도 있습니다. 예를 들어 함수가 여러 인수로 오류 객체를 기록하는 console 메서드를 사용하면 JSON 객체는 errorMessage, errorType, stackTrace 키를 가진 추가 키-값 쌍을 포함합니다.

코드가 이미 Powertools for AWS Lambda 같은 다른 로깅 라이브러리를 사용해 JSON 구조화 로그를 생성한다면 아무것도 변경할 필요가 없습니다. Lambda는 이미 JSON 인코딩된 로그를 이중 인코딩하지 않으므로 함수의 애플리케이션 로그는 계속 이전처럼 캡처됩니다.

Node.js 런타임에서 JSON 구조화 로그를 만들기 위해 Powertools for AWS Lambda 로깅 패키지를 사용하는 방법에 대한 자세한 내용은 TypeScript Lambda 함수 로그 및 모니터링을 참조하세요.

JSON 형식 로그 출력 예시

다음 예제는 함수의 로그 형식을 JSON으로 설정할 때 단일 및 다중 인수를 가진 console 메서드로 생성된 다양한 로그 출력이 CloudWatch Logs에서 어떻게 캡처되는지 보여줍니다.

첫 번째 예제는 console.error 메서드를 사용해 간단한 문자열을 출력합니다.

Node.js 로깅 코드 예시:

export const handler = async (event) => {
  console.error("This is a warning message");
  ...
}

JSON 로그 레코드 예시:

{
    "timestamp":"2025-11-01T00:21:51.358Z",
    "level":"ERROR",
    "message":"This is a warning message",
    "requestId":"93f25699-2cbf-4976-8f94-336a0aa98c6f"
}

console 메서드로 단일 또는 다중 인수를 사용해 더 복잡한 구조화된 로그 메시지도 출력할 수 있습니다. 다음 예제에서 console.log를 사용해 단일 인수로 두 개의 키-값 쌍을 출력합니다. Lambda가 CloudWatch Logs로 보내는 JSON 객체의 "message" 필드는 문자열화되지 않습니다.

Node.js 로깅 코드 예시:

export const handler = async (event) => {
  console.log({data: 12.3, flag: false});
  ...
}

JSON 로그 레코드 예시:

{
    "timestamp": "2025-12-08T23:21:04.664Z",
    "level": "INFO",
    "requestId": "405a4537-9226-4216-ac59-64381ec8654a",
    "message": {
        "data": 12.3,
        "flag": false
    }
}

다음 예제에서도 console.log 메서드를 사용해 로그 출력을 만듭니다. 이번에는 메서드가 두 개의 인수, 즉 두 개의 키-값 쌍을 포함하는 맵과 식별 문자열을 받습니다. 이 경우 두 인수를 제공했으므로 Lambda는 "message" 필드를 문자열화합니다.

Node.js 로깅 코드 예시:

export const handler = async (event) => {
  console.log('Some object - ', {data: 12.3, flag: false});
  ...
}

JSON 로그 레코드 예시:

{
    "timestamp": "2025-12-08T23:21:04.664Z",
    "level": "INFO",
    "requestId": "405a4537-9226-4216-ac59-64381ec8654a",
    "message": "Some object -  { data: 12.3, flag: false }"
}

Lambda는 console.log로 생성된 출력에 INFO 로그 수준을 할당합니다.

마지막 예제는 console 메서드를 사용해 오류 객체가 CloudWatch Logs로 출력되는 방법을 보여줍니다. 여러 인수로 오류 객체를 기록하면 Lambda는 로그 출력에 errorMessage, errorType, stackTrace 필드를 추가합니다.

Node.js 로깅 코드 예시:

export const handler = async (event) => {
  let e1 = new ReferenceError("some reference error");
  let e2 = new SyntaxError("some syntax error");
  console.log(e1);
  console.log("errors logged - ", e1, e2);
};

JSON 로그 레코드 예시:

{
    "timestamp": "2025-12-08T23:21:04.632Z",
    "level": "INFO",
    "requestId": "405a4537-9226-4216-ac59-64381ec8654a",
    "message": {
        "errorType": "ReferenceError",
        "errorMessage": "some reference error",
        "stackTrace": [
            "ReferenceError: some reference error",
            "    at Runtime.handler (file:///var/task/index.mjs:3:12)",
            "    at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1173:29)"
        ]
    }
}

{
    "timestamp": "2025-12-08T23:21:04.646Z",
    "level": "INFO",
    "requestId": "405a4537-9226-4216-ac59-64381ec8654a",
    "message": "errors logged -  ReferenceError: some reference error\n    at Runtime.handler (file:///var/task/index.mjs:3:12)\n    at Runtime.handleOnceNonStreaming
    (file:///var/runtime/index.mjs:1173:29) SyntaxError: some syntax error\n    at Runtime.handler (file:///var/task/index.mjs:4:12)\n    at Runtime.handleOnceNonStreaming
    (file:///var/runtime/index.mjs:1173:29)",
    "errorType": "ReferenceError",
    "errorMessage": "some reference error",
    "stackTrace": [
        "ReferenceError: some reference error",
        "    at Runtime.handler (file:///var/task/index.mjs:3:12)",
        "    at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1173:29)"
    ]
}

여러 오류 유형을 기록할 때 추가 필드 errorMessage, errorType, stackTrace는 console 메서드에 제공된 첫 번째 오류 유형에서 추출됩니다.

구조화된 JSON 로그와 함께 임베디드 메트릭 형식(EMF) 클라이언트 라이브러리 사용

AWS는 임베디드 메트릭 형식(EMF) 로그를 만드는 데 사용할 수 있는 Node.js용 오픈 소스 클라이언트 라이브러리를 제공합니다. 이러한 라이브러리를 사용하는 기존 함수가 있고 함수의 로그 형식을 JSON으로 변경하면 CloudWatch가 더 이상 코드가 내보내는 메트릭을 인식하지 못할 수 있습니다.

코드가 console.log를 직접 사용하거나 Powertools for AWS Lambda (TypeScript)를 사용해 현재 EMF 로그를 내보낸다면 함수의 로그 형식을 JSON으로 변경했을 때 CloudWatch도 이를 구문 분석할 수 없습니다.

중요

함수의 EMF 로그가 CloudWatch에 계속 올바르게 구문 분석되도록 EMF 및 Powertools for AWS Lambda 라이브러리를 최신 버전으로 업데이트하세요. JSON 로그 형식으로 전환하는 경우 함수의 임베디드 메트릭과의 호환성을 보장하기 위해 테스트를 수행할 것도 권장합니다. 코드가 console.log로 EMF 로그를 직접 내보낸다면 다음 코드 예제와 같이 해당 메트릭을 stdout으로 직접 출력하도록 코드를 변경하세요.

임베디드 메트릭을 stdout으로 내보내는 코드 예시:

process.stdout.write(JSON.stringify(
    {
        "_aws": {
            "Timestamp": Date.now(),
            "CloudWatchMetrics": [{
                "Namespace": "lambda-function-metrics",
                "Dimensions": [["functionVersion"]],
                "Metrics": [{
                    "Name": "time",
                    "Unit": "Milliseconds",
                    "StorageResolution": 60
                }]
            }]
        },
        "functionVersion": "$LATEST",
        "time": 100,
        "requestId": context.awsRequestId
    }
) + "\n")

Node.js에서 로그 수준 필터링 사용

AWS Lambda가 애플리케이션 로그를 로그 수준에 따라 필터링하게 하려면 함수가 JSON 형식 로그를 사용해야 합니다. 두 가지 방법으로 이것을 달성할 수 있습니다:

• 표준 console 메서드로 로그 출력을 만들고 함수를 JSON 로그 형식을 사용하도록 구성합니다. 그러면 AWS Lambda는 Node.js에서 구조화된 JSON 로그 사용에 설명된 JSON 객체의 "level" 키-값 쌍으로 로그 출력을 필터링합니다. 함수의 로그 형식 구성 방법을 알아보려면 Lambda 함수에 대한 고급 로깅 제어 구성을 참조하세요.
• 다른 로깅 라이브러리나 방법을 사용해 로그 출력의 수준을 정의하는 "level" 키-값 쌍이 포함된 JSON 구조화 로그를 코드에서 만듭니다. 예를 들어 Powertools for AWS Lambda를 사용해 코드에서 JSON 구조화 로그 출력을 생성할 수 있습니다. Node.js 런타임에서 Powertools 사용에 대해 더 알아보려면 TypeScript Lambda 함수 로그 및 모니터링을 참조하세요.

Lambda가 함수의 로그를 필터링하려면 JSON 로그 출력에 "timestamp" 키-값 쌍도 포함해야 합니다. 시간은 유효한 RFC 3339 타임스탬프 형식으로 지정해야 합니다. 유효한 타임스탬프를 제공하지 않으면 Lambda는 로그에 INFO 수준을 할당하고 타임스탬프를 추가합니다.

함수를 로그 수준 필터링을 사용하도록 구성할 때 AWS Lambda가 CloudWatch Logs로 보내려는 로그 수준을 다음 옵션 중에서 선택합니다:

로그 수준	표준 용도
TRACE (가장 상세)	코드 실행 경로를 추적하는 데 사용되는 가장 세분화된 정보
DEBUG	시스템 디버깅을 위한 상세 정보
INFO	함수의 정상 작동을 기록하는 메시지
WARN	해결하지 않으면 예기치 않은 동작으로 이어질 수 있는 잠재적 오류에 대한 메시지
ERROR	코드가 예상대로 수행되지 못하게 하는 문제에 대한 메시지
FATAL (가장 덜 상세)	애플리케이션이 작동을 멈추게 하는 심각한 오류에 대한 메시지

Lambda는 선택한 수준 이하의 로그를 CloudWatch로 보냅니다. 예를 들어 로그 수준을 WARN으로 구성하면 Lambda는 WARN, ERROR, FATAL 수준에 해당하는 로그를 보냅니다.

Lambda 콘솔에서 로그 보기

Lambda 함수를 호출한 후 Lambda 콘솔을 사용해 로그 출력을 볼 수 있습니다.

내장 Code 편집기에서 코드를 테스트할 수 있다면 실행 결과에서 로그를 찾습니다. 콘솔 테스트 기능으로 함수를 호출하면 Details(세부 정보) 섹션에서 Log output(로그 출력) 을 찾습니다.

CloudWatch 콘솔에서 로그 보기

Amazon CloudWatch 콘솔을 사용해 모든 Lambda 함수 호출의 로그를 볼 수 있습니다.

CloudWatch 콘솔에서 로그를 보려면:

1. CloudWatch 콘솔에서 Log groups(로그 그룹) 페이지를 엽니다.
2. 함수의 로그 그룹(/aws/lambda/your-function-name)을 선택합니다.
3. 로그 스트림을 선택합니다.

각 로그 스트림은 함수의 인스턴스에 해당합니다. Lambda 함수를 업데이트할 때와 동시 호출을 처리하기 위해 추가 인스턴스가 생성될 때 로그 스트림이 나타납니다. 특정 호출의 로그를 찾으려면 AWS X-Ray로 함수를 계측할 것을 권장합니다. X-Ray는 추적에서 요청과 로그 스트림에 대한 세부 정보를 기록합니다.

AWS CLI로 로그 보기

AWS CLI는 명령줄 셸에서 명령을 사용해 AWS 서비스를 상호작용할 수 있는 오픈 소스 도구입니다. 이 섹션의 단계를 완료하려면 AWS CLI 버전 2가 있어야 합니다.

AWS CLI를 사용해 --log-type 명령 옵션으로 호출에 대한 로그를 검색할 수 있습니다. 응답에는 호출에서 최대 4KB의 base64 인코딩 로그가 포함된 LogResult 필드가 있습니다.

로그 ID 검색 예시:

다음 예제는 my-function이라는 함수의 LogResult 필드에서 로그 ID를 검색하는 방법을 보여줍니다.

aws lambda invoke --function-name my-function out --log-type Tail

다음과 같은 출력이 표시되어야 합니다:

{
    "StatusCode": 200,
    "LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
    "ExecutedVersion": "$LATEST"
}

로그 디코딩 예시:

같은 명령 프롬프트에서 base64 유틸리티를 사용해 로그를 디코딩합니다. 다음 예제는 my-function의 base64 인코딩 로그를 검색하는 방법을 보여줍니다.

aws lambda invoke --function-name my-function out --log-type Tail \
--query 'LogResult' --output text --cli-binary-format raw-in-base64-out | base64 --decode

AWS CLI 버전 2를 사용하는 경우 cli-binary-format 옵션이 필요합니다. 기본 설정으로 만들려면 aws configure set cli-binary-format raw-in-base64-out을 실행하세요. 자세한 내용은 AWS Command Line Interface User Guide for Version 2의 AWS CLI 지원 글로벌 명령줄 옵션을 참조하세요.

다음과 같은 출력이 표시되어야 합니다:

START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST
"AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib",
END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8
REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8  Duration: 79.67 ms      Billed Duration: 80 ms         Memory Size: 128 MB     Max Memory Used: 73 MB

base64 유틸리티는 Linux, macOS, Windows의 Ubuntu에서 사용할 수 있습니다. macOS 사용자는 base64 -D를 사용해야 할 수 있습니다.

get-logs.sh 스크립트 예시:

같은 명령 프롬프트에서 다음 스크립트를 사용해 마지막 5개 로그 이벤트를 다운로드합니다. 스크립트는 sed를 사용해 출력 파일에서 따옴표를 제거하고, 로그를 사용할 수 있게 될 시간을 주기 위해 15초간 대기합니다. 출력에는 Lambda의 응답과 get-log-events 명령의 출력이 포함됩니다.

다음 코드 샘플 내용을 복사해 Lambda 프로젝트 디렉터리에 get-logs.sh로 저장합니다.

AWS CLI 버전 2를 사용하는 경우 cli-binary-format 옵션이 필요합니다. 기본 설정으로 만들려면 aws configure set cli-binary-format raw-in-base64-out을 실행하세요. 자세한 내용은 AWS Command Line Interface User Guide for Version 2의 AWS CLI 지원 글로벌 명령줄 옵션을 참조하세요.

#!/bin/bash
aws lambda invoke --function-name my-function --cli-binary-format raw-in-base64-out --payload '{"key": "value"}' out
sed -i'' -e 's/"//g' out
sleep 15
aws logs get-log-events --log-group-name /aws/lambda/my-function --log-stream-name stream1 --limit 5

macOS 및 Linux (전용):

같은 명령 프롬프트에서 macOS와 Linux 사용자는 스크립트가 실행 가능한지 확인하기 위해 다음 명령을 실행해야 할 수 있습니다.

chmod -R 755 get-logs.sh

마지막 5개 로그 이벤트 검색 예시:

같은 명령 프롬프트에서 다음 스크립트를 실행해 마지막 5개 로그 이벤트를 가져옵니다.

./get-logs.sh

다음과 같은 출력이 표시되어야 합니다:

{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}
{
    "events": [
        {
            "timestamp": 1559763003171,
            "message": "START RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf Version: $LATEST\n",
            "ingestionTime": 1559763003309
        },
        {
            "timestamp": 1559763003173,
            "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tENVIRONMENT VARIABLES\r{\r  \"AWS_LAMBDA_FUNCTION_VERSION\": \"$LATEST\",\r ...",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003173,
            "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tEVENT\r{\r  \"key\": \"value\"\r}\n",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003218,
            "message": "END RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\n",
            "ingestionTime": 1559763018353
        },
        {
            "timestamp": 1559763003218,
            "message": "REPORT RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\tDuration: 26.73 ms\tBilled Duration: 27 ms \tMemory Size: 128 MB\tMax Memory Used: 75 MB\t\n",
            "ingestionTime": 1559763018353
        }
    ],
    "nextForwardToken": "f/34783877304859518393868359594929986069206639495374241795",
    "nextBackwardToken": "b/34783877303811383369537420289090800615709599058929582080"
}

로그 삭제

함수를 삭제해도 로그 그룹은 자동으로 삭제되지 않습니다. 로그를 무기한 저장하지 않으려면 로그 그룹을 삭제하거나 로그가 자동으로 삭제되는 보존 기간을 구성하세요.

더 알아보기 (Learn more)

• Lambda 고급 로깅 제어
• Node.js Lambda 함수
• CloudWatch Logs 모니터링