Python Lambda 함수 로그 작성 및 모니터링

Python Lambda 함수 로그 작성 및 모니터링

AWS Lambda는 Lambda 함수를 자동으로 모니터링하고 로그 항목을 Amazon CloudWatch로 보내요. Lambda 함수에는 CloudWatch Logs 로그 그룹과 함수 인스턴스 각각에 대한 로그 스트림이 제공돼요. Lambda 런타임 환경은 각 호출에 대한 세부 정보와 함수 코드의 다른 출력을 로그 스트림으로 보내요. CloudWatch Logs에 대한 자세한 내용은 Lambda 함수 로그를 CloudWatch Logs로 보내기를 참고하세요.

함수 코드에서 로그를 출력하려면 기본 제공되는 logging 모듈을 사용할 수 있어요. 더 자세한 항목이 필요하면 stdout 또는 stderr에 쓰는 모든 로깅 라이브러리를 사용할 수 있어요.

출처: AWS Lambda 개발자 안내서

본문

로그에 출력하기

로그에 기본 출력을 보내려면 함수에서 print 메서드를 사용할 수 있어요. 다음 예시는 CloudWatch Logs 로그 그룹과 스트림의 값, 이벤트 객체를 기록해요.

함수가 Python print 문으로 로그를 출력하면 Lambda는 로그 출력을 일반 텍스트 형식으로만 CloudWatch Logs로 보낼 수 있다는 점에 유의하세요. 구조화된 JSON으로 로그를 캡처하려면 지원되는 로깅 라이브러리를 사용해야 해요. 자세한 내용은 Python과 함께 Lambda 고급 로깅 컨트롤 사용을 참고하세요.

예시 lambda_function.py

import os
def lambda_handler(event, context):
    print('## ENVIRONMENT VARIABLES')
    print(os.environ['AWS_LAMBDA_LOG_GROUP_NAME'])
    print(os.environ['AWS_LAMBDA_LOG_STREAM_NAME'])
    print('## EVENT')
    print(event)

예시 로그 출력

START RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95 Version: $LATEST
## ENVIRONMENT VARIABLES
/aws/lambda/my-function
2025/08/31/[$LATEST]3893xmpl7fac4485b47bb75b671a283c
## 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

Python 런타임은 각 호출에 대해 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 – 추적된 요청의 경우 샘플링 결과입니다.

로깅 라이브러리 사용

더 자세한 로그를 원하면 표준 라이브러리의 logging 모듈 또는 stdout이나 stderr에 쓰는 타사 로깅 라이브러리를 사용하세요.

지원되는 Python 런타임의 경우 표준 logging 모듈로 만든 로그를 일반 텍스트 또는 JSON으로 캡처할지 선택할 수 있어요. 자세한 내용은 Python과 함께 Lambda 고급 로깅 컨트롤 사용을 참고하세요.

현재 모든 Python 런타임의 기본 로그 형식은 일반 텍스트예요. 다음 예시는 표준 logging 모듈로 만든 로그 출력이 CloudWatch Logs에서 일반 텍스트로 캡처되는 방법을 보여줘요.

import os
import logging
logger = logging.getLogger()
logger.setLevel("INFO")

def lambda_handler(event, context):
    logger.info('## ENVIRONMENT VARIABLES')
    logger.info(os.environ['AWS_LAMBDA_LOG_GROUP_NAME'])
    logger.info(os.environ['AWS_LAMBDA_LOG_STREAM_NAME'])
    logger.info('## EVENT')
    logger.info(event)

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

START RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125 Version: $LATEST
[INFO]  2025-08-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## ENVIRONMENT VARIABLES
[INFO]  2025-08-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    /aws/lambda/my-function
[INFO]  2025-08-31T22:12:58.534Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    2025/01/31/[$LATEST]1bbe51xmplb34a2788dbaa7433b0aa4d
[INFO]  2025-08-31T22:12:58.535Z    1c8df7d3-xmpl-46da-9778-518e6eca8125    ## EVENT
[INFO]  2025-08-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

참고 함수의 로그 형식이 일반 텍스트로 설정되면 Python 런타임의 기본 로그 수준 설정은 WARN이에요. 즉 Lambda는 WARN 이하 수준의 로그 출력만 CloudWatch Logs로 보내요. 기본 로그 수준을 변경하려면 이 예시 코드와 같이 Python logging setLevel() 메서드를 사용하세요. 함수의 로그 형식을 JSON으로 설정한다면 코드에서 로그 수준을 설정하는 대신 Lambda 고급 로깅 컨트롤을 사용해 함수의 로그 수준을 구성하는 것을 권장해요. 자세한 내용은 Python과 함께 로그 수준 필터링 사용을 참고하세요.

Python과 함께 Lambda 고급 로깅 컨트롤 사용

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

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

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

Python Lambda 함수에서 로그 형식 및 로그 수준 옵션을 사용하는 방법에 대한 자세한 내용은 다음 섹션의 안내를 참고하세요.

Python과 함께 구조화된 JSON 로그 사용

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

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

Python logging 라이브러리는 이 JSON 객체에 "logger" 같은 추가 키-값 쌍도 추가할 수 있어요.

다음 섹션의 예시는 함수의 로그 형식을 JSON으로 구성할 때 Python logging 라이브러리로 생성한 로그 출력이 CloudWatch Logs에서 캡처되는 방법을 보여줘요.

로그에 출력하기에서 설명한 것처럼 print 메서드를 사용해 기본 로그 출력을 만들면 함수의 로깅 형식을 JSON으로 구성하더라도 Lambda는 이 출력을 일반 텍스트로 캡처한다는 점에 유의하세요.

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

다음 예시 코드 조각과 로그 출력은 함수의 로그 형식이 JSON으로 설정되었을 때 Python logging 라이브러리로 생성한 표준 로그 출력이 CloudWatch Logs에서 캡처되는 방법을 보여줘요.

예시 Python 로깅 코드

import logging  
logger = logging.getLogger()

def lambda_handler(event, context):
    logger.info("Inside the handler function")

예시 JSON 로그 레코드

{
    "timestamp":"2025-10-27T19:17:45.586Z",
    "level":"INFO",
    "message":"Inside the handler function",
    "logger": "root",
    "requestId":"79b4f56e-95b1-4643-9700-2807f4e68189"
}
JSON에서 추가 매개변수 로깅

함수의 로그 형식이 JSON으로 설정되면 extra 키워드를 사용해 Python 사전을 로그 출력에 전달해서 표준 Python logging 라이브러리로 추가 매개변수를 기록할 수도 있어요.

예시 Python 로깅 코드

import logging

def lambda_handler(event, context):
    logging.info(
        "extra parameters example", 
        extra={"a":"b", "b": [3]},
    )

예시 JSON 로그 레코드

{
  "timestamp": "2025-11-02T15:26:28Z",
  "level": "INFO",
  "message": "extra parameters example",
  "logger": "root",
  "requestId": "3dbd5759-65f6-45f8-8d7d-5bdc79a3bd01",
  "a": "b",
  "b": [
    3
  ]
}
JSON에서 예외 로깅

다음 코드 조각은 로그 형식을 JSON으로 구성했을 때 Python 예외가 함수의 로그 출력에서 캡처되는 방법을 보여줘요. logging.exception으로 생성된 로그 출력에는 ERROR 로그 수준이 할당된다는 점에 유의하세요.

예시 Python 로깅 코드

import logging

def lambda_handler(event, context):
    try:
        raise Exception("exception")
    except:
        logging.exception("msg")

예시 JSON 로그 레코드

{
  "timestamp": "2025-11-02T16:18:57Z",
  "level": "ERROR",
  "message": "msg",
  "logger": "root",
  "stackTrace": [
    "  File \"/var/task/lambda_function.py\", line 15, in lambda_handler\n    raise Exception(\"exception\")\n"
  ],
  "errorType": "Exception",
  "errorMessage": "exception",
  "requestId": "3f9d155c-0f09-46b7-bdf1-e91dab220855",
  "location": "/var/task/lambda_function.py:lambda_handler:17"
}
다른 로깅 도구와 함께 JSON 구조화 로그

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

다음 예시는 Powertools for AWS Lambda 패키지로 생성한 로그 출력이 CloudWatch Logs에서 캡처되는 방법을 보여줘요. 함수의 로깅 구성이 JSON이든 TEXT이든 이 로그 출력의 형식은 동일해요. Powertools for AWS Lambda 사용에 대한 자세한 내용은 구조화 로깅을 위한 Powertools for AWS Lambda(Python) 및 AWS SAM 사용과 구조화 로깅을 위한 Powertools for AWS Lambda(Python) 및 AWS CDK 사용을 참고하세요.

예시 Python 로깅 코드 조각(Powertools for AWS Lambda 사용)

from aws_lambda_powertools import Logger

logger = Logger()

def lambda_handler(event, context):
    logger.info("Inside the handler function")

예시 JSON 로그 레코드(Powertools for AWS Lambda 사용)

{ 
    "level": "INFO", 
    "location": "lambda_handler:7", 
    "message": "Inside the handler function", 
    "timestamp": "2025-10-31 22:38:21,010+0000", 
    "service": "service_undefined", 
    "xray_trace_id": "1-654181dc-65c15d6b0fecbdd1531ecb30" 
}

Python과 함께 로그 수준 필터링 사용

로그 수준 필터링을 구성하면 특정 로깅 수준 이하의 로그만 CloudWatch Logs로 보내도록 선택할 수 있어요. 함수에 대한 로그 수준 필터링을 구성하는 방법은 로그 수준 필터링을 참고하세요.

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

  • 표준 Python logging 라이브러리로 로그 출력을 만들고 함수가 JSON 로그 형식을 사용하도록 구성합니다. 그러면 AWS Lambda는 Python과 함께 구조화된 JSON 로그 사용에서 설명한 JSON 객체의 "level" 키-값 쌍을 사용해서 로그 출력을 필터링해요. 함수의 로그 형식을 구성하는 방법은 Lambda 함수에 대한 고급 로깅 컨트롤 구성을 참고하세요.

  • 다른 로깅 라이브러리나 방법을 사용해서 코드에서 로그 출력 수준을 정의하는 "level" 키-값 쌍을 포함한 JSON 구조화 로그를 만듭니다. 예를 들어 Powertools for AWS Lambda를 사용해서 코드에서 JSON 구조화 로그 출력을 생성할 수 있어요.

    또한 print 문을 사용해서 로그 수준 식별자를 포함한 JSON 객체를 출력할 수도 있어요. 다음 print 문은 로그 수준이 INFO로 설정된 JSON 형식 출력을 만들어요. 함수의 로깅 수준이 INFO, DEBUG, TRACE로 설정되어 있으면 AWS Lambda는 JSON 객체를 CloudWatch Logs로 보내요.

    print('{"msg":"My log message", "level":"info"}')

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

Lambda 콘솔에서 로그 보기

Lambda 함수를 호출한 후 Lambda 콘솔을 사용해서 로그 출력을 볼 수 있어요.

코드를 포함된 코드(Code) 편집기에서 테스트할 수 있다면 실행 결과(execution results)에서 로그를 확인할 수 있어요. 콘솔 테스트 기능으로 함수를 호출하면 세부 정보(Details) 섹션에서 로그 출력(Log output)을 확인할 수 있어요.

CloudWatch 콘솔에서 로그 보기

Amazon CloudWatch 콘솔을 사용해서 모든 Lambda 함수 호출에 대한 로그를 볼 수 있어요.

CloudWatch 콘솔에서 로그를 보려면

  1. CloudWatch 콘솔의 로그 그룹 페이지를 엽니다.

  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

cli-binary-format 옵션은 AWS CLI 버전 2를 사용하는 경우 필요해요. 기본 설정으로 만들려면 aws configure set cli-binary-format raw-in-base64-out을 실행하세요. 자세한 내용은 *AWS Command Line Interface 사용 설명서(버전 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로 저장하세요. cli-binary-format 옵션은 AWS CLI 버전 2를 사용하는 경우 필요해요. 기본 설정으로 만들려면 aws configure set cli-binary-format raw-in-base64-out을 실행하세요. 자세한 내용은 *AWS Command Line Interface 사용 설명서(버전 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"
}

로그 삭제

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

다른 로깅 도구 및 라이브러리 사용

Powertools for AWS Lambda (Python)은 Serverless 모범 사례를 구현하고 개발자 생산성을 높이기 위한 개발자 툴킷이에요. Logger 유틸리티는 모든 함수에 걸쳐 함수 컨텍스트에 대한 추가 정보를 JSON으로 구조화된 출력으로 포함하는 Lambda 최적화 로거를 제공해요. 이 유틸리티를 사용해서 다음 작업을 할 수 있어요:

  • Lambda 컨텍스트의 핵심 필드를 캡처하고, 콜드 스타트를 캡처하며, 로깅 출력을 JSON으로 구조화
  • 지시된 경우 Lambda 호출 이벤트 기록(기본적으로 비활성화)
  • 로그 샘플링을 통해 호출의 일정 비율에 대해서만 모든 로그 출력(기본적으로 비활성화)
  • 구조화된 로그에 원하는 시점에 추가 키 추가
  • 사용자 지정 로그 포맷터(Bring Your Own Formatter)를 사용해서 조직의 로깅 RFC와 호환되는 구조로 로그 출력

구조화 로깅을 위한 Powertools for AWS Lambda(Python) 및 AWS SAM 사용

AWS SAM을 사용해서 통합된 Powertools for Python 모듈이 있는 샘플 Hello World Python 애플리케이션을 다운로드·빌드·배포하려면 다음 단계를 따르세요. 이 애플리케이션은 기본 API 백엔드를 구현하고 Powertools를 사용해서 로그·지표·트레이스를 내보내요. 이 애플리케이션은 Amazon API Gateway 엔드포인트와 Lambda 함수로 구성돼요. API Gateway 엔드포인트로 GET 요청을 보내면 Lambda 함수가 호출되어 Embedded Metric Format을 사용해 로그와 지표를 CloudWatch로 보내고 트레이스를 AWS X-Ray로 보내요. 함수는 hello world 메시지를 반환해요.

사전 요구 사항

이 섹션의 단계를 완료하려면 다음이 있어야 해요:

샘플 AWS SAM 애플리케이션 배포

  1. Hello World Python 템플릿을 사용해서 애플리케이션을 초기화합니다.

    sam init --app-template hello-world-powertools-python --name sam-app --package-type Zip --runtime python3.9 --no-tracing

  2. 앱을 빌드합니다.

    cd sam-app && sam build

  3. 앱을 배포합니다.

    sam deploy --guided

  4. 화면의 프롬프트를 따릅니다. 대화형 환경에서 제공되는 기본 옵션을 수락하려면 Enter를 누르세요. 참고 HelloWorldFunction may not have authorization defined, Is this okay? 에 대해 y를 입력해야 합니다.

  5. 배포된 애플리케이션의 URL을 가져옵니다:

    aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text

  6. API 엔드포인트를 호출합니다:

    curl GET {{<URL_FROM_PREVIOUS_STEP>}}

    성공하면 다음 응답이 표시됩니다:

    {"message":"hello world"}

  7. 함수의 로그를 가져오려면 sam logs를 실행합니다. 자세한 내용은 AWS Serverless Application Model 개발자 안내서의 로그 작업을 참고하세요.

    sam logs --stack-name sam-app

    로그 출력은 다음과 같습니다:

    2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:50.371000 INIT_START Runtime Version: python:3.9.v16    Runtime Version ARN: arn:aws:lambda:us-east-1::runtime:07a48df201798d627f2b950f03bb227aab4a655a1d019c3296406f95937e2525
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.112000 START RequestId: d455cfc4-7704-46df-901b-2a5cce9405be Version: $LATEST
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.114000 {
  "level": "INFO",
  "location": "hello:23",
  "message": "Hello world API - HTTP 200",
  "timestamp": "2025-02-03 14:59:51,113+0000",
  "service": "PowertoolsHelloWorld",
  "cold_start": true,
  "function_name": "sam-app-HelloWorldFunction-YBg8yfYtOc9j",
  "function_memory_size": "128",
  "function_arn": "arn:aws:lambda:us-east-1:111122223333:function:sam-app-HelloWorldFunction-YBg8yfYtOc9j",
  "function_request_id": "d455cfc4-7704-46df-901b-2a5cce9405be",
  "correlation_id": "e73f8aef-5e07-436e-a30b-63e4b23f0047",
  "xray_trace_id": "1-63dd2166-434a12c22e1307ff2114f299"
}
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.126000 {
  "_aws": {
    "Timestamp": 1675436391126,
    "CloudWatchMetrics": [
      {
        "Namespace": "Powertools",
        "Dimensions": [
          [
            "function_name",
            "service"
          ]
        ],
        "Metrics": [
          {
            "Name": "ColdStart",
            "Unit": "Count"
          }
        ]
      }
    ]
  },
  "function_name": "sam-app-HelloWorldFunction-YBg8yfYtOc9j",
  "service": "PowertoolsHelloWorld",
  "ColdStart": [
    1.0
  ]
}
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.126000 {
  "_aws": {
    "Timestamp": 1675436391126,
    "CloudWatchMetrics": [
      {
        "Namespace": "Powertools",
        "Dimensions": [
          [
            "service"
          ]
        ],
        "Metrics": [
          {
            "Name": "HelloWorldInvocations",
            "Unit": "Count"
          }
        ]
      }
    ]
  },
  "service": "PowertoolsHelloWorld",
  "HelloWorldInvocations": [
    1.0
  ]
}
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.128000 END RequestId: d455cfc4-7704-46df-901b-2a5cce9405be
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.128000 REPORT RequestId: d455cfc4-7704-46df-901b-2a5cce9405be    Duration: 16.33 ms    Billed Duration: 756 ms    Memory Size: 128 MB    Max Memory Used: 64 MB    Init Duration: 739.46 ms    
XRAY TraceId: 1-63dd2166-434a12c22e1307ff2114f299    SegmentId: 3c5d18d735a1ced0    Sampled: true

  8. 이것은 인터넷을 통해 접근할 수 있는 공개 API 엔드포인트예요. 테스트 후에는 엔드포인트를 삭제하는 것을 권장합니다.

    sam delete

로그 보존 관리

함수를 삭제해도 로그 그룹은 자동으로 삭제되지 않아요. 로그를 무기한 저장하지 않으려면 로그 그룹을 삭제하거나, CloudWatch가 로그를 자동으로 삭제하는 보존 기간을 구성하세요. 로그 보존을 설정하려면 AWS SAM 템플릿에 다음을 추가하세요:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      # Omitting other properties

  LogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub "/aws/lambda/${HelloWorldFunction}"
      RetentionInDays: 7

구조화 로깅을 위한 Powertools for AWS Lambda(Python) 및 AWS CDK 사용

AWS CDK를 사용해서 통합된 Powertools for AWS Lambda (Python) 모듈이 있는 샘플 Hello World Python 애플리케이션을 다운로드·빌드·배포하려면 다음 단계를 따르세요. 이 애플리케이션은 기본 API 백엔드를 구현하고 Powertools를 사용해서 로그·지표·트레이스를 내보내요. 이 애플리케이션은 Amazon API Gateway 엔드포인트와 Lambda 함수로 구성돼요. API Gateway 엔드포인트로 GET 요청을 보내면 Lambda 함수가 호출되어 Embedded Metric Format을 사용해 로그와 지표를 CloudWatch로 보내고 트레이스를 AWS X-Ray로 보내요. 함수는 hello world 메시지를 반환해요.

사전 요구 사항

이 섹션의 단계를 완료하려면 다음이 있어야 해요:

샘플 AWS CDK 애플리케이션 배포

  1. 새 애플리케이션용 프로젝트 디렉터리를 만듭니다.

    mkdir hello-world
cd hello-world

  2. 앱을 초기화합니다.

    cdk init app --language python

  3. Python 종속성을 설치합니다.

    pip install -r requirements.txt

  4. 루트 폴더 아래에 lambda_function 디렉터리를 만듭니다.

    mkdir lambda_function
cd lambda_function

  5. app.py 파일을 만들고 다음 코드를 파일에 추가합니다. 이것은 Lambda 함수용 코드입니다.

    from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools import Logger
from aws_lambda_powertools import Tracer
from aws_lambda_powertools import Metrics
from aws_lambda_powertools.metrics import MetricUnit

app = APIGatewayRestResolver()
tracer = Tracer()
logger = Logger()
metrics = Metrics(namespace="PowertoolsSample")

@app.get("/hello")
@tracer.capture_method
def hello():
    # adding custom metrics
    # See: https://docs.aws.amazon.com/powertools/python/latest//latest/core/metrics/
    metrics.add_metric(name="HelloWorldInvocations", unit=MetricUnit.Count, value=1)

    # structured log
    # See: https://docs.aws.amazon.com/powertools/python/latest//latest/core/logger/
    logger.info("Hello world API - HTTP 200")
    return {"message": "hello world"}

# Enrich logging with contextual information from Lambda
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
# Adding tracer
# See: https://docs.aws.amazon.com/powertools/python/latest//latest/core/tracer/
@tracer.capture_lambda_handler
# ensures metrics are flushed upon request completion/failure and capturing ColdStart metric
@metrics.log_metrics(capture_cold_start_metric=True)
def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

  6. hello_world 디렉터리를 엽니다. hello_world_stack.py라는 파일이 보일 거예요.

    cd ..
cd hello_world

  7. hello_world_stack.py를 열고 다음 코드를 파일에 추가합니다. 여기에는 Lambda 함수를 만들고, Powertools용 환경 변수를 구성하고, 로그 보존을 1주일로 설정하는 Lambda Constructor와 REST API를 만드는 ApiGatewayv1 Constructor가 포함됩니다.

    from aws_cdk import (
    Stack,
    aws_apigateway as apigwv1,
    aws_lambda as lambda_,
    CfnOutput,
    Duration
)
from constructs import Construct

class HelloWorldStack(Stack):

    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Powertools Lambda Layer
        powertools_layer = lambda_.LayerVersion.from_layer_version_arn(
            self,
            id="lambda-powertools",
            # Using AWS Lambda Powertools with Lambda Layer
            # This imports the Powertools layer which provides observability features for Lambda functions
            # For available versions, see: https://docs.aws.amazon.com/powertools/python/latest/#lambda-layer
        )

        function = lambda_.Function(self,
            'sample-app-lambda',
            runtime=lambda_.Runtime.PYTHON_3_9,
            layers=[powertools_layer],
            code = lambda_.Code.from_asset("./lambda_function/"),
            handler="app.lambda_handler",
            memory_size=128,
            timeout=Duration.seconds(3),
            architecture=lambda_.Architecture.X86_64,
            environment={
                "POWERTOOLS_SERVICE_NAME": "PowertoolsHelloWorld",
                "POWERTOOLS_METRICS_NAMESPACE": "PowertoolsSample",
                "LOG_LEVEL": "INFO"
            }
        )

        apigw = apigwv1.RestApi(self, "PowertoolsAPI", deploy_options=apigwv1.StageOptions(stage_name="dev"))

        hello_api = apigw.root.add_resource("hello")
        hello_api.add_method("GET", apigwv1.LambdaIntegration(function, proxy=True))

        CfnOutput(self, "apiUrl", value=f"{apigw.url}hello")

  8. 애플리케이션을 배포합니다.

    cd ..
cdk deploy

  9. 배포된 애플리케이션의 URL을 가져옵니다:

    aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?OutputKey==`apiUrl`].OutputValue' --output text

  10. API 엔드포인트를 호출합니다:

    curl GET {{<URL_FROM_PREVIOUS_STEP>}}

    성공하면 다음 응답이 표시됩니다:

    {"message":"hello world"}

  11. 함수의 로그를 가져오려면 sam logs를 실행합니다. 자세한 내용은 AWS Serverless Application Model 개발자 안내서의 로그 작업을 참고하세요.

    sam logs --stack-name HelloWorldStack

    로그 출력은 다음과 같습니다:

    2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:50.371000 INIT_START Runtime Version: python:3.9.v16    Runtime Version ARN: arn:aws:lambda:us-east-1::runtime:07a48df201798d627f2b950f03bb227aab4a655a1d019c3296406f95937e2525
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.112000 START RequestId: d455cfc4-7704-46df-901b-2a5cce9405be Version: $LATEST
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.114000 {
  "level": "INFO",
  "location": "hello:23",
    "message": "Hello world API - HTTP 200",
  "timestamp": "2025-02-03 14:59:51,113+0000",
  "service": "PowertoolsHelloWorld",
  "cold_start": true,
  "function_name": "sam-app-HelloWorldFunction-YBg8yfYtOc9j",
  "function_memory_size": "128",
  "function_arn": "arn:aws:lambda:us-east-1:111122223333:function:sam-app-HelloWorldFunction-YBg8yfYtOc9j",
  "function_request_id": "d455cfc4-7704-46df-901b-2a5cce9405be",
  "correlation_id": "e73f8aef-5e07-436e-a30b-63e4b23f0047",
  "xray_trace_id": "1-63dd2166-434a12c22e1307ff2114f299"
}
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.126000 {
  "_aws": {
    "Timestamp": 1675436391126,
    "CloudWatchMetrics": [
      {
        "Namespace": "Powertools",
        "Dimensions": [
          [
            "function_name",
            "service"
          ]
        ],
        "Metrics": [
          {
            "Name": "ColdStart",
            "Unit": "Count"
          }
        ]
      }
    ]
  },
  "function_name": "sam-app-HelloWorldFunction-YBg8yfYtOc9j",
  "service": "PowertoolsHelloWorld",
  "ColdStart": [
    1.0
  ]
}
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.126000 {
  "_aws": {
    "Timestamp": 1675436391126,
    "CloudWatchMetrics": [
      {
        "Namespace": "Powertools",
        "Dimensions": [
          [
            "service"
          ]
        ],
        "Metrics": [
          {
            "Name": "HelloWorldInvocations",
            "Unit": "Count"
          }
        ]
      }
    ]
  },
  "service": "PowertoolsHelloWorld",
  "HelloWorldInvocations": [
    1.0
  ]
}
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.128000 END RequestId: d455cfc4-7704-46df-901b-2a5cce9405be
2025/02/03/[$LATEST]ea9a64ec87294bf6bbc9026c05a01e04 2025-02-03T14:59:51.128000 REPORT RequestId: d455cfc4-7704-46df-901b-2a5cce9405be    Duration: 16.33 ms    Billed Duration: 756 ms    Memory Size: 128 MB    Max Memory Used: 64 MB    Init Duration: 739.46 ms    
XRAY TraceId: 1-63dd2166-434a12c22e1307ff2114f299    SegmentId: 3c5d18d735a1ced0    Sampled: true

  12. 이것은 인터넷을 통해 접근할 수 있는 공개 API 엔드포인트예요. 테스트 후에는 엔드포인트를 삭제하는 것을 권장합니다.

    cdk destroy

더 알아보기 (Learn more)

이 주제는 Python Lambda 함수의 로그 작성·모니터링 방법을 설명해요. 고급 로깅 컨트롤과 CloudWatch Logs 통합에 대한 자세한 내용은 Lambda 개발자 안내서의 관련 주제를 참고하세요.