TypeScript Lambda 함수 로그 및 모니터링

TypeScript Lambda 함수 로그 및 모니터링

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

함수 코드에서 로그를 출력하려면 console 객체의 메서드를 사용할 수 있어요. 더 상세한 로깅이 필요하면 stdout 또는 stderr에 쓰는 아무 로깅 라이브러리를 사용할 수 있어요.

출처: AWS Lambda 개발자 안내서

본문

주제(Topics)

• 로깅 도구와 라이브러리 사용
• Powertools for AWS Lambda(TypeScript)와 AWS SAM으로 구조화 로깅
• Powertools for AWS Lambda(TypeScript)와 AWS CDK로 구조화 로깅
• Lambda 콘솔에서 로그 보기
• CloudWatch 콘솔에서 로그 보기

로깅 도구와 라이브러리 사용

Powertools for AWS Lambda(TypeScript)는 서버리스 모범 사례를 구현하고 개발 속도를 높이기 위한 개발자 도구 키트예요. Logger 유틸리티는 모든 함수에서 함수 컨텍스트에 대한 추가 정보를 포함하고 JSON으로 구조화된 출력을 제공하는 Lambda 최적화 로거를 제공해요. 이 유틸리티를 사용해서 다음을 수행할 수 있어요.

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

Powertools for AWS Lambda(TypeScript)와 AWS SAM으로 구조화 로깅

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

사전 조건(Prerequisites)

이 섹션의 단계를 완료하려면 다음이 필요해요.

• Node.js 20 이상
• AWS CLI 버전 2
• AWS SAM CLI 버전 1.75 이상. 더 오래된 버전의 AWS SAM CLI가 있다면 AWS SAM CLI 업그레이드를 참고하세요.

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

1. Hello World TypeScript 템플릿을 사용해서 애플리케이션을 초기화해요.

   sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x
   

2. 앱을 빌드해요.

   cd sam-app && sam build
   

3. 앱을 배포해요.

   sam deploy --guided
   

4. 화면의 프롬프트를 따라가요. 대화형 환경에서 제공되는 기본 옵션을 받아들이려면 Enter를 눌러요. 참고(Note)
   **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 {{<URL_FROM_PREVIOUS_STEP>}}
   

   성공하면 다음과 같은 응답을 볼 수 있어요.

   {"message":"hello world"}
   

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

   sam logs --stack-name sam-app
   

   로그 출력은 다음과 같아요.

   2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.552000 START RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Version: $LATEST
   2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.594000 2025-08-31T09:33:10.557Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390556,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[{"Name":"ColdStart","Unit":"Count"}]}]},"service":"helloWorld","ColdStart":1}
   2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.595000 2025-08-31T09:33:10.595Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"level":"INFO","message":"This is an INFO log - sending HTTP 200 - hello world response","service":"helloWorld","timestamp":"2025-08-31T09:33:10.594Z"}
   2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.655000 2025-08-31T09:33:10.655Z 70693159-7e94-4102-a2af-98a6343fb8fb INFO {"_aws":{"Timestamp":1661938390655,"CloudWatchMetrics":[{"Namespace":"sam-app","Dimensions":[["service"]],"Metrics":[]}]},"service":"helloWorld"}
   2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.754000 END RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb
   2025/01/31/[$LATEST]4d53e8d279824834a1ccd35511a4949c 2025-08-31T09:33:10.754000 REPORT RequestId: 70693159-7e94-4102-a2af-98a6343fb8fb Duration: 201.55 ms Billed Duration: 202 ms Memory Size: 128 MB Max Memory Used: 66 MB Init Duration: 252.42 ms
   XRAY TraceId: 1-630f2ad5-1de22b6d29a658a466e7ecf5 SegmentId: 567c116658fbf11a 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(TypeScript)와 AWS CDK로 구조화 로깅

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

사전 조건(Prerequisites)

이 섹션의 단계를 완료하려면 다음이 필요해요.

• Node.js 20 이상
• AWS CLI 버전 2
• AWS CDK 버전 2
• AWS SAM CLI 버전 1.75 이상. 더 오래된 버전의 AWS SAM CLI가 있다면 AWS SAM CLI 업그레이드를 참고하세요.

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

1. 새 애플리케이션의 프로젝트 디렉토리를 만드세요.

   mkdir hello-world
   cd hello-world
   

2. 앱을 초기화해요.

   cdk init app --language typescript
   

3. @types/aws-lambda 패키지를 개발 종속성으로 추가해요.

   npm install -D @types/aws-lambda
   

4. Powertools Logger 유틸리티를 설치해요.

   npm install @aws-lambda-powertools/logger
   

5. lib 디렉토리를 열어요. hello-world-stack.ts라는 파일이 보일 거예요. 이 디렉토리에 hello-world.function.ts와 hello-world.ts라는 새 파일 두 개를 만들어요.

6. hello-world.function.ts를 열고 다음 코드를 파일에 추가해요. 이것이 Lambda 함수의 코드예요.

   import { APIGatewayEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
   import { Logger } from '@aws-lambda-powertools/logger';
   const logger = new Logger();
   
   export const handler = async (event: APIGatewayEvent, context: Context): Promise<APIGatewayProxyResult> => {
     logger.info('This is an INFO log - sending HTTP 200 - hello world response');
     return {
       statusCode: 200,
       body: JSON.stringify({
         message: 'hello world',
       }),
     };
   };
   

7. hello-world.ts를 열고 다음 코드를 파일에 추가해요. 여기에는 Lambda 함수를 만들고 Powertools용 환경 변수를 구성하며 로그 보존 기간을 1주일로 설정하는 NodejsFunction construct가 포함돼 있어요. 또한 REST API를 만드는 LambdaRestApi construct도 포함돼 있어요.

   import { Construct } from 'constructs';
   import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
   import { LambdaRestApi } from 'aws-cdk-lib/aws-apigateway';
   import { RetentionDays } from 'aws-cdk-lib/aws-logs';
   import { CfnOutput } from 'aws-cdk-lib';
   
   export class HelloWorld extends Construct {
     constructor(scope: Construct, id: string) {
       super(scope, id);
       const helloFunction = new NodejsFunction(this, 'function', {
         environment: {
           Powertools_SERVICE_NAME: 'helloWorld',
           LOG_LEVEL: 'INFO',
         },
         logRetention: RetentionDays.ONE_WEEK,
       });
       const api = new LambdaRestApi(this, 'apigw', {
         handler: helloFunction,
       });
       new CfnOutput(this, 'apiUrl', {
         exportName: 'apiUrl',
         value: api.url,
       });
     }
   }
   

8. hello-world-stack.ts를 열어요. 이것이 AWS CDK 스택을 정의하는 코드예요. 코드를 다음으로 바꿔요.

   import { Stack, StackProps } from 'aws-cdk-lib';
   import { Construct } from 'constructs';
   import { HelloWorld } from './hello-world';
   
   export class HelloWorldStack extends Stack {
     constructor(scope: Construct, id: string, props?: StackProps) {
       super(scope, id, props);
       new HelloWorld(this, 'hello-world');
     }
   }
   

9. 프로젝트 디렉토리로 돌아가요.

   cd hello-world
   

10. 애플리케이션을 배포해요.

    cdk deploy
    

11. 배포된 애플리케이션의 URL을 가져와요.

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

12. API 엔드포인트를 호출해요.

    curl {{<URL_FROM_PREVIOUS_STEP>}}
    

    성공하면 다음과 같은 응답을 볼 수 있어요.

    {"message":"hello world"}
    

13. 함수의 로그를 보려면 sam logs를 실행해요. 자세한 내용은 AWS Serverless Application Model 개발자 안내서의 로그 작업을 참고하세요.

    sam logs --stack-name HelloWorldStack
    

    로그 출력은 다음과 같아요.

    2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.047000 START RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Version: $LATEST
    2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.050000 {
    "level": "INFO",
    "message": "This is an INFO log - sending HTTP 200 - hello world response",
    "service": "helloWorld",
    "timestamp": "2025-08-31T14:48:37.048Z",
    "xray_trace_id": "1-630f74c4-2b080cf77680a04f2362bcf2"
    }
    2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.082000 END RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c
    2025/01/31/[$LATEST]2ca67f180dcd4d3e88b5d68576740c8e 2025-08-31T14:48:37.082000 REPORT RequestId: 19ad1007-ff67-40ce-9afe-0af0a9eb512c Duration: 34.60 ms Billed Duration: 35 ms Memory Size: 128 MB Max Memory Used: 57 MB Init Duration: 173.48 ms
    

14. 이것은 인터넷을 통해 접근 가능한 공개 API 엔드포인트예요. 테스트 후에는 엔드포인트를 삭제하는 것을 권장해요.

    cdk destroy
    

Lambda 콘솔에서 로그 보기

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

코드를 내장 Code 편집기에서 테스트할 수 있다면 execution results에서 로그를 찾을 수 있어요. 콘솔 테스트 기능으로 함수를 호출하면 Details 섹션에서 Log output을 찾을 수 있어요.

CloudWatch 콘솔에서 로그 보기

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

CloudWatch 콘솔에서 로그를 보려면

1. CloudWatch 콘솔에서 Log groups 페이지를 열어요.

2. 함수의 로그 그룹(/aws/lambda/{{your-function-name}})을 선택해요.

3. 로그 스트림을 선택해요.

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

더 알아보기 (Learn more)

Lambda 함수 로그를 CloudWatch Logs로 보내는 방법은 Lambda 함수 로그를 CloudWatch Logs로 보내기를 참고하세요. 로그 형식 구성에 대한 내용은 JSON 및 일반 텍스트 로그 형식 구성을 참고하세요.