本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用適用於 Python 的 X-Ray 開發套件產生自訂子區段
<a name="xray-sdk-python-subsegments"></a>

**注意**  
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [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)。

子區段會延伸追蹤的[區段](xray-concepts.md#xray-concepts-segments)，其中包含為了處理請求而完成之工作的詳細資訊。每次您與經檢測的用戶端進行呼叫時，X-Ray 開發套件都會記錄子區段中產生的資訊。您可以建立其他子區段來將其他子區段分組、測量程式碼區段的效能，或記錄註釋和中繼資料。

若要管理子區段，請使用 `begin_subsegment` 和 `end_subsegment` 方法。

**Example main.py – 自訂子區段**  

```
from aws_xray_sdk.core import xray_recorder

subsegment = xray_recorder.begin_subsegment('annotations')
subsegment.put_annotation('id', 12345)
xray_recorder.end_subsegment()
```

若要建立同步函數的子區段，請使用 `@xray_recorder.capture` 裝飾項目。您可以將子區段的名稱傳遞給擷取函數，或是不傳遞它來使用函數名稱。

**Example main.py – 函數子區段**  

```
from aws_xray_sdk.core import xray_recorder

@xray_recorder.capture('## create_user')
def create_user():
...
```

針對非同步函數，請使用 `@xray_recorder.capture_async` 裝飾項目，並將非同步內容傳遞給記錄器。

**Example main.py – 非同步函數子區段**  

```
from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())

@xray_recorder.capture_async('## create_user')
async def create_user():
    ...

async def main():
    await myfunc()
```

當您在區段或其他子區段中建立子區段時，適用於 Python 的 X-Ray 開發套件會為其產生 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"
    }
  },
```