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

# Node.js용 X-Ray SDK를 사용하여 사용자 지정 하위 세그먼트 생성하기
<a name="xray-sdk-nodejs-subsegments"></a>

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

## 사용자 지정 Express 하위 세그먼트
<a name="xray-sdk-nodejs-subsegments-express"></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)을 참조하세요.

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

**Example 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를 생성하고 시작 시간 및 종료 시간을 기록합니다.

**Example 메타데이터가 포함된 하위 세그먼트**  

```
"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 하위 세그먼트
<a name="xray-sdk-nodejs-subsegments-lambda"></a>

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

**Example 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
```