# Ruby Lambda 함수 로깅 및 모니터링
AWS Lambda는 자동으로 Lambda 함수를 모니터링하고 로그를 Amazon CloudWatch로 보냅니다. Lambda 함수는 함수의 각 인스턴스에 대한 CloudWatch Logs 로그 그룹 및 로그 스트림과 함께 제공됩니다. Lambda 런타임 환경은 각 호출에 관한 세부 정보를 로그 스트림에 전송하며, 함수 코드에서 로그 및 그 외 출력을 중계합니다. 자세한 내용은 [CloudWatch Logs로 Lambda 함수 로그 전송](monitoring-cloudwatchlogs.md) 섹션을 참조하세요.
이 페이지에서는 AWS Command Line Interface, Lambda 콘솔 또는 CloudWatch 콘솔을 사용하여 Lambda 함수 코드의 로그 출력하고 액세스 로그를 생성하는 방법에 대해 설명합니다.
**Topics**
+ [로그를 반환하는 함수 생성](#ruby-logging-output)
+ [Ruby에서 Lambda 고급 로깅 제어 사용](#ruby-logging-advanced)
+ [Lambda 콘솔에서 로그 보기](#ruby-logging-console)
+ [CloudWatch 콘솔에서 로그 보기](#ruby-logging-cwconsole)
+ [AWS Command Line Interface(AWS CLI)(을)를 사용하여 로그 보기](#ruby-logging-cli)
+ [로그 삭제](#ruby-logging-delete)
+ [Ruby 로거 라이브러리 작업](#ruby-logging-lib)
## 로그를 반환하는 함수 생성
함수 코드에서 로그를 출력하려는 경우, `puts` 명령문을 사용하거나 `stdout` 또는 `stderr`에 쓰는 로깅 라이브러리를 사용할 수 있습니다. 다음 예제는 환경 변수의 값과 이벤트 객체를 로깅합니다.
**Example lambda\_function.rb**
```
# lambda_function.rb
def handler(event:, context:)
puts "## ENVIRONMENT VARIABLES"
puts ENV.to_a
puts "## EVENT"
puts event.to_a
end
```
**Example 로그 형식**
```
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 행 데이터 필드**
+ **RequestId** – 호출의 고유한 요청 ID입니다.
+ **지속시간** – 함수의 핸들러 메서드가 이벤트를 처리하는 데 걸린 시간입니다.
+ **청구 기간** – 호출에 대해 청구된 시간입니다.
+ **메모리 크기** - 함수에 할당된 메모리 양입니다.
+ **사용된 최대 메모리** – 함수에서 사용한 메모리 양입니다. 간접 호출이 실행 환경을 공유하는 경우 Lambda는 모든 간접 호출에서 사용된 최대 메모리를 보고합니다. 이 동작으로 인해 보고된 값이 예상보다 높을 수 있습니다.
+ **초기화 기간** – 제공된 첫 번째 요청의 경우 런타임이 핸들러 메서드 외부에서 함수를 로드하고 코드를 실행하는 데 걸린 시간입니다.
+ **XRAY TraceId** – 추적된 요청의 경우 [AWS X-Ray 추적 ID](services-xray.md)입니다.
+ **SegmentId** - 추적된 요청의 경우 X-Ray 세그먼트 ID입니다.
+ **샘플링 완료(Sampled)** – 추적된 요청의 경우 샘플링 결과입니다.
자세한 로그를 보려면 [Ruby 로거 라이브러리 작업](#ruby-logging-lib)를 사용합니다.
## Ruby에서 Lambda 고급 로깅 제어 사용
함수의 로그를 캡처, 처리 및 사용하는 방법을 더 잘 제어할 수 있도록 Lambda는 Ruby용 고급 로깅 제어 기능을 제공합니다. Ruby 4.0 이상 런타임의 경우 다음과 같은 로깅 옵션을 구성할 수 있습니다.
+ **로그 형식** - 함수 로그에 대해 일반 텍스트와 구조화된 JSON 형식 중에서 선택
+ **로그 수준** - JSON 형식의 로그의 경우, Lambda가 Amazon CloudWatch로 전송하는 로그의 세부 수준(ERROR, DEBUG 또는 INFO 등)을 선택
+ **로그 그룹** - 함수가 로그를 보내는 CloudWatch 로그 그룹을 선택
이러한 로깅 옵션에 대한 자세한 내용과 이를 사용하도록 함수를 구성하는 방법에 대한 지침은 [Lambda 함수에 대한 고급 로깅 제어 구성](monitoring-logs.md#monitoring-cloudwatchlogs-advanced)을 참조하세요.
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` 메서드를 사용하여 [로그를 반환하는 함수 생성](#ruby-logging-output)에 설명된 대로 기본 로그 출력을 생성하는 경우 함수의 로깅 형식을 JSON으로 구성하더라도 Lambda는 이러한 출력을 일반 텍스트로 캡처합니다.
### Ruby Logger 라이브러리를 사용하는 표준 JSON 로그 출력
다음의 코드 조각 및 로그 출력 예는 함수의 로그 형식이 JSON으로 설정된 경우 Ruby `Logger` 라이브러리를 사용하여 생성된 표준 로그 출력이 CloudWatch Logs에 캡처되는 방법을 보여줍니다.
**Example Ruby 로깅 코드 예**
```
require 'logger'
def lambda_handler(event:, context:)
logger = Logger.new($stdout)
logger.info("Inside the handler function")
end
```
**Example 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` 라이브러리로 추가 파라미터를 로깅할 수도 있습니다.
**Example 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
```
**Example 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가 할당됩니다.
**Example Ruby 로깅 코드 예**
```
require 'logger'
def lambda_handler(event:, context:)
logger = Logger.new($stdout)
begin
raise "exception"
rescue => e
logger.error(e)
end
end
```
**Example 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로 전송하도록 선택할 수 있습니다. 함수의 로그 수준 필터링을 구성하는 방법을 알아보려면 [로그 수준 필터링](monitoring-cloudwatchlogs-log-level.md)을 참조하세요.
AWS Lambda에서 애플리케이션 로그를 로그 수준에 따라 필터링하려면 함수에서 JSON 형식의 로그를 사용해야 합니다. 다음 두 가지 방법으로 이 작업을 달성할 수 있습니다.
+ 표준 Ruby `Logger` 라이브러리를 사용하여 로그 출력을 생성하고 JSON 로그 형식을 사용하도록 함수를 구성합니다. AWS Lambda은 그런 다음 [Ruby에서 구조화된 JSON 로그 사용](#ruby-logging-json)에서 설명하는 JSON 객체의 `"level"` 키 값 쌍을 사용하여 로그 출력을 필터링합니다. 함수의 로그 형식을 구성하는 방법은 [Lambda 함수에 대한 고급 로깅 제어 구성](monitoring-logs.md#monitoring-cloudwatchlogs-advanced)를 참조하세요.
+ 다른 로깅 라이브러리 또는 메서드를 사용하여 로그 출력 수준을 정의하는 `"level"` 키 값 쌍이 포함된 JSON 구조화된 로그를 코드에 만들 수 있습니다.
또한 `puts` 문을 사용하여 로그 수준 식별자를 포함하는 JSON 객체를 출력할 수도 있습니다. 다음 `puts` 문은 로그 수준이 INFO로 설정된 JSON 형식의 출력을 생성합니다. AWS Lambda는 함수의 로깅 수준이 INFO, DEBUG, 또는 TRACE로 설정된 경우 JSON 객체를 CloudWatch Logs로 전송합니다.
```
puts '{"msg":"My log message", "level":"info"}'
```
Lambda가 함수 로그를 필터링하려면 JSON 로그 출력에 `"timestamp"` 키 값 쌍도 포함해야 합니다. 시간은 유효한 [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) 타임스탬프 형식으로 지정해야 합니다. 유효한 타임스탬프를 제공하지 않으면 Lambda는 로그에 레벨 INFO를 할당하고 타임스탬프를 추가합니다.
### 대체 로깅 라이브러리 사용
사용자 지정 버전의 `logger` 라이브러리를 사용해야 하는 경우, 배포 패키지 또는 Lambda 계층에 라이브러리를 포함하고 `RUBYLIB` 환경 변수를 라이브러리의 `lib` 디렉터리로 설정할 수 있습니다. Lambda 런타임은 번들링된 버전 대신 해당 버전을 로드합니다.
코드에서 이미 다른 로깅 라이브러리를 사용하여 JSON 구조화된 로그를 생성하는 경우에는 변경할 필요가 없습니다. AWS Lambda는 이미 JSON으로 인코딩된 로그를 이중 인코딩하지 않습니다. JSON 로그 형식을 사용하도록 함수를 구성하더라도 로깅 출력은 사용자가 정의한 JSON 구조로 CloudWatch에 표시됩니다.
## Lambda 콘솔에서 로그 보기
Lambda 함수를 간접 호출한 후 Lambda 콘솔을 사용하여 로그 출력을 볼 수 있습니다.
포함된 **코드** 편집기에서 코드를 테스트할 수 있는 경우 **실행 결과**에서 로그를 찾을 수 있습니다. 콘솔 테스트 기능을 사용하여 함수를 간접적으로 간접 호출하면 **세부 정보** 섹션에서 **로그 출력**을 찾을 수 있습니다.
## CloudWatch 콘솔에서 로그 보기
Amazon CloudWatch 콘솔을 사용하여 모든 Lambda 함수 호출에 대한 로그를 볼 수 있습니다.
**CloudWatch 콘솔에서 로그를 보려면**
1. CloudWatch 콘솔에서 [로그 그룹 페이지](https://console.aws.amazon.com/cloudwatch/home?#logs:)를 엽니다.
1. 함수(**/aws/lambda/{{your-function-name}}**)에 대한 로그 그룹을 선택합니다.
1. 로그 스트림을 선택합니다.
각 로그 스트림은 [함수의 인스턴스](lambda-runtime-environment.md)에 해당합니다. 로그 스트림은 Lambda 함수를 업데이트할 때, 그리고 동시 호출을 처리하기 위해 추가 인스턴스가 생성될 때 나타납니다. 특정 호출에 대한 로그를 찾으려면 AWS X-Ray로 함수를 계측하는 것이 좋습니다. X-Ray는 요청 및 로그 스트림에 대한 세부 정보를 기록합니다.
## AWS Command Line Interface(AWS CLI)(을)를 사용하여 로그 보기
AWS CLI은(는) 명령줄 셸의 명령을 사용하여 AWS 서비스와 상호 작용할 수 있는 오픈 소스 도구입니다. 이 섹션의 단계를 완료하려면 [AWS CLI 버전 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)가 필요합니다.
[AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)를 사용하면 `--log-type` 명령 옵션을 통해 호출에 대한 로그를 검색할 수 있습니다. 호출에서 base64로 인코딩된 로그를 최대 4KB까지 포함하는 `LogResult` 필드가 응답에 포함됩니다.
**Example 로그 ID 검색**
다음 예제에서는 `LogResult`이라는 함수의 `my-function` 필드에서 *로그 ID*를 검색하는 방법을 보여줍니다.
```
aws lambda invoke --function-name my-function out --log-type Tail
```
다음 결과가 표시됩니다:
```
{
"StatusCode": 200,
"LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
"ExecutedVersion": "$LATEST"
}
```
**Example decode the logs**
동일한 명령 프롬프트에서 `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
```
**cli-binary-format** 옵션은 AWS CLI 버전 2를 사용할 때 필요합니다. 이 설정을 기본 설정으로 지정하려면 `aws configure set cli-binary-format raw-in-base64-out`을(를) 실행하세요. 자세한 내용은 *AWS Command Line Interface 사용 설명서 버전 2*에서 [AWS CLI 지원 글로벌 명령줄 옵션](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list)을 참조하세요.
다음 결과가 표시됩니다.
```
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 및 [Ubuntu on Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10)에서 사용할 수 있습니다. macOS 사용자는 `base64 -D`를 사용해야 할 수도 있습니다.
**Example get-logs.sh 스크립트**
동일한 명령 프롬프트에서 다음 스크립트를 사용하여 마지막 5개 로그 이벤트를 다운로드합니다. 이 스크립트는 `sed`를 사용하여 출력 파일에서 따옴표를 제거하고, 로그를 사용할 수 있는 시간을 허용하기 위해 15초 동안 대기합니다. 출력에는 Lambda의 응답과 `get-log-events` 명령의 출력이 포함됩니다.
다음 코드 샘플의 내용을 복사하고 Lambda 프로젝트 디렉터리에 `get-logs.sh`로 저장합니다.
**cli-binary-format** 옵션은 AWS CLI 버전 2를 사용할 때 필요합니다. 이 설정을 기본 설정으로 지정하려면 `aws configure set cli-binary-format raw-in-base64-out`을(를) 실행하세요. 자세한 내용은 *AWS Command Line Interface 사용 설명서 버전 2*에서 [AWS CLI 지원 글로벌 명령줄 옵션](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list)을 참조하세요.
```
#!/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
```
**Example macOS 및 Linux(전용)**
동일한 명령 프롬프트에서 macOS 및 Linux 사용자는 스크립트가 실행 가능한지 확인하기 위해 다음 명령을 실행해야 할 수 있습니다.
```
chmod -R 755 get-logs.sh
```
**Example 마지막 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"
}
```
## 로그 삭제
함수를 삭제해도 로그 그룹이 자동으로 삭제되지 않습니다. 로그를 무기한 저장하지 않으려면 로그 그룹을 삭제하거나 로그가 자동으로 삭제되는 [보존 기간을 구성](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html#SettingLogRetention)하세요.
## Ruby 로거 라이브러리 작업
Ruby [로거 라이브러리](https://ruby-doc.org/stdlib-2.7.0/libdoc/logger/rdoc/index.html)는 쉽게 읽을 수 있는 간소화된 로그를 반환합니다. 로거 유틸리티를 사용하여 함수와 관련된 세부 정보, 메시지 및 오류 코드를 출력합니다.
```
# 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
```