Node.js 용 X-Ray AWS SDK를 사용하여 SDK 호출 추적하기

애플리케이션이 데이터를 저장하거나, 대기열에 기록하거나, 알림을 보내기 위해 를 호출하는 경우, Node.js X-Ray SDK는 호출을 하위 세그먼트로 다운스트림에서 추적합니다. AWS services 추적되고 AWS services해당 서비스 내에서 액세스하는 리소스 (예: Amazon S3 버킷 또는 Amazon SQS 대기열) 는 X-Ray 콘솔의 추적 맵에 다운스트림 노드로 표시됩니다.

V2 또는 V3를 통해 생성한 인스트루먼트 AWS SDK 클라이언트.AWS SDK for JavaScriptAWS SDK for JavaScript 각 AWS SDK 버전은 SDK 클라이언트를 AWS 계측하기 위한 다양한 방법을 제공합니다.

참고

현재 Node.js AWS X-Ray SDK는 AWS SDK for JavaScript V3 클라이언트를 계측할 때 V2 클라이언트를 계측하는 경우에 비해 더 적은 세그먼트 정보를 반환합니다. 예를 들어, DynamoDB에 대한 직접 호출을 나타내는 하위 세그먼트는 테이블 이름을 반환하지 않습니다. 트레이스에 이 세그먼트 정보가 필요한 경우 V2를 사용해 보세요. AWS SDK for JavaScript

AWS SDK for JavaScript V2

aws-sdkrequire 명령문을 호출에 포함시켜 모든 AWS SDK V2 클라이언트를 계측할 AWSXRay.captureAWS 수 있습니다.

예 app.js - AWS SDK 구성

const AWS = AWSXRay.captureAWS(require('aws-sdk'));

개별 클라이언트를 계측하려면 AWS SDK 클라이언트를 호출로 래핑하십시오. AWSXRay.captureAWSClient 예를 들어, AmazonDynamoDB 클라이언트를 구성하려면

예 app.js - DynamoDB 클라이언트 계측

    const AWSXRay = require('aws-xray-sdk');
...
    const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());

주의

captureAWS 및 captureAWSClient를 함께 사용하지 마십시오. 이렇게 하면 하위 세그먼트가 중복됩니다.

ECMAScript 모듈 (ESM) TypeScript과 함께 사용하여 JavaScript 코드를 로드하려면 다음 예제를 사용하여 라이브러리를 가져오십시오.

예 app.js - SDK 인스트루멘테이션 AWS

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

ESM으로 모든 AWS 클라이언트를 계측하려면 다음 코드를 사용하십시오.

예 app.js - AWS SDK 인스트루멘테이션

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();

모든 서비스에 대해, X-Ray 콘솔에서 호출된 API의 이름을 볼 수 있습니다. 서비스 하위 집합에 대해서는 X-Ray SDK가 세그먼트에 정보를 추가하여 서비스 맵에서 추가 세분화를 제공합니다.

예를 들어 계측된 DynamoDB 클라이언트에서 직접 호출을 생성하는 경우 SDK가 특정 테이블을 대상으로 한 직접 호출에 대해 테이블 이름을 세그먼트에 추가합니다. 콘솔에서, 각 테이블이 개별 노드로 서비스 맵에 표시되고, 특정 테이블을 대상으로 하지 않은 호출에 대해 일반 DynamoDB 노드가 표시됩니다.

예 항목을 저장하기 위한 DynamoDB 직접 호출에 대한 하위 세그먼트

{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}

명명된 리소스에 액세스할 때 다음 서비스를 호출할 경우 서비스 맵에 추가 노드가 생성됩니다. 특정 리소스를 대상으로 하지 않는 경우 서비스를 직접 호출하면 해당 서비스에 대한 일반 노드가 생성됩니다.

• Amazon DynamoDB – 테이블 이름

• Amazon Simple Storage Service –버킷 및 키 이름

• Amazon Simple Queue Service – 대기열 이름

AWS SDK for JavaScript V3

AWS SDK for JavaScript V3는 모듈식이므로 코드가 필요한 모듈만 로드합니다. 이 때문에 V3에서는 이 메서드를 지원하지 않으므로 모든 AWS SDK 클라이언트를 계측할 수는 없습니다. captureAWS

ECMAScript 모듈 (ESM) TypeScript 과 함께 사용하여 JavaScript 코드를 로드하려는 경우 다음 예제를 사용하여 라이브러리를 가져올 수 있습니다.

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

메서드를 AWS 사용하여 각 SDK 클라이언트를 계측합니다. AWSXRay.captureAWSv3Client 예를 들어, AmazonDynamoDB 클라이언트를 구성하려면

예 app.js - Javascript V3용 SDK를 사용한 DynamoDB 클라이언트 계측

    const AWSXRay = require('aws-xray-sdk');
    const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
    const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));

AWS SDK for JavaScript V3를 사용하는 경우 테이블 이름, 버킷 및 키 이름 또는 대기열 이름과 같은 메타데이터가 현재 반환되지 않으므로 V2를 사용하여 AWS SDK 클라이언트를 계측할 때처럼 추적 맵에 각 명명된 리소스에 대한 개별 노드가 포함되지 않습니다. AWS SDK for JavaScript

예 V3를 사용할 때 DynamoDB를 호출하여 항목을 저장하기 위한 서브세그먼트 AWS SDK for JavaScript

{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}