AWS Node.js SDK 용 X-Ray

X-Ray SDK for Node.js 는 Express 웹 애플리케이션 및 Node.js Lambda 함수용 라이브러리로, 추적 데이터를 생성하고 X-Ray 데몬으로 전송하기 위한 클래스와 메서드를 제공합니다. 추적 데이터에는 애플리케이션이 제공하는 수신 HTTP 요청 및 애플리케이션이 또는 클라이언트를 사용하여 다운스트림 서비스에 보내는 호출에 대한 정보가 포함됩니다. AWS SDK HTTP

참고

X-Ray SDK for Node.js 는 Node.js 버전 14.x 이상에서 지원되는 오픈 소스 프로젝트입니다. github.com/aws/ 에서 프로젝트를 팔로우하고 이슈와 풀 리퀘스트를 제출할 수 있습니다 GitHub. aws-xray-sdk-node

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

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

참고

Lambda에서 SDK X-Ray는 선택 사항입니다. 이를 함수에 사용하지 않는 경우 여전히 서비스 맵에 Lambda 서비스용 노드와 각 Lambda 함수용 노트 하나가 포함됩니다. 를 SDK 추가하면 Lambda가 기록한 함수 세그먼트에 하위 세그먼트를 추가하도록 함수 코드를 계측할 수 있습니다. 자세한 내용은 AWS Lambda 그리고 AWS X-Ray 섹션을 참조하세요.

다음으로, Node.js SDK 용 X-Ray를 사용하여 Node.js AWS SDK 클라이언트용으로 JavaScript 측정하십시오. 인스트루먼트된 클라이언트를 사용하여 다운스트림 AWS 서비스 또는 리소스에 전화를 걸 때마다 통화에 대한 정보가 하위 세그먼트에 SDK 기록됩니다. AWS 서비스 또한 서비스 내에서 액세스하는 리소스는 추적 맵에 다운스트림 노드로 나타나므로 개별 연결의 오류 및 제한 문제를 식별하는 데 도움이 됩니다.

또한 Node.js SDK 용 X-Ray는 HTTP 웹에 대한 다운스트림 호출 APIs 및 SQL 쿼리를 위한 도구를 제공합니다. SDK의 캡처 메서드로 HTTP 클라이언트를 감싸서 발신 HTTP 전화에 대한 정보를 기록하십시오. SQL클라이언트의 경우 데이터베이스 유형에 맞는 캡처 방법을 사용하십시오.

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

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

주석 및 메타데이터

주석과 메타데이터는 X-Ray를 사용하여 세그먼트에 추가하는 임의의 텍스트입니다. SDK 주석은 필터 표현식에서 사용하기 위해 인덱싱됩니다. 메타데이터는 인덱싱되지 않지만 X-Ray 콘솔 또는 API 를 사용하여 원시 세그먼트에서 볼 수 있습니다. X-Ray에 대한 읽기 액세스가 부여된 사용자는 누구나 이 데이터를 볼 수 있습니다.

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

SDK의 클래스와 메서드에 대한 참조 설명서는 AWS X-Ray SDKfor Node.js API Reference를 참조하십시오.

요구 사항

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

• atomic-batcher – 1.0.2

• cls-hooked – 4.2.2

• pkginfo – 0.4.0

• semver – 5.3.0

를 SDK 사용하여 설치하면 이러한 라이브러리가 함께 NPM 제공됩니다.

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

• aws-sdk – 2.7.15

종속성 관리

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

• 패키지 – aws-xray-sdk

로컬 개발의 SDK 경우 npm을 사용하여 프로젝트 디렉토리에 를 설치하십시오.

~/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

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

Node.js 샘플

AWS X-Ray SDKfor Node.js 를 사용하면 Node.js 애플리케이션을 통해 전달되는 요청을 end-to-end 확인할 수 있습니다.

• Node.js 샘플 애플리케이션이 켜져 GitHub 있습니다.