AWS Lambda에서 Node.js 코드 계측(Instrumenting)

Lambda는 AWS X-Ray와 통합되어 Lambda 애플리케이션을 추적(trace), 디버그, 최적화할 수 있게 도와줘요. X-Ray를 사용하면 애플리케이션의 리소스(Lambda 함수와 다른 AWS 서비스 포함)를 가로지르는 요청을 추적할 수 있죠.

X-Ray로 추적 데이터를 보내려면 다음 두 가지 SDK 라이브러리 중 하나를 사용하면 돼요:

AWS Distro for OpenTelemetry (ADOT) – OpenTelemetry(OTel) SDK의 안전하고 프로덕션에 적합하며 AWS에서 지원하는 배포판이에요.
AWS X-Ray SDK for Node.js – 추적 데이터를 생성해 X-Ray로 보내는 SDK예요.

두 SDK 모두 텔레메트리 데이터를 X-Ray 서비스로 보내는 방법을 제공해요. 그러면 X-Ray로 애플리케이션의 성능 지표를 보고, 필터링하고, 인사이트를 얻어 문제와 최적화 기회를 찾을 수 있습니다.

중요
X-Ray와 Powertools for AWS Lambda SDK는 AWS가 제공하는 긴밀하게 통합된 계측 솔루션의 일부예요. ADOT Lambda 레이어(layer)는 업계 표준 추적 계측 방식으로, 일반적으로 더 많은 데이터를 수집하지만 모든 사용 사례에 적합하진 않을 수 있어요. 두 솔루션 중 하나로 X-Ray에서 종단 간 추적(end-to-end tracing)을 구현할 수 있어요. 어떤 걸 고를지 알아보려면 AWS Distro for OpenTelemetry와 X-Ray SDK 중 선택을 참고하세요.

Topics(주제)

ADOT로 Node.js 함수 계측
X-Ray SDK로 Node.js 함수 계측
Lambda 콘솔로 추적 활성화
Lambda API로 추적 활성화
CloudFormation으로 추적 활성화
X-Ray 추적 해석
레이어(layer)에 런타임 의존성 저장 (X-Ray SDK)

출처: AWS Lambda 개발자 안내서

본문

ADOT로 Node.js 함수 계측

ADOT는 OTel SDK로 텔레메트리 데이터를 수집하는 데 필요한 모든 것을 패키징한 완전 관리형 Lambda 레이어를 제공해요. 이 레이어를 사용하면 함수 코드를 전혀 수정하지 않고도 Lambda 함수를 계측할 수 있죠. 또한 레이어를 구성해 OTel의 커스텀 초기화를 할 수도 있어요. 자세한 내용은 ADOT 문서의 Lambda에서 ADOT Collector 커스텀 구성을 참고하세요.

Node.js 런타임에서는 ADOT Javascript용 AWS 관리형 Lambda 레이어를 추가해 함수를 자동으로 계측할 수 있어요. 이 레이어를 추가하는 자세한 방법은 ADOT 문서의 JavaScript용 AWS Distro for OpenTelemetry Lambda 지원을 참고하세요.

X-Ray SDK로 Node.js 함수 계측

Lambda 함수가 애플리케이션의 다른 리소스에 호출하는 상세 정보를 기록하려면 AWS X-Ray SDK for Node.js를 사용할 수도 있어요. SDK를 얻으려면 aws-xray-sdk-core 패키지를 애플리케이션의 의존성에 추가하세요.

예제 blank-nodejs/package.json

{
  "name": "blank-nodejs",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "jest": "29.7.0"
  },
  "dependencies": {
    "@aws-sdk/client-lambda": "3.345.0",
    "aws-xray-sdk-core": "3.5.3"
  },
  "scripts": {
    "test": "jest"
  }
}

AWS SDK for JavaScript v3의 AWS SDK 클라이언트를 계측하려면 captureAWSv3Client 메서드로 클라이언트 인스턴스를 감싸세요.

예제 blank-nodejs/function/index.js – AWS SDK 클라이언트 추적

const AWSXRay = require('aws-xray-sdk-core');
const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda');

// Create client outside of handler to reuse
const lambda = AWSXRay.captureAWSv3Client(new LambdaClient());

// Handler
exports.handler = async function(event, context) {
    event.Records.forEach(record => {
  ...

Lambda 런타임은 X-Ray SDK를 구성하기 위해 몇 가지 환경 변수를 설정해요. 예를 들어 Lambda는 AWS_XRAY_CONTEXT_MISSING을 LOG_ERROR로 설정해서 X-Ray SDK가 런타임 오류를 던지지 않게 해요. 커스텀 컨텍스트 미싱 전략(context missing strategy)을 설정하려면 함수 구성에서 이 환경 변수를 값 없이 재정의한 뒤, 컨텍스트 미싱 전략을 프로그래밍 방식으로 설정하면 됩니다.

예제 초기화 코드

const AWSXRay = require('aws-xray-sdk-core');

// Configure the context missing strategy to do nothing
AWSXRay.setContextMissingStrategy(() => {});

자세한 내용은 Lambda 환경 변수 작업을 참고하세요.

올바른 의존성을 추가하고 필요한 코드 변경을 마친 뒤, Lambda 콘솔 또는 API를 통해 함수 구성에서 추적을 활성화하세요.

Lambda 콘솔로 추적 활성화

콘솔에서 Lambda 함수의 활성 추적(active tracing)을 켜려면 다음 단계를 따르세요.

활성 추적 켜기

Lambda 콘솔의 함수 페이지를 엽니다.
함수를 선택합니다.
Configuration(구성)을 선택한 다음 Monitoring and operations tools(모니터링 및 운영 도구)를 선택합니다.
Additional monitoring tools(추가 모니터링 도구)에서 Edit(편집)을 선택합니다.
CloudWatch Application Signals and AWS X-Ray 아래에서 Lambda service traces에 대해 Enable(활성화)을 선택합니다.
Save(저장)를 선택합니다.

Lambda API로 추적 활성화

AWS CLI 또는 AWS SDK로 Lambda 함수에서 추적을 구성하려면 다음 API 작업을 사용하세요:

다음 예제 AWS CLI 명령은 my-function이라는 함수의 활성 추적을 활성화해요.

aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active

추적 모드는 함수 버전을 게시할 때 버전별 구성(version-specific configuration)의 일부가 돼요. 게시된 버전에서는 추적 모드를 변경할 수 없습니다.

CloudFormation으로 추적 활성화

CloudFormation 템플릿에서 AWS::Lambda::Function 리소스의 추적을 활성화하려면 TracingConfig 속성을 사용하세요.

예제 function-inline.yml – 추적 구성

Resources:
  function:
    Type: [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html)
    Properties:
      TracingConfig:
        Mode: Active
      ...

AWS Serverless Application Model(AWS SAM) AWS::Serverless::Function 리소스에는 Tracing 속성을 사용하세요.

예제 template.yml – 추적 구성

Resources:
  function:
    Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)
    Properties:
      Tracing: Active
      ...

X-Ray 추적 해석

함수는 추적 데이터를 X-Ray에 업로드할 권한이 필요해요. Lambda 콘솔에서 추적을 활성화하면 Lambda가 함수의 실행 역할에 필요한 권한을 추가해요. 그렇지 않으면 실행 역할에 AWSXRayDaemonWriteAccess 정책을 추가하세요.

활성 추적을 구성한 뒤에는 애플리케이션을 통과하는 특정 요청을 관찰할 수 있어요. X-Ray 서비스 그래프는 애플리케이션과 모든 구성 요소에 대한 정보를 보여줘요. 다음 예제는 함수 두 개가 있는 애플리케이션을 보여줍니다. 기본 함수는 이벤트를 처리하고 가끔 오류를 반환해요. 맨 위의 두 번째 함수는 첫 번째 함수의 로그 그룹에 나타난 오류를 처리하며, AWS SDK를 사용해 X-Ray, Amazon Simple Storage Service(Amazon S3), Amazon CloudWatch Logs를 호출합니다.

두 개의 개별 애플리케이션과 각각의 X-Ray 서비스 맵을 보여주는 다이어그램

X-Ray는 애플리케이션에 대한 모든 요청을 추적하진 않아요. X-Ray는 추적이 효율적이면서도 모든 요청의 대표적인 샘플을 제공하도록 샘플링 알고리즘을 적용해요. 샘플링 비율은 초당 1개 요청과 추가 요청의 5%예요. 함수의 X-Ray 샘플링 비율은 구성할 수 없습니다.

X-Ray에서 trace(추적)는 하나 이상의 service(서비스)가 처리하는 요청에 대한 정보를 기록해요. Lambda는 추적마다 2개의 세그먼트를 기록해서 서비스 그래프에 두 개의 노드를 만들어요. 다음 이미지는 이 두 노드를 강조합니다:

단일 함수가 있는 X-Ray 서비스 맵.

왼쪽의 첫 번째 노드는 호출 요청을 받는 Lambda 서비스를 나타내요. 두 번째 노드는 여러분의 특정 Lambda 함수를 나타냅니다. 다음 예제는 이 두 세그먼트가 있는 추적을 보여줘요. 둘 다 my-function이라는 이름이지만, 하나는 origin이 AWS::Lambda이고 다른 하나는 origin이 AWS::Lambda::Function이에요. AWS::Lambda 세그먼트에 오류가 표시되면 Lambda 서비스에 문제가 있는 것이고, AWS::Lambda::Function 세그먼트에 오류가 표시되면 여러분의 함수에 문제가 있는 거예요.

특정 Lambda 호출의 각 하위 세그먼트별 지연 시간을 보여주는 X-Ray 추적.

이 예제는 AWS::Lambda::Function 세그먼트를 펼쳐서 세 개의 하위 세그먼트를 보여줍니다.

참고
AWS는 현재 Lambda 서비스에 변경 사항을 구현하고 있어요. 이 변경으로 인해 AWS 계정의 서로 다른 Lambda 함수가 내보내는 시스템 로그 메시지와 추적 세그먼트의 구조 및 내용에 약간의 차이가 있을 수 있습니다.
여기 표시된 예제 추적은 이전 스타일의 함수 세그먼트를 보여줘요. 이전/새 스타일 세그먼트의 차이는 다음 단락에 설명되어 있죠.
이 변경은 향후 몇 주에 걸쳐 구현되며, 중국 및 GovCloud 리전을 제외한 모든 AWS 리전의 모든 함수가 새 형식의 로그 메시지와 추적 세그먼트로 전환될 예정입니다.

이전 스타일 함수 세그먼트에는 다음 하위 세그먼트가 포함돼요:

Initialization(초기화) – 함수를 로드하고 초기화 코드를 실행하는 데 걸린 시간을 나타내요. 이 하위 세그먼트는 함수 인스턴스 각각이 처리하는 첫 번째 이벤트에만 나타나요.
Invocation(호출) – 핸들러 코드를 실행하는 데 걸린 시간을 나타내요.
Overhead(오버헤드) – Lambda 런타임이 다음 이벤트를 처리할 준비를 하는 데 쓰는 시간을 나타내요.

새 스타일 함수 세그먼트에는 Invocation 하위 세그먼트가 없어요. 대신 고객 하위 세그먼트가 함수 세그먼트에 직접 연결되죠. 이전/새 스타일 함수 세그먼트의 구조에 대해 더 알아보려면 X-Ray 추적 이해를 참고하세요.

HTTP 클라이언트를 계측하고, SQL 쿼리를 기록하고, 주석(annotation)과 메타데이터로 커스텀 하위 세그먼트를 만들 수도 있어요. 자세한 내용은 AWS X-Ray 개발자 안내서의 AWS X-Ray SDK for Node.js를 참고하세요.

요금
AWS Free Tier의 일부로 매월 일정 한도까지 X-Ray 추적을 무료로 사용할 수 있어요. 그 임계값을 넘으면 X-Ray는 추적 저장과 검색에 요금을 부과해요. 자세한 내용은 AWS X-Ray 요금을 참고하세요.

레이어(layer)에 런타임 의존성 저장 (X-Ray SDK)

X-Ray SDK로 함수 코드의 AWS SDK 클라이언트를 계측하면 배포 패키지가 꽤 커질 수 있어요. 함수 코드를 업데이트할 때마다 런타임 의존성을 다시 업로드하지 않으려면 X-Ray SDK를 Lambda 레이어에 패키징하세요.

다음 예제는 AWS X-Ray SDK for Node.js를 저장하는 AWS::Serverless::LayerVersion 리소스를 보여줘요.

예제 template.yml – 의존성 레이어

Resources:
  function:
    Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)
    Properties:
      CodeUri: function/.
      Tracing: Active
      Layers:
        - !Ref libs
      ...
  libs:
    Type: [AWS::Serverless::LayerVersion](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-layerversion.html)
    Properties:
      LayerName: blank-nodejs-lib
      Description: Dependencies for the blank sample app.
      ContentUri: lib/.
      CompatibleRuntimes:
        - nodejs24.x

이 구성에서는 런타임 의존성을 변경할 때만 라이브러리 레이어를 업데이트하면 돼요. 함수 배포 패키지에 코드만 담기므로 업로드 시간을 줄이는 데 도움이 됩니다.

의존성용 레이어를 만들려면 배포 전에 레이어 아카이브를 생성하는 빌드 변경이 필요해요. 작동하는 예제는 blank-nodejs 샘플 애플리케이션을 참고하세요.

더 알아보기 (Learn more)

ADOT·X-Ray SDK 계측, 콘솔·API·CloudFormation 활성화, 추적 해석, 의존성 레이어까지 Node.js 트레이싱의 전체 흐름을 다뤄 보세요.