기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Node.js용 AWS X-Ray SDK

Node.js용 X-Ray SDK는 트레이스 데이터를 생성하고 X-Ray 대몬(daemon)에 보내기 위한 클래스 및 메서드를 제공하는 Express 웹 애플리케이션 및 Node.js Lambda 함수용 라이브러리입니다. 트레이스 데이터는 애플리케이션에서 처리하는 수신 HTTP 요청과 애플리케이션이 AWS SDK 또는 HTTP 클라이언트를 사용하여 다운스트림 서비스에 하는 호출에 대한 정보를 포함합니다.

Express를 사용한다면, 애플리케이션 서버에서 SDK를 미들웨어로 추가하여 수신 요청 트레이스를 시작합니다. 미들웨어는 각 트레이스 요청에 대한 세그먼트를 생성하고, 응답이 전송되면 세그먼트를 완료합니다. 세그먼트가 열려 있는 동안에는 SDK 클라이언트의 메서드를 이용해 정보를 세그먼트에 추가하고 하위 세그먼트를 만들어 다운스트림 호출을 트레이스할 수 있습니다. 또한 SDK는 세그먼트가 열려 있는 동안 애플리케이션에서 발생하는 예외를 자동으로 기록합니다.

계측되는 애플리케이션 또는 서비스에 의해 호출되는 Lambda 함수의 경우, Lambda는 추적 헤더를 읽고 샘플링된 요청을 자동으로 추적합니다. 그 밖의 함수의 경우 수신 요청을 샘플링 및 추적하도록 Lambda를 구성합니다. 어느 경우든, Lambda는 세그먼트를 생성하여 X-Ray SDK에 제공합니다.

그런 다음, Node.js 용 X-Ray SDK를 사용하여 Node.js 클라이언트에서 JavaScript 용 AWS SDK를 계측합니다. 계측된 클라이언트로 다운스트림 AWS 서비스나 리소스를 직접 호출할 때마다, SDK는 하위 세그먼트에 직접 호출 정보를 기록합니다. 서비스에서 액세스하는 AWS 서비스와 리소스는 트레이스 맵에 다운스트림 노드로 표시되기 때문에 개별 연결의 오류와 제한 문제를 쉽게 확인할 수 있습니다.

또한 Node.js용 X-Ray SDK는 HTTP 웹 API 및 SQL 쿼리에 대한 다운스트림 호출의 계측도 제공합니다. HTTP 클라이언트를 SDK의 캡처 메서드에 래핑해 발신 HTTP 호출에 대한 정보를 기록합니다. SQL 클라이언트의 경우 데이터베이스 유형에 맞는 캡처 메서드를 사용하십시오.

미들웨어는 샘플링 규칙을 수신 요청에 적용해 트레이스할 요청을 결정합니다. Node.js용 X-Ray SDK를 구성하여 샘플링 동작을 수정하거나 애플리케이션이 실행하는 AWS 컴퓨팅 리소스에 대한 정보를 기록할 수 있습니다.

요청에 대한 추가 정보와 애플리케이션이 주석 및 메타데이터에서 하는 작업을 기록합니다. 주석은 필터 표현식과 함께 사용할 수 있도록 인덱싱된 단순한 키 값 쌍이기 때문에, 특정 데이터를 포함한 트레이스를 검색할 수 있습니다. 메타데이터 항목은 제한이 적으며 JSON으로 직렬화할 수 있는 모든 객체와 어레이를 기록할 수 있습니다.

코드에 구성된 클라이언트가 많이 있다면, 구성된 클라이언트로 만든 각 요청의 하위 세그먼트를 대량으로 보관하는 요청 세그먼트 하나를 만들 수 있습니다. 사용자 지정 하위 세그먼트의 클라이언트 호출을 래핑해 하위 세그먼트를 조직하고 그룹화할 수 있습니다. 전체 함수나 특정 코드 부분에 대한 사용자 지정 하위 세그먼트를 만들고, 상위 세그먼트에 모든 것을 적는 대신 하위 세그먼트에 메타데이터와 주석을 기록할 수 있습니다.

SDK의 클래스 및 메서드에 대한 레퍼런스 문서는 Node.js용 AWS X-Ray X-Ray SDK API Reference를 참조하십시오.

요구 사항

Node.js용 X-Ray SDK는 Node.js 및 다음 라이브러리가 필요합니다.

SDK는 사용자가 NPM으로 설치할 때 이 라이브러리를 가져옵니다.

AWS SDK 클라이언트를 추적하려면 Node.js용 X-Ray SDK에 Node.js의 JavaScript용 AWS SDK 최소 버전이 필요합니다.

종속성 관리

Node.js용 X-Ray SDK는 NPM에서 사용할 수 있습니다.

로컬 개발의 경우에는 NPM으로 SDK를 프로젝트 디렉터리에 설치합니다.

~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
  ├─┬ aws-xray-sdk-core@3.3.3
  │ ├── @aws-sdk/service-error-classification@3.15.0
  │ ├── @aws-sdk/types@3.15.0
  │ ├─┬ @types/cls-hooked@4.3.3
  │ │ └── @types/node@15.3.0
  │ ├── atomic-batcher@1.0.2
  │ ├─┬ cls-hooked@4.2.2
  │ │ ├─┬ async-hook-jl@1.7.6
  │ │ │ └── stack-chain@1.3.7
  │ │ └─┬ emitter-listener@1.1.2
  │ │   └── shimmer@1.2.1
  │ └── semver@5.7.1
  ├── aws-xray-sdk-express@3.3.3
  ├── aws-xray-sdk-mysql@3.3.3
  └── aws-xray-sdk-postgres@3.3.3

--save 옵션을 사용해 SDK를 애플리케이션의 package.json에 종속성으로 저장합니다.

~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3

애플리케이션에 X-Ray SDK의 종속성과 충돌하는 버전이 있는 종속성이 있는 경우, 호환성을 보장하기 위해 두 버전이 모두 설치됩니다. 자세한 내용은 종속성 해결에 대한 공식 NPM 문서를 참조하십시오.

Node.js 샘플

Node.js용 AWS X-Ray SDK를 사용하면 요청이 Node.js 애플리케이션을 통해 이동할 때 요청을 전체적으로 확인할 수 있습니다.