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

# Node.js용 X-Ray SDK로 세그먼트에 주석 및 메타데이터 추가하기
<a name="xray-sdk-nodejs-segment"></a>

**참고**  
X-Ray SDK/데몬 유지 관리 공지 - 2026년 2월 25일에 AWS X-Ray SDKs/데몬은 유지 관리 모드로 전환되며, 여기서 AWS 는 보안 문제만 해결하도록 X-Ray SDK 및 데몬 릴리스를 제한합니다. 지원 일정에 대한 자세한 내용은 [X-Ray SDK 및 데몬 지원 타임라인](xray-sdk-daemon-timeline.md) 섹션을 참조하세요. OpenTelemetry로 마이그레이션하는 것이 좋습니다. OpenTelemetry로 마이그레이션하는 방법에 대한 자세한 내용은 [X-Ray 계측에서 OpenTelemetry 계측으로 마이그레이션](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)을 참조하세요.

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

**주석**은 문자열, 숫자 또는 부울 값과 결합한 키-값 페어입니다. 주석은 [필터 표현식](xray-console-filters.md)에서 사용하기 위해 인덱싱됩니다. 주석은 콘솔의 트레이스를 그룹화할 때 사용할 데이터를 기록하거나 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API를 직접 호출할 때 사용하세요.

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

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

**Topics**
+ [Node.js용 X-Ray SDK로 주석 기록하기](#xray-sdk-nodejs-segment-annotations)
+ [Node.js용 X-Ray SDK로 메타데이터 기록하기](#xray-sdk-nodejs-segment-metadata)
+ [Node.js용 X-Ray SDK로 사용자 ID 기록하기](#xray-sdk-nodejs-segment-userid)

## Node.js용 X-Ray SDK로 주석 기록하기
<a name="xray-sdk-nodejs-segment-annotations"></a>

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

**주석 요구 사항**
+ **키** - X-Ray 주석의 키는 최대 500자의 영숫자를 포함할 수 있습니다. 점이나 마침표(.) 이외의 공백이나 기호를 사용할 수 없습니다.
+ **값** - X-Ray 주석의 값은 최대 1,000자의 유니코드 문자를 포함할 수 있습니다.
+ **주석** 수 - 트레이스당 최대 50개의 주석을 사용할 수 있습니다.

**주석 기록 방법**

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

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

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

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

   다음 예에서는 점이 포함된 문자열 키와 부울, 숫자 또는 문자열 값을 사용하여 `putAnnotation`을 직접 호출하는 방법을 보여줍니다.

   ```
   document.putAnnotation("testkey.test", "my value");
   ```

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

특정 값을 포함한 주석이 있는 트레이스를 찾으려면 `annotation[key]` 키워드를 [필터 표현식](xray-console-filters.md)에 사용하십시오.

**Example 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로 메타데이터 기록하기
<a name="xray-sdk-nodejs-segment-metadata"></a>

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

**메타데이터 기록 방법**

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

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

1. 문자열 키, 부울, 숫자, 문자열 또는 객체 값 및 문자열 네임스페이스로 `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 기록하기
<a name="xray-sdk-nodejs-segment-userid"></a>

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

**사용자 ID 기록 방법**

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

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

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

   ```
   var user = 'john123';
   
   AWSXRay.getSegment().setUser(user);
   ```

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

**Example 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` 키워드를 [필터 표현식](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html)에 적용하십시오.