# TypeScript Lambda 함수 로깅 및 모니터링
AWS Lambda는 자동으로 Lambda 함수를 모니터링하고 로그 항목을 Amazon CloudWatch로 보냅니다. Lambda 함수는 함수의 각 인스턴스에 대한 CloudWatch Logs 로그 그룹 및 로그 스트림과 함께 제공됩니다. Lambda 런타임 환경은 각 간접 호출에 대한 세부 정보와 함수 코드의 기타 출력을 로그 스트림으로 전송합니다. CloudWatch Logs에 대한 자세한 내용은 [CloudWatch Logs로 Lambda 함수 로그 전송](monitoring-cloudwatchlogs.md) 섹션을 참조하세요.
함수 코드의 로그를 출력하려면 [콘솔 객체](https://nodejs.org/docs/latest-v18.x/api/console.html)의 메서드를 사용합니다. 보다 자세한 로깅을 위해 `stdout` 또는 `stderr`에 쓰는 로깅 라이브러리를 사용할 수 있습니다.
**Topics**
+ [로깅 도구 및 라이브러리 사용](#typescript-tools-libraries)
+ [구조화된 로깅에 Powertools for AWS Lambda(TypeScript) 및 AWS SAM 사용](#typescript-logging-sam)
+ [구조화된 로깅에 Powertools for AWS Lambda(TypeScript) 및 AWS CDK 사용](#typescript-logging-cdk)
+ [Lambda 콘솔에서 로그 보기](#typescript-logging-console)
+ [CloudWatch 콘솔에서 로그 보기](#typescript-logging-cwconsole)
## 로깅 도구 및 라이브러리 사용
[Powertools for AWS Lambda(TypeScript)](https://docs.aws.amazon.com/powertools/typescript/)는 서버리스 모범 사례를 구현하고 개발자 속도를 높이기 위한 개발자 도구 키트입니다. [Logger 유틸리티](https://docs.powertools.aws.dev/lambda/typescript/latest/features/logger/)는 JSON으로 구조화된 출력과 함께 모든 함수의 함수 컨텍스트에 대한 추가 정보를 포함하는 Lambda 최적화 로거를 제공합니다. 이 유틸리티를 사용하여 다음을 수행합니다.
+ Lambda 컨텍스트, 콜드 스타트 및 구조 로깅 출력에서 JSON으로 주요 필드 캡처
+ 지시 시 Lambda 호출 이벤트 로깅(기본적으로 비활성화됨)
+ 로그 샘플링을 통해 호출 비율에 대해서만 모든 로그 인쇄(기본적으로 비활성화됨)
+ 언제든지 구조화된 로그에 추가 키 추가
+ 사용자 지정 로그 포맷터(Bring Your Own Formatter)를 사용하여 조직의 로깅 RFC와 호환되는 구조로 로그 출력
## 구조화된 로깅에 Powertools for AWS Lambda(TypeScript) 및 AWS SAM 사용
다음 단계에 따라 AWS SAM을 사용하는 통합 [Powertools for AWS Lambda(TypeScript)](https://docs.powertools.aws.dev/lambda-typescript) 모듈로 샘플 Hello World TypeScript 애플리케이션을 다운로드, 빌드 및 배포합니다. 이 애플리케이션은 기본 API 백엔드를 구현하고 Powertools를 사용하여 로그, 지표 및 추적을 내보냅니다. 이 구성에는 Amazon API Gateway 엔드포인트와 Lambda 함수가 포함됩니다. API Gateway 엔드포인트로 GET 요청을 전송하면 Lambda 함수가 간접 호출되고 Embedded Metric Format을 사용하여 로그 및 지표를 CloudWatch로 전송하고 기록을 AWS X-Ray로 전송합니다. 이 함수는 `hello world` 메시지를 반환합니다.
**사전 조건**
이 섹션의 단계를 완료하려면 다음이 필요합니다.
+ Node.js 20 이상
+ [AWS CLI 버전 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS SAM CLI 버전 1.75 이상](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). 이전 버전의 AWS SAM CLI가 있는 경우 [AWS SAM CLI 업그레이드](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade)를 참조하세요.
**샘플 AWS SAM 애플리케이션 배포**
1. Hello World TypeScript 템플릿을 사용하여 애플리케이션을 초기화합니다.
```
sam init --app-template hello-world-powertools-typescript --name sam-app --package-type Zip --runtime nodejs24.x
```
1. 앱을 빌드합니다.
```
cd sam-app && sam build
```
1. 앱을 배포합니다.
```
sam deploy --guided
```
1. 화면에 표시되는 프롬프트를 따릅니다. 대화형 환경에서 제공되는 기본 옵션을 수락하려면 `Enter`을 누릅니다.
**참고**
**HelloWorldFunction에 권한 부여가 정의되어 있지 않을 수 있습니다. 괜찮습니다?**에 대해 `y`를 입력합니다.
1. 배포된 애플리케이션의 URL을 가져옵니다.
```
aws cloudformation describe-stacks --stack-name sam-app --query 'Stacks[0].Outputs[?OutputKey==`HelloWorldApi`].OutputValue' --output text
```
1. API 엔드포인트 간접 호출:
```
curl
```
성공하면 다음과 같은 결과가 응답됩니다.
```
{"message":"hello world"}
```
1. 함수에 대한 로그를 가져오려면 [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html)를 실행합니다. 자세한 내용은 *AWS Serverless Application Model 개발자 안내서*에서 [로그 관련 작업](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html)을 참조하세요.
```
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
```
1. 이는 인터넷을 통해 액세스할 수 있는 퍼블릭 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)](https://docs.powertools.aws.dev/lambda-typescript) 모듈로 샘플 Hello World TypeScript 애플리케이션을 다운로드, 빌드 및 배포합니다. 이 애플리케이션은 기본 API 백엔드를 구현하고 Powertools를 사용하여 로그, 지표 및 추적을 내보냅니다. 이 구성에는 Amazon API Gateway 엔드포인트와 Lambda 함수가 포함됩니다. API Gateway 엔드포인트로 GET 요청을 전송하면 Lambda 함수가 간접 호출되고 Embedded Metric Format을 사용하여 로그 및 지표를 CloudWatch로 전송하고 기록을 AWS X-Ray로 전송합니다. 이 함수는 `hello world` 메시지를 반환합니다.
**사전 조건**
이 섹션의 단계를 완료하려면 다음이 필요합니다.
+ Node.js 20 이상
+ [AWS CLI 버전 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+ [AWS CDK 버전 2](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites)
+ [AWS SAM CLI 버전 1.75 이상](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). 이전 버전의 AWS SAM CLI가 있는 경우 [AWS SAM CLI 업그레이드](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/manage-sam-cli-versions.html#manage-sam-cli-versions-upgrade)를 참조하세요.
**샘플 AWS CDK 애플리케이션 배포**
1. 새 애플리케이션용 프로젝트 디렉터리를 생성합니다.
```
mkdir hello-world
cd hello-world
```
1. 앱을 초기화합니다.
```
cdk init app --language typescript
```
1. [@types/aws-lambda](https://www.npmjs.com/package/@types/aws-lambda) 패키지를 개발 종속성으로 추가합니다.
```
npm install -D @types/aws-lambda
```
1. Powertools [Logger 유틸리티](https://docs.aws.amazon.com/powertools/typescript/latest/features/logger/)를 설치합니다.
```
npm install @aws-lambda-powertools/logger
```
1. **lib** 디렉터리를 엽니다. **hello-world-stack.ts**라는 이름의 파일이 있어야 합니다. 이 디렉터리에 **hello-world.function.ts**와 **hello-world.ts**하는 2개의 새 파일을 만듭니다.
1. **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 => {
logger.info('This is an INFO log - sending HTTP 200 - hello world response');
return {
statusCode: 200,
body: JSON.stringify({
message: 'hello world',
}),
};
};
```
1. **hello-world.ts**를 열고 파일에 다음 코드를 추가합니다. 여기에는 Lambda 함수를 생성하고, Powertools용 환경 변수를 구성하고, 로그 보존을 1주일로 설정하는 [NodeJSFunction 구성체](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs-readme.html)가 포함됩니다. 또한 REST API를 생성하는 [LambdaRestAPI 구성체](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.LambdaRestApi.html)도 포함되어 있습니다.
```
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,
});
}
}
```
1. **hello-world-stack.ts**를 엽니다. 이 코드는 [AWS CDK 스택](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html)을 정의하는 코드입니다. 코드를 다음으로 바꿉니다.
```
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');
}
}
```
1. 프로젝트 디렉터리로 돌아갑니다.
```
cd hello-world
```
1. 애플리케이션 배포
```
cdk deploy
```
1. 배포된 애플리케이션의 URL을 가져옵니다.
```
aws cloudformation describe-stacks --stack-name HelloWorldStack --query 'Stacks[0].Outputs[?ExportName==`apiUrl`].OutputValue' --output text
```
1. API 엔드포인트 간접 호출:
```
curl
```
성공하면 다음과 같은 결과가 응답됩니다.
```
{"message":"hello world"}
```
1. 함수에 대한 로그를 가져오려면 [sam logs](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-logs.html)를 실행합니다. 자세한 내용은 *AWS Serverless Application Model 개발자 안내서*에서 [로그 관련 작업](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html)을 참조하세요.
```
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
```
1. 이는 인터넷을 통해 액세스할 수 있는 퍼블릭 API 엔드포인트입니다. 테스트 후에는 엔드포인트를 삭제하는 것이 좋습니다.
```
cdk destroy
```
## 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는 요청 및 로그 스트림에 대한 세부 정보를 기록합니다.