Ruby Lambda 함수 로그 및 모니터링

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

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

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

출처: AWS Lambda 개발자 안내서

본문

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

함수 코드에서 로그를 출력하려면 puts 문 또는 stdout이나 stderr에 쓰는 로깅 라이브러리를 사용할 수 있습니다. 다음 예제는 환경 변수와 이벤트 객체의 값을 기록합니다. 핸들러에서 사용할 수 있는 컨텍스트 객체에 대한 정보는 Lambda 컨텍스트 객체를 사용해 Ruby 함수 정보 검색을 참조하세요.

예시 lambda_function.rb:

# lambda_function.rb

def handler(event:, context:)
    puts "## ENVIRONMENT VARIABLES"
    puts ENV.to_a
    puts "## EVENT"
    puts event.to_a
end

로그 형식 예시:

START RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95 Version: $LATEST
## ENVIRONMENT VARIABLES
environ({'AWS_LAMBDA_LOG_GROUP_NAME': '/aws/lambda/my-function', 'AWS_LAMBDA_LOG_STREAM_NAME': '2020/01/31/[$LATEST]3893xmpl7fac4485b47bb75b671a283c', 'AWS_LAMBDA_FUNCTION_NAME': 'my-function', ...})
## EVENT
{'key': 'value'}
END RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95
REPORT RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95  Duration: 15.74 ms  Billed Duration: 147 ms Memory Size: 128 MB Max Memory Used: 56 MB  Init Duration: 130.49 ms
XRAY TraceId: 1-5e34a614-10bdxmplf1fb44f07bc535a1   SegmentId: 07f5xmpl2d1f6f85 Sampled: true

Ruby 런타임은 각 호출에 대해 START, END, REPORT 줄을 기록합니다. 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 — 추적된 요청의 샘플링 결과입니다.

더 상세한 로그는 Ruby logger 라이브러리 작업을 참조하세요.

Ruby에서 Lambda 고급 로깅 제어 사용

함수 로그가 캡처, 처리, 소비되는 방식을 더 잘 제어하기 위해 Lambda는 Ruby에서 고급 로깅 제어를 제공합니다. Ruby 4.0 이상 런타임에서 다음 로깅 옵션을 구성할 수 있습니다:

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

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

로그 형식과 로그 수준 옵션을 Ruby Lambda 함수에서 사용하는 방법에 대해 자세히 알아보려면 다음 섹션의 지침을 참조하세요.

Ruby에서 구조화된 JSON 로그 사용

함수의 로그 형식으로 JSON을 선택하면 Lambda는 Ruby 표준 Logger 라이브러리가 출력하는 로그를 구조화된 JSON으로 CloudWatch에 보냅니다. 각 JSON 로그 객체에는 다음 키가 있는 최소 4개의 키-값 쌍이 포함됩니다:

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

Ruby Logger 라이브러리는 이 JSON 객체에 "logger" 같은 추가 키-값 쌍도 추가할 수 있습니다.

다음 섹션의 예제는 함수의 로그 형식을 JSON으로 구성할 때 Ruby Logger 라이브러리를 사용해 생성된 로그 출력이 CloudWatch Logs에서 어떻게 캡처되는지 보여줍니다.

로그를 반환하는 함수 만들기에 설명된 대로 puts 메서드로 기본 로그 출력을 생성하면 함수의 로깅 형식을 JSON으로 구성해도 Lambda는 이 출력을 일반 텍스트로 캡처합니다.

Ruby Logger 라이브러리를 사용한 표준 JSON 로그 출력

다음 예제 코드 조각과 로그 출력은 함수의 로그 형식이 JSON으로 설정될 때 Ruby Logger 라이브러리를 사용해 생성된 표준 로그 출력이 CloudWatch Logs에서 어떻게 캡처되는지 보여줍니다.

Ruby 로깅 코드 예시:

require 'logger'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  logger.info("Inside the handler function")
end

JSON 로그 레코드 예시:

{
    "timestamp": "2025-10-27T19:17:45.586Z",
    "level": "INFO",
    "message": "Inside the handler function",
    "requestId": "79b4f56e-95b1-4643-9700-2807f4e68189"
}

JSON에서 추가 파라미터 로깅

함수의 로그 형식이 JSON으로 설정되면 추가 키-값 쌍의 해시를 로그 출력에 전달해 Ruby Logger 라이브러리로 추가 파라미터를 기록할 수도 있습니다.

Ruby 로깅 코드 예시:

require 'logger'
require 'json'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  extra_params = { "a" => "b", "b" => [3] }
  logger.info({ message: "extra parameters example" }.merge(extra_params).to_json)
end

JSON 로그 레코드 예시:

{
    "timestamp": "2025-11-02T15:26:28Z",
    "level": "INFO",
    "message": "extra parameters example",
    "requestId": "3dbd5759-65f6-45f8-8d7d-5bdc79a3bd01",
    "a": "b",
    "b": [
        3
    ]
}

JSON에서 예외 로깅

다음 코드 조각은 로그 형식을 JSON으로 구성했을 때 Ruby 예외가 함수의 로그 출력에서 어떻게 캡처되는지 보여줍니다. 예외와 함께 logger.error를 사용해 생성된 로그 출력에는 ERROR 로그 수준이 할당됩니다.

Ruby 로깅 코드 예시:

require 'logger'

def lambda_handler(event:, context:)
  logger = Logger.new($stdout)
  begin
    raise "exception"
  rescue => e
    logger.error(e)
  end
end

JSON 로그 레코드 예시:

{
    "timestamp": "2025-11-02T16:18:57Z",
    "level": "ERROR",
    "message": "exception",
    "stackTrace": [
        "  /var/task/lambda_function.rb:4:in `lambda_handler'"
    ],
    "errorType": "RuntimeError",
    "errorMessage": "exception",
    "requestId": "3f9d155c-0f09-46b7-bdf1-e91dab220855",
    "location": "/var/task/lambda_function.rb:lambda_handler:6"
}

Ruby에서 로그 수준 필터링 사용

로그 수준 필터링을 구성하면 일정 로깅 수준 이하의 로그만 CloudWatch Logs로 보내도록 선택할 수 있습니다. 함수에 대한 로그 수준 필터링 구성 방법을 알아보려면 로그 수준 필터링을 참조하세요.

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

표준 Ruby Logger 라이브러리로 로그 출력을 만들고 함수를 JSON 로그 형식을 사용하도록 구성합니다. 그러면 AWS Lambda는 Ruby에서 구조화된 JSON 로그 사용에 설명된 JSON 객체의 "level" 키-값 쌍으로 로그 출력을 필터링합니다. 함수의 로그 형식 구성 방법을 알아보려면 Lambda 함수에 대한 고급 로깅 제어 구성을 참조하세요.
다른 로깅 라이브러리나 방법을 사용해 로그 출력의 수준을 정의하는 "level" 키-값 쌍이 포함된 JSON 구조화 로그를 코드에서 만듭니다.

또한 puts 문을 사용해 로그 수준 식별자를 포함하는 JSON 객체를 출력할 수 있습니다. 다음 puts 문은 로그 수준이 INFO로 설정된 JSON 형식 출력을 생성합니다. 함수의 로깅 수준이 INFO, DEBUG 또는 TRACE로 설정되어 있으면 AWS Lambda는 JSON 객체를 CloudWatch Logs로 보냅니다.

puts '{"msg":"My log message", "level":"info"}'

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

대체 로깅 라이브러리 사용

logger 라이브러리의 사용자 지정 버전을 사용해야 한다면 배포 패키지나 Lambda 레이어에 포함하고 RUBYLIB 환경 변수를 라이브러리의 lib 디렉터리로 설정할 수 있습니다. Lambda 런타임은 번들된 버전 대신 사용자의 버전을 로드합니다.

코드가 이미 다른 로깅 라이브러리를 사용해 JSON 구조화 로그를 생성한다면 아무것도 변경할 필요가 없습니다. AWS Lambda는 이미 JSON 인코딩된 로그를 이중 인코딩하지 않습니다. 함수를 JSON 로그 형식을 사용하도록 구성해도 로깅 출력은 정의한 JSON 구조로 CloudWatch에 나타납니다.

Lambda 콘솔에서 로그 보기

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

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

CloudWatch 콘솔에서 로그 보기

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

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

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

각 로그 스트림은 함수의 인스턴스에 해당합니다. 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로 저장합니다.

#!/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"
}

로그 삭제

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

Ruby logger 라이브러리 작업

Ruby logger 라이브러리는 쉽게 읽을 수 있는 간결한 로그를 반환합니다. logger 유틸리티를 사용해 함수와 관련된 상세 정보, 메시지, 오류 코드를 출력하세요.

# lambda_function.rb

require 'logger'

def handler(event:, context:)
  logger = Logger.new($stdout)
  logger.info('## ENVIRONMENT VARIABLES')
  logger.info(ENV.to_a)
  logger.info('## EVENT')
  logger.info(event)
  event.to_a
end

logger의 출력에는 로그 수준, 타임스탬프, 요청 ID가 포함됩니다.

START RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125 Version: $LATEST
[INFO]  2020-01-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## ENVIRONMENT VARIABLES

[INFO]  2020-01-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    environ({'AWS_LAMBDA_LOG_GROUP_NAME': '/aws/lambda/my-function', 'AWS_LAMBDA_LOG_STREAM_NAME': '2020/01/31/[$LATEST]1bbe51xmplb34a2788dbaa7433b0aa4d', 'AWS_LAMBDA_FUNCTION_NAME': 'my-function', ...})

[INFO]  2020-01-31T22:12:58.535Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## EVENT

[INFO]  2020-01-31T22:12:58.535Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    {'key': 'value'}

END RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125
REPORT RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125  Duration: 2.75 ms   Billed Duration: 117 ms Memory Size: 128 MB Max Memory Used: 56 MB  Init Duration: 113.51 ms
XRAY TraceId: 1-5e34a66a-474xmpl7c2534a87870b4370   SegmentId: 073cxmpl3e442861 Sampled: true

더 알아보기 (Learn more)

Lambda 고급 로깅 제어
Ruby Lambda 함수
CloudWatch Logs 모니터링