Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Tambahkan anotasi dan metadata ke segmen dengan X-Ray SDK for Python
**catatan**
Pemberitahuan SDK/Daemon Pemeliharaan X-Ray - Pada 25 Februari 2026, AWS SDKs/Daemon X-Ray akan memasuki mode pemeliharaan, di mana AWS akan membatasi rilis X-Ray SDK dan Daemon untuk mengatasi masalah keamanan saja. Untuk informasi selengkapnya tentang garis waktu dukungan, lihat[Garis waktu Dukungan X-Ray SDK dan Daemon](xray-sdk-daemon-timeline.md). Kami merekomendasikan untuk bermigrasi ke OpenTelemetry. Untuk informasi lebih lanjut tentang migrasi ke OpenTelemetry, lihat [Migrasi dari instrumentasi X-Ray ke instrumentasi](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Anda dapat mencatat informasi tambahan tentang permintaan, lingkungan, atau aplikasi Anda dengan anotasi dan metadata. Anda dapat menambahkan anotasi dan metadata ke segmen yang dibuat oleh SDK X-Ray, atau subsegmen kustom yang Anda buat.
**Anotasi** adalah pasangan kunci-nilai dengan string, nomor, atau nilai-nilai Boolean. Anotasi diindekskan untuk digunakan dengan [Ekspresi filter](xray-console-filters.md). Gunakan anotasi untuk mencatat data yang ingin Anda gunakan untuk mengelompokkan pelacakan di konsol tersebut, atau saat memanggil API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
**Metadata** adalah pasangan kunci-nilai yang dapat memiliki nilai dari setiap tipe, termasuk objek dan daftar, tetapi tidak diindekskan untuk digunakan dengan ekspresi filter. Gunakan metadata untuk mencatat data tambahan yang ingin disimpan dalam pelacakan tetapi tidak perlu digunakan dengan pencarian.
Selain anotasi dan metadata, Anda juga dapat [mencatat string ID pengguna](#xray-sdk-python-segment-userid) pada segmen. Pengguna IDs direkam dalam bidang terpisah pada segmen dan diindeks untuk digunakan dengan pencarian.
**Topics**
+ [Anotasi pencatatan dengan X-Ray SDK for Python](#xray-sdk-python-segment-annotations)
+ [Metadata pencatatan dengan X-Ray SDK for Python](#xray-sdk-python-segment-metadata)
+ [Merekam pengguna IDs dengan X-Ray SDK untuk Python](#xray-sdk-python-segment-userid)
## Anotasi pencatatan dengan X-Ray SDK for Python
Gunakan anotasi untuk mencatat informasi pada segmen atau subsegmen yang ingin diindeks untuk pencarian.
**Persyaratan Anotasi**
+ **Tombol** — Kunci untuk anotasi X-Ray dapat memiliki hingga 500 karakter alfanumerik. Anda tidak dapat menggunakan spasi atau simbol selain titik atau titik (.)
+ **Nilai** — Nilai untuk anotasi X-Ray dapat memiliki hingga 1.000 karakter Unicode.
+ Jumlah **Anotasi** — Anda dapat menggunakan hingga 50 anotasi per jejak.
**Untuk mencatat anotasi**
1. Dapatkan referensi ke segmen atau subsegmen saat ini dari `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
atau
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Panggil `put_annotation` dengan kunci String, serta nilai Boolean, Nomor, atau String.
```
document.put_annotation("mykey", "my value");
```
Contoh berikut menunjukkan cara memanggil `putAnnotation` dengan kunci String yang mencakup titik, dan nilai Boolean, Number, atau String.
```
document.putAnnotation("testkey.test", "my value");
```
Atau, Anda dapat menggunakan metode `put_annotation` pada `xray_recorder`. Metode ini mencatat penjelasan pada subsegmen saat ini atau, jika tidak ada subsegmen terbuka, pada segmen.
```
xray_recorder.put_annotation("mykey", "my value");
```
SDK mencatat penjelasan sebagai pasangan kunci-nilai dalam objek `annotations` dokumen segmen. Memanggil `put_annotation` dua kali dengan tombol yang sama akan menimpa nilai yang tercatat sebelumnya pada segmen atau subsegmen yang sama.
Untuk menemukan penelusuran yang memiliki anotasi dengan nilai-nilai tertentu, gunakan kata kunci `annotation[key]` dalam [ekspresi filter](xray-console-filters.md).
## Metadata pencatatan dengan X-Ray SDK for Python
**Awas**
Jangan menambahkan objek dengan referensi melingkar sebagai nilai metadata di X-Ray SDK untuk Python. Objek ini tidak dapat diserialisasikan ke dalam JSON dan dapat membuat loop tak terbatas di SDK. Selain itu, hindari menambahkan objek besar dan kompleks sebagai metadata untuk mencegah masalah kinerja.
Gunakan metadata untuk mencatat informasi pada segmen atau subsegmen yang tidak perlu diindeks untuk pencarian. Nilai metadata bisa string, angka, Boolean, atau objek yang dapat diserialkan ke dalam objek JSON atau array.
**Untuk mencatat metadata**
1. Dapatkan referensi ke segmen atau subsegmen saat ini dari `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
atau
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_subsegment()
```
1. Panggil `put_metadata` dengan kunci String, Boolean, Nomor, String, atau nilai Objek; dan namespace String.
```
document.put_metadata("my key", "my value", "my namespace");
```
atau
Panggil `put_metadata` dengan kunci dan nilai.
```
document.put_metadata("my key", "my value");
```
Atau, Anda dapat menggunakan metode `put_metadata` pada `xray_recorder`. Metode ini mencatat metadata pada subsegmen saat ini atau, jika tidak ada subsegmen terbuka, pada segmen.
```
xray_recorder.put_metadata("my key", "my value");
```
Jika Anda tidak menentukan namespace, SDK menggunakan `default`. Memanggil `put_metadata` dua kali dengan tombol yang sama akan menimpa nilai yang tercatat sebelumnya pada segmen atau subsegmen yang sama.
## Merekam pengguna IDs dengan X-Ray SDK untuk Python
Rekam segmen pengguna IDs berdasarkan permintaan untuk mengidentifikasi pengguna yang mengirim permintaan.
**Untuk merekam pengguna IDs**
1. Dapatkan referensi ke segmen saat ini dari `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
...
document = xray_recorder.current_segment()
```
1. Panggil `setUser` dengan ID String dari pengguna yang mengirim permintaan.
```
document.set_user("U12345");
```
Anda dapat menelepon `set_user` di pengendali Anda untuk mencatat ID pengguna segera setelah aplikasi Anda mulai memproses permintaan.
Untuk menemukan penelusuran pada ID pengguna, gunakan kata kunci `user` di [ekspresi filter](xray-console-filters.md).