本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 X-Ray SDK for Node.js 生成自定义子分段
自定义子分段

子分段可为跟踪的[分段](xray-concepts.md#xray-concepts-segments)扩展为了给请求提供服务而已完成的工作的详细信息。每次使用已检测的客户端进行调用时，X-Ray SDK 在子分段中记录生成的信息。您可以创建其他子分段来分组其他子分段，来度量某个代码段的性能如何，或是来记录注释和元数据。

## 自定义 Express 子分段


**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

使用 `captureAsyncFunc` 函数为调用下游服务的函数创建自定义子分段。

**Example app.js - 自定义子分段表示**  

```
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();
};
```

在本示例中，应用程序将创建一个名为 `send` 的自定义子分段以调用 `sendRequest` 函数。`captureAsyncFunc` 传递您在回调函数发出的异步调用完成时必须在回调函数内关闭的子分段。

对于同步函数，您可以使用 `captureFunc` 函数，这会在函数块完成执行时立即自动结束子分段。

当您在分段或者其他子分段中创建子分段时，X-Ray SDK for Node.js 将为其生成 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 子分段


该 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
```