AWS Node.js 전용 X-Ray SDK - AWS X-Ray
요구 사항종속성 관리Node.js 샘플구성수신 요청발신 HTTP 호출SQL 쿼리사용자 지정 하위 세그먼트주석 및 메타데이터

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

AWS Node.js 전용 X-Ray SDK

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

참고

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

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

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

참고

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

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

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

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

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

주석 및 메타데이터

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

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

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

요구 사항

Node.js용 X-Ray SDK는 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 용 X-Ray SDK를 사용하려면 Node.js 형식의 최소 AWS SDK 버전이 필요합니다. JavaScript

  • aws-sdk – 2.7.15

종속성 관리

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 애플리케이션을 통해 전달되는 end-to-end 요청을 파악할 수 있습니다.

Node.js용 X-Ray SDK 구성

애플리케이션이 실행되는 서비스에 대한 정보를 포함하거나, 기본 샘플링 동작을 수정하거나 요청에 적용되는 샘플링 규칙을 특정 경로에 추가하도록 플러그인을 사용하여 Node.js용 X-Ray SDK를 구성할 수 있습니다.

서비스 플러그인

plugins을 사용하여 애플리케이션을 호스팅하는 서비스에 대한 정보를 기록할 수 있습니다.

플러그인

  • Amazon EC2 — 인스턴스 ID, 가용 영역 및 CloudWatch 로그 그룹을 EC2Plugin 추가합니다.

  • Elastic Beanstalk – ElasticBeanstalkPlugin이 환경 이름, 버전 레이블 및 배포 ID를 추가합니다.

  • Amazon ECS — ECSPlugin이 컨테이너 ID를 추가합니다.

플러그인을 사용하려면 config 메서드를 사용하여 Node.js용 X-Ray SDK 클라이언트를 구성합니다.

예 app.js - 플러그인
var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);

SDK는 플러그인 설정을 사용하여 세그먼트에 origin 필드를 설정하기도 합니다. 이는 애플리케이션을 실행하는 AWS 리소스 유형을 나타냅니다. 여러 플러그인을 사용하는 경우 SDK는 ElasticBeanstalk > EKS > ECS > EC2와 같은 해결 순서를 사용하여 출처를 결정합니다.

샘플링 규칙

SDK는 X-Ray 콘솔에서 정의하는 샘플링 규칙을 사용하여 기록할 요청을 결정합니다. 기본 규칙은 매초 첫 번째 요청을 추적하고, 모든 서비스에서 추가 요청의 5%를 X-Ray로 추적 전송합니다. X-Ray 콘솔에서 추가 규칙을 생성하여 각 애플리케이션에 대해 기록되는 데이터의 양을 사용자 지정합니다.

SDK는 사용자 지정 규칙을 정의된 순서대로 적용합니다. 요청이 여러 사용자 지정 규칙과 일치하는 경우 SDK는 첫 번째 규칙만 적용합니다.

참고

SDK가 샘플링 규칙을 가져오기 위해 X-Ray에 연결할 수 없는 경우, 매초 첫 번째 요청과 호스트당 추가 요청의 5%에 대한 기본 로컬 규칙으로 되돌아갑니다. 호스트가 샘플링 API를 직접 호출할 수 있는 권한이 없거나, X-Ray 대몬(daemon)에 연결할 수 없을 경우 이러한 상황이 발생할 수 있고 이 대몬(daemon)은 SDK에서 수행한 API 직접 호출에 대한 TCP 프록시 역할을 합니다.

JSON 문서에서 샘플링 규칙을 불러오도록 SDK를 구성할 수도 있습니다. SDK는 X-Ray 샘플링을 사용할 수 없을 경우 로컬 규칙을 백업으로 사용하거나, 로컬 규칙을 전용으로 사용할 수 있습니다.

예 sampling-rules.json
{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

이 예에서는 하나의 사용자 지정 규칙과 기본 규칙을 정의합니다. 사용자 지정 규칙은 최소 추적 요청 수 없이 5% 샘플링 비율을 /api/move/ 아래 경로에 적용합니다. 기본 규칙은 매초 최초 요청과 추가 요청의 10%를 추적합니다.

로컬로 규칙의 정의할 때의 단점은 고정 대상이 X-Ray 서비스를 통해 관리되는 대신, 레코더의 각 인스턴스별로 독립적으로 적용된다는 것입니다. 호스트를 많이 배포할수록 고정 속도가 크게 증대하기 때문에 기록되는 데이터의 양을 제어하기가 어려워집니다.

아니요 AWS Lambda, 샘플링 속도는 수정할 수 없습니다. 구성된 서비스가 함수를 호출하는 경우 해당 서비스에서 샘플링한 요청을 생성한 호출이 Lambda에 의해 기록됩니다. 활성 추적이 활성화되고 트레이스 헤더가 없는 경우 Lambda에서 샘플링 결정을 내립니다.

백업 규칙을 구성하려면 setSamplingRules를 사용하여 파일에서 샘플링 규칙을 로드하도록 Node.js용 X-Ray SDK에 지정합니다.

예 app.js - 파일의 샘플링 규칙
var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');

또한 코드에서 규칙을 정의하여 객체로 setSamplingRules에 전달할 수도 있습니다.

예 app.js - 객체의 샘플링 규칙
var AWSXRay = require('aws-xray-sdk');
var rules = {
  "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
  "default": { "fixed_target": 1, "rate": 0.1 },
  "version": 1
  }

AWSXRay.middleware.setSamplingRules(rules);

로컬 규칙만 사용하려면 disableCentralizedSampling를 호출합니다.

AWSXRay.middleware.disableCentralizedSampling()

로깅

SDK의 출력을 기록하려면 AWSXRay.setLogger(logger)를 호출합니다. 여기서 logger는 표준 로깅 메서드(warn, info 등)를 제공하는 객체입니다.

기본적으로 SDK는 콘솔 객체의 표준 메서드를 사용하여 콘솔에 오류 메시지를 기록합니다. 내장 로거의 로그 수준은 AWS_XRAY_DEBUG_MODE 또는 AWS_XRAY_LOG_LEVEL 환경 변수를 사용하여 설정할 수 있습니다. 유효한 로그 수준 값 목록은 환경 변수를 참조하십시오.

로그에 다른 형식이나 대상을 제공하려는 경우 아래와 같이 로거 인터페이스의 자체 구현을 SDK에 제공할 수 있습니다. 이 인터페이스를 구현하는 모든 객체를 사용할 수 있습니다. 즉, Winston과 같은 다양한 로깅 라이브러리를 사용하여 SDK에 직접 전달할 수 있습니다.

예 app.js – 로깅
var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);

다른 구성 메서드를 실행하기 전에 setLogger를 호출하여 해당 작업의 출력을 캡처하도록 합니다.

X-Ray 대몬(daemon) 주소

X-Ray 대몬(daemon)이 127.0.0.1:2000 이외의 다른 포트 또는 호스트를 수신 대기하는 경우 추적 데이터를 다른 주소로 전송하도록 Node.js용 X-Ray SDK를 구성할 수 있습니다.

AWSXRay.setDaemonAddress('host:port');

호스트를 이름 또는 IPv4 주소로 지정할 수 있습니다.

예 app.js - 데몬 주소
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');

다른 포트에서 TCP와 UDP를 수신 대기하도록 데몬을 구성한 경우 데몬 주소 설정에서 둘 다 지정할 수 있습니다.

예 app.js - 개별 포트의 데몬 주소
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');

AWS_XRAY_DAEMON_ADDRESS 환경 변수를 사용하여 데몬 주소를 설정할 수도 있습니다.

환경 변수

환경 변수를 사용하여 Node.js용 X-Ray SDK를 구성할 수 있습니다. SDK는 다음 변수를 지원합니다.

  • AWS_XRAY_CONTEXT_MISSING – 열려 있는 세그먼트가 없는 경우 구성된 구성된 코드가 데이터를 기록하려고 할 때 발생하는 예외를 방지하려면 RUNTIME_ERROR로 설정합니다.

    유효한 값

    • RUNTIME_ERROR— 런타임 예외가 발생합니다.

    • LOG_ERROR – 오류를 기록하고 계속합니다 (기본값).

    • IGNORE_ERROR— 오류를 무시하고 계속합니다.

    열린 요청이 없을 때 실행되는 시작 코드 또는 새 스레드를 생성하는 코드에서 계측된 클라이언트를 사용하려고 하는 경우 누락된 세그먼트 또는 하위 세그먼트와 관련된 오류가 발생할 수 있습니다.

  • AWS_XRAY_DAEMON_ADDRESS – X-Ray 대몬(daemon) 리스너의 호스트와 포트를 설정합니다. 기본적으로 SDK는 추적 데이터(UDP)와 샘플링(TCP) 모두에 127.0.0.1:2000을 사용합니다. 다른 포트에서 수신 대기하도록 대몬(daemon)을 구성한 경우 또는 다른 호스트에서 실행 중인 경우 이 변수를 사용합니다.

    형식

    • 동일한 포트 – address:port

    • 다른 포트 – tcp:address:port udp:address:port

  • AWS_XRAY_DEBUG_MODE – debug 수준에서 로그를 콘솔에 출력하도록 SDK를 구성하려면 TRUE로 설정합니다.

  • AWS_XRAY_LOG_LEVEL – 기본 로거의 로그 수준을 설정합니다. 유효한 값은 debug, info, warn, error 및 silent입니다. AWS_XRAY_DEBUG_MODE가 TRUE로 설정된 경우 이 값은 무시됩니다.

  • AWS_XRAY_TRACING_NAME – SDK가 세그먼트에 사용할 서비스 이름을 설정합니다. Express 미들웨어에 설정한 세그먼트 이름을 재정의합니다.

Node.js용 X-Ray SDK로 수신 요청 추적하기

Node.js 용 X-Ray SDK를 사용하여 Express 및 Restify 애플리케이션이 Amazon EC2 또는 Amazon ECS의 EC2 인스턴스에서 제공하는 수신 HTTP 요청을 추적할 수 있습니다. AWS Elastic Beanstalk

Node.js용 X-Ray SDK는 Express 및 Restify 프레임워크를 사용하는 애플리케이션을 위한 미들웨어를 제공합니다. 애플리케이션에 X-Ray 미들웨어를 추가하면 Node.js용 X-Ray SDK가 샘플링된 각 요청에 대해 세그먼트를 생성합니다. 이 세그먼트에는 HTTP 요청의 시간, 메서드 및 배치가 포함됩니다. 추가로 구성하면 이 세그먼트의 하위 세그먼트가 생성됩니다.

참고

AWS Lambda 함수의 경우 Lambda는 샘플링된 각 요청에 대해 세그먼트를 생성합니다. 자세한 정보는 AWS Lambda 그리고 AWS X-Ray을 참조하세요.

각 세그먼트에는 서비스 맵 안에서 애플리케이션을 식별하는 이름이 있습니다. 이 세그먼트의 이름이 정적으로 지정되도록 하거나, 수신 요청의 호스트 헤더를 기반으로 SDK가 동적으로 이름을 지정하도록 구성할 수 있습니다. 동적 이름 지정을 사용하면 요청의 도메인 이름에 따라 그룹을 추적하고 이름이 예상 패턴과 일치하지 않을 경우(예: 호스트 헤더가 위조된 경우) 기본 이름을 적용할 수 있습니다.

전달된 요청

로드 밸런서 또는 기타 중개자가 애플리케이션으로 요청을 전달하는 경우, X-Ray는 IP 패킷 내 소스 IP가 아니라 요청의 X-Forwarded-For 헤더로부터 클라이언트 IP를 가져옵니다. 전달된 요청에 대해 기록된 클라어언트 IP는 위조될 수 있으므로 신뢰하면 안 됩니다.

요청이 전달되면 SDK는 세그먼트에 추가 필드를 설정하여 이를 나타냅니다. 세그먼트에 x_forwarded_for로 설정된 true 필드가 포함된 경우 클라이언트 IP는 HTTP 요청의 X-Forwarded-For 헤더로부터 가져옵니다.

메시지 핸들러는 다음 정보를 포함하는 http 블록을 이용해 각 수신 요청에 대한 세그먼트를 생성합니다.

  • HTTP 메서드 – GET, POST, PUT, DELETE 등.

  • 클라이언트 주소 – 요청을 전송한 클라이언트의 IP 주소.

  • 응답 코드 – 완료된 요청의 HTTP 응답 코드.

  • 시간 – 시작 시간(요청 수신) 및 종료 시간(응답 전송).

  • 유저 에이전트 — 요청에서 가져온 user-agent입니다.

  • 콘텐츠 길이 — 응답의 content-length입니다.

Express를 사용하여 수신 요청 추적

Express 미들웨어를 사용하려면 SDK 클라이언트를 시작하고 express.openSegment 함수가 반환하는 미들웨어를 사용하여 경로를 정의합니다.

예 app.js - Express
var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());

경로를 정의한 후, express.closeSegment의 출력을 사용하여 Node.js용 X-Ray SDK가 반환한 오류를 모두 처리합니다.

Restify를 사용하여 수신 요청 추적

Restify 미들웨어를 사용하려면 SDK 클라이언트를 시작하고 enable을 실행합니다. Restify 서버 및 세그먼트 이름을 전달합니다.

예 app.js - Restify
var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');

var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));

server.get('/', function (req, res) {
  res.render('index');
});

세그먼트 이름 지정 전략 구성

AWS X-Ray 서비스 이름을 사용하여 애플리케이션을 식별하고 애플리케이션이 사용하는 다른 애플리케이션, 데이터베이스, 외부 API 및 AWS 리소스와 구별합니다. X-Ray SDK는 수신 요청에 대한 세그먼트를 생성할 때 해당 세그먼트의 이름 필드에 애플리케이션의 서비스 이름을 기록합니다.

X-Ray SDK는 HTTP 요청 헤더의 호스트 이름 뒤에 세그먼트를 지정할 수 있습니다. 그러나 이 헤더가 위조되면 서비스 맵에 예기치 않은 노드가 발생할 수 있습니다. 위조된 호스트 헤더가 포함된 요청으로 인해 SDK가 잘못된 세그먼트 이름을 지정하는 현상을 방지하려면 들어오는 요청의 기본 이름을 지정해야 합니다.

애플리케이션이 여러 도메인의 요청을 처리하는 경우, 동적 이름 지정 전략을 사용하여 이를 세그먼트 이름에 반영하도록 SDK를 구성할 수 있습니다. 동적 이름 지정 전략을 사용하면 SDK가 예상 패턴과 일치하는 요청에 호스트 이름을 사용하고, 그렇지 않은 요청에 기본 이름을 적용할 수 있습니다.

예를 들어, 하나의 애플리케이션이 세 개의 하위 도메인 (www.example.com, api.example.com, static.example.com) 에 요청을 전송할 수 있습니다. *.example.com 패턴으로 동적 이름 지정 전략을 사용하여 각 하위도메인의 세그먼트를 서로 다른 이름으로 표시하면 서비스 맵에 서비스 노드가 세 개 생깁니다. 이 패턴에 맞지 않는 호스트 이름의 요청이 애플리케이션에 수신되면, 사용자가 지정한 대체 이름의 네 번째 노드가 서비스 맵에 표시됩니다.

모든 요청 세그먼트에 같은 이름을 사용하려면, 이전 단원에 나온 것처럼 미들웨어를 초기화할 때 애플리케이션 이름을 지정하십시오.

참고

코드에 정의한 기본 서비스 이름을 AWS_XRAY_TRACING_NAME 환경 변수를 사용하여 재정의할 수 있습니다.

동적 이름 지정 전략은 호스트 이름이 일치해야 하는 패턴 및 HTTP 요청의 호스트 이름이 패턴과 일치하지 않는 경우 사용할 기본 이름을 정의합니다. 동적으로 세그먼트의 이름을 지정하려면 AWSXRay.middleware.enableDynamicNaming을 사용합니다.

예 app.js – 동적 세그먼트 이름

요청의 호스트 이름이 *.example.com 패턴과 일치하는 경우 호스트 이름을 사용합니다. 그렇지 않은 경우 MyApp을 사용합니다.

var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
AWSXRay.middleware.enableDynamicNaming('*.example.com');
        
app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());

Node.js용 X-Ray SDK를 사용하여 다운스트림 HTTP 웹 서비스에 대한 호출 추적하기

애플리케이션이 마이크로서비스 또는 공개 HTTP API를 호출할 때 Node.js용 X-Ray SDK 클라이언트를 사용하여 해당 호출을 계측하고 API를 다운스트림 서비스로 서비스 그래프에 추가할 수 있습니다.

http 또는 https 클라이언트를 Node.js용 X-Ray SDK의 captureHTTPs 메서드로 전달하여 발신 호출을 트레이스합니다.

참고

Axios 또는 Superagent 같은 타사 HTTP 요청 라이브러리를 사용하는 호출은 captureHTTPsGlobal() API를 통해 지원되며 네이티브 http 모듈을 사용할 때 추적됩니다.

예 app.js – HTTP 클라이언트
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));

모든 HTTP 클라이언트에서 추적을 활성화하려면 http를 로드하기 전에 captureHTTPsGlobal을 호출합니다.

예 app.js – HTTP 클라이언트(전역)
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');

다운스트림 웹 API에 대한 직접 호출을 계측할 때 Node.js용 X-Ray SDK가 HTTP 요청 및 응답에 대한 정보가 포함된 하위 세그먼트를 기록합니다. X-Ray는 하위 세그먼트를 사용하여 원격 API에 대해 추정된 세그먼트를 생성합니다.

예 다운스트림 HTTP 호출에 대한 하위 세그먼트
{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}
예 다운스트림 HTTP 호출에 대한 추정된 세그먼트
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}

Node.js용 X-Ray SDK로 SQL 쿼리 추적하기

SQL 클라이언트를 대응하는 Node.js용 X-Ray SDK 클라이언트 메서드로 감싸 SQL 데이터베이스 쿼리를 계측합니다.

  • PostgreSQL – AWSXRay.capturePostgres() 

    var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();

  • MySQL – AWSXRay.captureMySQL() 

    var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
...
var connection = mysql.createConnection(config);

구성된 클라이언트를 이용해 SQL 쿼리를 생성한다면, Node.js용 X-Ray SDK는 연결과 쿼리에 대한 정보를 하위 세그먼트에 기록합니다.

SQL 하위 세그먼트에 추가 데이터 포함

허용 목록에 있는 SQL 필드에 매핑된다면 SQL 쿼리에 대해 생성된 하위 세그먼트에 정보를 더 추가할 수 있습니다. 예를 들어 하위 세그먼트에 삭제된 SQL 쿼리 문자열을 기록하려는 경우 하위 세그먼트의 SQL 객체에 직접 추가할 수 있습니다.

예 하위 세그먼트에 SQL 지정
    const queryString = 'SELECT * FROM MyTable';
connection.query(queryString, ...);

// Retrieve the most recently created subsegment
const subs = AWSXRay.getSegment().subsegments;

if (subs & & subs.length > 0) {
  var sqlSub = subs[subs.length - 1];
  sqlSub.sql.sanitized_query = queryString;
}

허용 목록에 있는 SQL 필드의 전체 목록은 AWS X-Ray 개발자 안내서의 SQL 쿼리를 참조하십시오.

Node.js용 X-Ray SDK를 사용하여 사용자 지정 하위 세그먼트 생성하기

하위 세그먼트는 추적의 세그먼트를 확장하여 요청을 처리하기 위해 완료된 작업에 대한 세부 정보를 표시합니다. 계측되는 클라이언트에서 직접 호출할 때마다, X-Ray SDK는 하위 세그먼트 안에 생성된 정보를 기록합니다. 추가 하위 세그먼트를 생성하여 다른 하위 세그먼트를 그룹화하거나, 코드 섹션의 성능을 평가하거나, 주석 및 메타데이터를 기록할 수 있습니다.

사용자 지정 Express 하위 세그먼트

captureAsyncFunc 함수를 사용하여 다운스트림 서비스를 호출하는 기능에 대해 사용자 지정 하위 세그먼트를 생성할 수 있습니다.

예 app.js – 사용자 지정 하위 세그먼트 Express
var AWSXRay = require('aws-xray-sdk');

app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  var host = 'api.example.com';

  AWSXRay.captureAsyncFunc('send', function(subsegment) {
    sendRequest(host, function() {
      console.log('rendering!');
      res.render('index');
      subsegment.close();
    });
  });
});

app.use(AWSXRay.express.closeSegment());

function sendRequest(host, cb) {
  var options = {
    host: host,
    path: '/',
  };

  var callback = function(response) {
    var str = '';

    response.on('data', function (chunk) {
      str += chunk;
    });

    response.on('end', function () {
      cb();
    });
  }

  http.request(options, callback).end();
};

이 예제에서 애플리케이션은 sendRequest 함수를 호출하기 위해 send라는 사용자 지정 하위 세그먼트를 생성합니다. captureAsyncFunc는 콜백 함수가 생성하는 비동기 호출이 완료되면 해당 콜백 함수 내에서 닫아야 하는 하위 세그먼트를 전달합니다.

동기식 기능에 대해서는 captureFunc 함수를 사용할 수 있습니다. 이 함수는 함수 블록이 실행을 마치는 즉시 자동으로 하위 세그먼트를 닫습니다.

하위 세그먼트를 세그먼트 또는 다른 하위 세그먼트 내에서 생성할 경우 Node.js용 X-Ray SDK가 해당 하위 세그먼트에 대해 ID를 생성하고 시작 시간 및 종료 시간을 기록합니다.

예 메타데이터가 포함된 하위 세그먼트
"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },

사용자 지정 Lambda 하위 세그먼트

SDK는 Lambda에서 실행 중임을 감지하면 자리표시자 facade 세그먼트를 자동으로 생성하도록 구성됩니다. X-Ray Trace 맵에 단일 AWS::Lambda::Function 노드를 생성하는 기본 하위 세그먼트를 만들려면 파사드 세그먼트를 호출하고 용도를 변경하십시오. 추적 ID, 상위 ID 및 샘플링 결정을 공유할 때 새 ID를 사용하여 새 세그먼트를 수동으로 만들면 새 세그먼트를 보낼 수 있습니다.

예 app.js – 수동 사용자 지정 하위 세그먼트
const segment = AWSXRay.getSegment(); //returns the facade segment
const subsegment = segment.addNewSubsegment('subseg');
...
subsegment.close();
//the segment is closed by the SDK automatically

Node.js용 X-Ray SDK로 세그먼트에 주석 및 메타데이터 추가하기

주석과 메타데이터를 사용하여 요청, 환경 또는 애플리케이션에 대한 추가 정보를 기록할 수 있습니다. X-Ray SDK에서 생성하는 세그먼트 또는 사용자가 생성하는 사용자 지정 하위 세그먼트에 주석 및 메타데이터를 추가할 수 있습니다.

주석은 문자열, 숫자 또는 부울 값과 결합한 키-값 페어입니다. 주석은 필터 표현식에서 사용하기 위해 인덱싱됩니다. 주석은 콘솔의 트레이스를 그룹화할 때 사용할 데이터를 기록하거나 GetTraceSummaries API를 호출할 때 사용하십시오.

메타데이터는 객체 및 목록을 포함한 모든 유형의 값을 가질 수 있는 키-값 페어지만, 필터 표현식에 사용할 수 있도록 인덱싱되지는 않습니다. 트레이스에 저장하고 싶지만 검색에는 사용하지 않을 추가 데이터는 메타데이터를 사용하여 기록하십시오.

세그먼트에는 주석과 메타데이터 외에 사용자 ID 문자열도 기록할 수 있습니다. 사용자 ID는 세그먼트의 별도 필드에 기록되면 검색용으로 인덱스되지 않습니다.

Node.js용 X-Ray SDK로 주석 기록하기

주석을 사용하여 검색용으로 인덱싱할 정보를 세그먼트나 하위 세그먼트에 기록하십시오.

주석 요구 사항

  • 키 — X-Ray 주석의 키는 최대 500자의 영숫자를 포함할 수 있습니다. 밑줄 기호 (_) 이외의 공백이나 기호는 사용할 수 없습니다.

  • 값 — X-Ray 주석의 값은 최대 1,000개의 유니코드 문자를 포함할 수 있습니다.

  • 주석 수 — 트레이스당 최대 50개의 주석을 사용할 수 있습니다.

주석 기록 방법

  1. 현재 세그먼트나 하위 세그먼트의 참조를 가져옵니다.

    var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();

  2. 문자열 키, 부울, 숫자 또는 문자열 값으로 addAnnotation을 호출합니다.

    document.addAnnotation("mykey", "my value");

SDK는 세그먼트 문서의 annotations 객체에 주석을 키-값 페어로 기록합니다. 같은 키로 addAnnotation을 두 번 호출하면 같은 세그먼트나 하위 세그먼트에 기록했던 값을 덮어씁니다.

특정 값을 포함한 주석이 있는 트레이스를 찾으려면 annotations.key 키워드를 필터 표현식에 사용하십시오.

예 app.js - 주석
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
    var item = {
        'email': {'S': req.body.email},
        'name': {'S': req.body.name},
        'preview': {'S': req.body.previewAccess},
        'theme': {'S': req.body.theme}
    };

    var seg = AWSXRay.getSegment();
    seg.addAnnotation('theme', req.body.theme);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...

Node.js용 X-Ray SDK로 메타데이터 기록하기

메타데이터를 이용해 검색용으로 인덱싱하지 않아도 되는 정보를 세그먼트나 하위 세그먼트에 기록하십시오. 메타데이터 값은 문자열, 숫자, 부울 또는 JSON 객체나 어레이에 직렬화할 수 있는 다른 모든 객체가 될 수 있습니다.

메타데이터 기록 방법

  1. 현재 세그먼트나 하위 세그먼트의 참조를 가져옵니다.

    var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();

  2. 문자열 키, 부울, 숫자, 문자열 또는 객체 값 및 문자열 네임스페이스로 addMetadata를 호출합니다.

    document.addMetadata("my key", "my value", "my namespace");

    또는

    키와 값만 이용해 addMetadata를 호출합니다.

    document.addMetadata("my key", "my value");

네임스페이스를 지정하지 않으면, SDK는 default를 사용합니다. 같은 키로 addMetadata을 두 번 호출하면 같은 세그먼트나 하위 세그먼트에 기록했던 값을 덮어씁니다.

Node.js용 X-Ray SDK로 사용자 ID 기록하기

사용자 ID를 요청 세그먼트에 기록하여 요청을 보낸 사용자를 식별합니다. Lambda 환경의 세그먼트는 변경할 수 없으므로 이 작업은 AWS Lambda 함수와 호환되지 않습니다. setUser 호출은 하위 세그먼트가 아닌 세그먼트에만 적용할 수 있습니다.

사용자 ID 기록 방법

  1. 현재 세그먼트나 하위 세그먼트의 참조를 가져옵니다.

    var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();

  2. 요청을 보낸 사용자의 문자열 ID로 setUser()를 호출합니다.

    var user = 'john123';

AWSXRay.getSegment().setUser(user);

빠른 애플리케이션이 요청 처리를 시작하는 즉시 사용자 ID를 기록하기 위해 setUser를 호출할 수 있습니다. 사용자 ID 설정을 위해서만 세그먼트를 사용한다면 호출을 1줄로 연결할 수 있습니다.

예 app.js - 사용자 ID
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
    app.post('/signup', function(req, res) {
    var userId = uuidv4();
    var item = {
        'userId': {'S': userId},
        'email': {'S': req.body.email},
        'name': {'S': req.body.name}
    };

    var seg = AWSXRay.getSegment().setUser(userId);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...

사용자 ID의 트레이스를 찾으려면, user 키워드를 필터 표현식에 적용하십시오.