Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS X-Ray SDK untuk 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
X-Ray SDK for Python adalah pustaka untuk aplikasi web Python yang menyediakan kelas dan metode untuk menghasilkan dan mengirim data pelacakan ke daemon X-Ray. Data pelacakan mencakup informasi tentang permintaan HTTP masuk yang disajikan oleh aplikasi, dan panggilan yang dilakukan aplikasi ke layanan hilir menggunakan AWS SDK, klien HTTP, atau konektor database SQL. Anda juga dapat membuat segmen secara manual dan menambahkan informasi debug dalam anotasi dan metadata.
Anda dapat mengunduh SDK dengan `pip`.
```
$ pip install aws-xray-sdk
```
**catatan**
X-Ray SDK for Python adalah proyek sumber terbuka. Anda dapat mengikuti proyek dan mengirimkan masalah dan menarik permintaan di GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-python)- xray-sdk-python
Jika Anda menggunakan Django atau Flask, mulai dengan [menambahkan middleware SDK ke aplikasi Anda](xray-sdk-python-middleware.md) untuk melacak permintaan yang masuk. middleware menciptakan [segmen](xray-concepts.md#xray-concepts-segments) untuk setiap permintaan yang dilacak, dan melengkapi segmen ketika respons dikirim. Ketika segmen terbuka, Anda dapat menggunakan metode klien SDK untuk menambahkan informasi ke segmen dan membuat subsegmen untuk penelusuran panggilan hilir. SDK juga secara otomatis mencatat pengecualian yang aplikasi Anda lempar ketika segmen terbuka. Untuk aplikasi lain, Anda dapat [buat segmen secara manual](xray-sdk-python-middleware.md#xray-sdk-python-middleware-manual).
Untuk fungsi Lambda yang disebut oleh aplikasi atau layanan yang diinstrumentasi, Lambda membaca [tracing header](xray-concepts.md#xray-concepts-tracingheader) dan pelacakan sampel permintaan secara otomatis. Untuk fungsi lainnya, Anda dapat [mengonfigurasi Lambda](xray-services-lambda.md) untuk sampel dan pelacakan permintaan masuk. Dalam kedua kasus, Lambda membuat segmen dan menyediakannya ke X-Ray SDK.
**catatan**
Pada Lambda, X-Ray SDK adalah opsional. Jika Anda tidak menggunakannya dalam fungsi Anda, peta layanan Anda masih akan menyertakan simpul untuk layanan Lambda, dan satu untuk setiap fungsi Lambda. Dengan menambahkan SDK, Anda dapat melakukan instrumen kode fungsi Anda untuk menambahkan subsegmen ke segmen fungsi yang dicatat oleh Lambda. Lihat [AWS Lambda dan AWS X-Ray](xray-services-lambda.md) untuk informasi selengkapnya.
Lihat [Pekerja](scorekeep-lambda.md#scorekeep-lambda-worker) untuk contoh fungsi Python yang diinstrumentasikan di Lambda.
Selanjutnya, gunakan X-Ray SDK for Python untuk instrumen panggilan hilir dengan [patching pustaka aplikasi Anda](xray-sdk-python-patching.md). SDK mendukung pustaka berikut.
**Pustaka yang didukung**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)` — AWS SDK for Python (Boto) Klien instrumen.
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – Versi PynamoDB Instrumen dari klien Amazon DynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)` – Instrumen [asyncio](https://docs.python.org/3/library/asyncio.html)-versi terintegrasi dari klien SDK for Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)` – Instrumen klien HTTP tingkat tinggi.
+ `[httplib](https://docs.python.org/2/library/httplib.html)`, [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) – Instrumen klien HTTP tingkat rendah dan pustaka tingkat yang lebih tinggi yang menggunakannya.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Klien instrumen.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` – Instrumen klien MySQL.
+ `[pg8000](https://pypi.org/project/pg8000/)` – Instrumen antarmuka Pure-Python PostgreSQL.
+ `[psycopg2](https://pypi.org/project/psycopg2/)` – Adaptor basis data Instrumen PostgreSQL.
+ `[pymongo](https://pypi.org/project/pymongo/)` – Instrumen klien MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Instrumen klien berbasis PyMy SQL untuk MySQL dan MariaDB.
Setiap kali aplikasi Anda membuat panggilan ke AWS, database SQL, atau layanan HTTP lainnya, SDK mencatat informasi tentang panggilan dalam subsegmen. Layanan AWS dan sumber daya yang Anda akses dalam layanan muncul sebagai node hilir pada peta jejak untuk membantu Anda mengidentifikasi kesalahan dan masalah pembatasan pada koneksi individual.
Setelah Anda mulai menggunakan SDK, sesuaikan perilakunya dengan [mengonfigurasi perekam dan middleware](xray-sdk-python-configuration.md). Anda dapat menambahkan plugin untuk mencatat data mengenai sumber daya komputasi yang berjalan di aplikasi Anda, menyesuaikan perilaku sampling dengan mendefinisikan aturan sampling, dan mengatur tingkat log untuk melihat lebih atau kurang informasi dari SDK dalam log aplikasi Anda.
Catat informasi tambahan tentang permintaan dan pekerjaan yang dilakukan aplikasi Anda dalam [anotasi dan metadata](xray-sdk-python-segment.md). Anotasi adalah pasangan kunci-nilai sederhana yang diindeks untuk digunakan dengan [ekspresi filter](xray-console-filters.md), sehingga Anda dapat mencari pelacakan yang berisi data tertentu. Entri metadata kurang bersifat membatasi dan dapat mencatat seluruh objek dan array — segala yang dapat disambungkan ke dalam JSON.
**Anotasi dan Metadata**
Anotasi dan metadata adalah teks abritari yang Anda tambahkan ke segmen dengan X-Ray SDK. Anotasi diindekskan untuk digunakan dengan ekspresi filter. Metadata tidak diindeks, tetapi dapat dilihat di segmen mentah dengan konsol X-Ray atau API. Siapa pun yang Anda berikan akses baca ke X-Ray dapat melihat data ini.
Bila Anda memiliki banyak klien diinstrumentasi dalam kode Anda, segmen permintaan tunggal dapat berisi sejumlah besar subsegmen, satu untuk setiap panggilan yang dilakukan dengan klien yang diinstrumentasi. Anda dapat mengatur dan grup subsegmen dengan membungkus panggilan klien di [subsegmen kustom](xray-sdk-python-subsegments.md). Anda dapat membuat subsegmen kustom untuk seluruh fungsi atau bagian kode apa pun. Anda kemudian dapat mencatat metadata dan anotasi pada subsegmen bukan menulis segala sesuatu pada segmen induk.
Untuk dokumentasi referensi untuk kelas SDK dan metode, lihat [AWS X-Ray SDK for Python untuk Referensi API](https://docs.aws.amazon.com/xray-sdk-for-python/latest/reference).
## Persyaratan
X-Ray SDK for Python mendukung versi bahasa dan pustaka berikut.
+ **Python** – 2.7, 3.4, dan yang lebih baru
+ **Django** – 1.10 dan yang lebih baru
+ **Flask** – 0.10 dan yang lebih baru
+ **aiohttp** – 2.3.0 dan versi terbaru
+ **AWS SDK for Python (Boto)** – 1.4.0 dan yang lebih baru
+ **botocore** – 1.5.0 dan yang lebih baru
+ **enum** – 0.4.7 dan yang lebih baru, untuk Python versi 3.4.0 dan yang lebih lama
+ **jsonpickle** – 1.0.0 dan yang lebih baru
+ **setuptools** – 40.6.3 dan yang lebih baru
+ **wrapt** – 1.11.0 dan yang lebih baru
## Manajemen dependensi
X-Ray SDK for Python tersedia dari `pip`.
+ **Package** - `aws-xray-sdk`
Tambahkan SDK sebagai dependensi di file `requirements.txt` Anda.
**Example requirements.txt**
```
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3
```
Jika Anda menggunakan Elastic Beanstalk untuk men-deploy aplikasi Anda, Elastic Beanstalk menginstal semua paket di `requirements.txt` secara otomatis.
# Mengonfigurasi 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
X-Ray SDK for Python mencakup kelas bernama `xray_recorder` yang menyediakan pencatat global. Anda dapat mengonfigurasi pencatat global untuk menyesuaikan middleware yang membuat segmen untuk panggilan HTTP masuk.
**Topics**
+ [Plugin layanan](#xray-sdk-python-configuration-plugins)
+ [Aturan pengambilan sampel](#xray-sdk-python-configuration-sampling)
+ [Logging](#xray-sdk-python-configuration-logging)
+ [Konfigurasi pencatat dalam kode](#xray-sdk-python-middleware-configuration-code)
+ [Konfigurasi pencatat dengan Django](#xray-sdk-python-middleware-configuration-django)
+ [Variabel-variabel lingkungan](#xray-sdk-python-configuration-envvars)
## Plugin layanan
Gunakan `plugins` untuk mencatat informasi tentang layanan yang meng-hosting aplikasi Anda.
**Plugin**
+ Amazon EC2 — `EC2Plugin` menambahkan ID instans, Availability Zone, dan Grup CloudWatch Log.
+ Elastic Beanstalk – `ElasticBeanstalkPlugin` menambahkan nama lingkungan, label versi, dan ID deployment.
+ Amazon ECS – `ECSPlugin` menambahkan ID kontainer.
![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)
Untuk menggunakan plugin, hubungi `configure` di `xray_recorder`.
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
xray_recorder.configure(service='My app')
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
xray_recorder.configure(plugins=plugins)
patch_all()
```
**catatan**
Karena `plugins` diteruskan sebagai tuple, pastikan untuk menyertakan `,` saat menentukan plugin tunggal. Sebagai contoh, `plugins = ('EC2Plugin',)`.
Anda juga dapat menggunakan [variabel lingkungan](#xray-sdk-python-configuration-envvars), yang diutamakan daripada nilai yang ditetapkan dalam kode, untuk mengonfigurasi pencatat.
Konfigurasikan plugin sebelum [pustaka patch](xray-sdk-python-patching.md) untuk mencatat panggilan hilir.
SDK juga menggunakan pengaturan plugin untuk mengatur bidang `origin` pada segmen. Ini menunjukkan jenis AWS sumber daya yang menjalankan aplikasi Anda. Saat Anda menggunakan beberapa plugin, SDK menggunakan urutan resolusi berikut untuk menentukan asal: ElasticBeanstalk > EKS > ECS >. EC2
## Aturan pengambilan sampel
SDK menggunakan aturan pengambilan sampel yang Anda tetapkan di konsol X-Ray untuk menentukan permintaan yang akan dicatat. Aturan default menelusuri permintaan pertama setiap detik, dan lima persen permintaan tambahan di semua layanan yang mengirim pelacakan ke X-Ray. [Buat aturan tambahan di konsol X-Ray](xray-console-sampling.md) untuk menyesuaikan jumlah data yang dicatat untuk setiap aplikasi Anda.
SDK menerapkan aturan kustom sesuai urutan penetapannya. Jika permintaan cocok dengan beberapa aturan kustom, SDK hanya menerapkan aturan pertama.
**catatan**
Jika SDK tidak dapat mencapai X-Ray untuk mendapatkan aturan pengambilan sampel, SDK akan beralih ke aturan lokal default dari permintaan pertama setiap detik, dan lima persen permintaan tambahan per host. Hal ini dapat terjadi jika host tidak memiliki izin untuk memanggil sampling APIs, atau tidak dapat terhubung ke daemon X-Ray, yang bertindak sebagai proxy TCP untuk panggilan API yang dilakukan oleh SDK.
Anda juga dapat mengonfigurasi SDK untuk memuat aturan sampling dari dokumen JSON. SDK dapat menggunakan aturan lokal sebagai cadangan jika terjadi kasus tidak dapat mengambil sampel X-Ray, atau menggunakan aturan lokal secara eksklusif.
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
Contoh ini menentukan satu aturan kustom dan aturan default. Aturan kustom menerapkan tingkat pengambilan sampel lima persen tanpa jumlah minimum permintaan untuk melacak jalur di `/api/move/`. Aturan default menelusuri permintaan pertama setiap detik dan 10 persen dari permintaan tambahan.
Kerugian dari menentukan aturan secara lokal adalah bahwa target tetap diterapkan oleh setiap instans pencatat secara independen, alih-alih dikelola oleh layanan X-Ray. Ketika Anda men-deploy lebih banyak host, laju tetap akan dikalikan, sehingga sulit untuk mengontrol jumlah data yang dicatat.
AWS Lambda Aktif, Anda tidak dapat mengubah laju pengambilan sampel. Jika fungsi Anda dipanggil oleh layanan yang diinstrumentasikan, panggilan yang menghasilkan permintaan yang sampelnya diambil oleh layanan yang akan dicatat oleh Lambda. Jika pelacakan aktif diaktifkan dan tidak ada header pelacakan, Lambda membuat keputusan pengambilan sampel.
Untuk mengonfigurasi aturan pengambilan sampel cadangan, panggil`xray_recorder.configure`, seperti yang ditunjukkan pada contoh berikut, di mana *rules* adalah kamus aturan atau jalur absolut ke file JSON yang berisi aturan pengambilan sampel.
```
xray_recorder.configure(sampling_rules=rules)
```
Untuk menggunakan hanya aturan lokal, konfigurasikan pencatat dengan `LocalSampler`.
```
from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())
```
Anda juga dapat mengonfigurasi pencatat global untuk menonaktifkan pengambilan sampel dan instrumen semua permintaan masuk.
**Example main.py - Nonaktifkan sampling**
```
xray_recorder.configure(sampling=False)
```
## Logging
SDK menggunakan modul `logging` Python bawaan dengan tingkat pencatatan `WARNING` default. Dapatkan referensi ke pencatat untuk kelas `aws_xray_sdk` dan panggil `setLevel` untuk mengonfigurasi tingkat log yang berbeda untuk pustaka dan sisa aplikasi Anda.
**Example app.py - Pencatatan**
```
logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)
```
Gunakan log debug untuk mengidentifikasi masalah, seperti subsegmen yang tidak tertutup, saat Anda [menghasilkan subsegmen secara manual](xray-sdk-python-subsegments.md).
## Konfigurasi pencatat dalam kode
Pengaturan tambahan tersedia dari metode `configure` pada `xray_recorder`.
+ `context_missing` – Mengatur ke `LOG_ERROR` untuk menghindari mengembalikan pengecualian ketika kode instrumentasi Anda mencoba mencatat data ketika tidak ada segmen yang terbuka.
+ `daemon_address` – Mengatur host dan port listener daemon X-Ray.
+ `service` – Mengatur nama layanan yang digunakan SDK untuk segmen.
+ `plugins`— Rekam informasi tentang AWS sumber daya aplikasi Anda.
+ `sampling` – Atur ke `False` untuk menonaktifkan pengambilan sampel.
+ `sampling_rules` – Mengatur jalur dari file JSON yang berisi [Aturan pengambilan sampel](#xray-sdk-python-configuration-sampling).
**Example main.py - Nonaktifkan pengecualian konteks yang hilang**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(context_missing='LOG_ERROR')
```
## Konfigurasi pencatat dengan Django
Jika Anda menggunakan kerangka kerja Django, Anda dapat menggunakan file `settings.py` Django untuk mengonfigurasi opsi pada pencatat global.
+ `AUTO_INSTRUMENT` (hanya Django) – Mencatat subsegmen untuk basis data bawaan dan operasi penyajian templat.
+ `AWS_XRAY_CONTEXT_MISSING` – Mengatur ke `LOG_ERROR` untuk menghindari mengembalikan pengecualian ketika kode instrumentasi Anda mencoba untuk mencatat data ketika tidak ada segmen yang terbuka.
+ `AWS_XRAY_DAEMON_ADDRESS` – Mengatur host dan port listener daemon X-Ray.
+ `AWS_XRAY_TRACING_NAME` – Mengatur nama layanan yang digunakan SDK untuk segmen.
+ `PLUGINS`— Rekam informasi tentang AWS sumber daya aplikasi Anda.
+ `SAMPLING` – Atur ke `False` untuk menonaktifkan pengambilan sampel.
+ `SAMPLING_RULES` – Mengatur jalur dari file JSON yang berisi [Aturan pengambilan sampel](#xray-sdk-python-configuration-sampling).
Untuk mengaktifkan konfigurasi pencatat di `settings.py`, tambahkan middleware Django ke daftar aplikasi terinstal.
**Example settings.py – Aplikasi terinstal**
```
INSTALLED_APPS = [
...
'django.contrib.sessions',
'aws_xray_sdk.ext.django',
]
```
Mengonfigurasi pengaturan yang tersedia dalam kamus bernama `XRAY_RECORDER`.
**Example settings.py – Aplikasi terinstal**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000',
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
'SAMPLING': False,
}
```
## Variabel-variabel lingkungan
Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for Python. SDK mendukung variabel berikut:
+ `AWS_XRAY_TRACING_NAME` – Mengatur nama layanan yang digunakan SDK untuk segmen. Menimpa nama layanan yang Anda tetapkan secara terprogram.
+ `AWS_XRAY_SDK_ENABLED` – Ketika diatur ke `false`, menonaktifkan SDK. Secara default, SDK diaktifkan kecuali variabel lingkungan diatur ke salah.
+ Ketika dinonaktifkan, pencatat global secara otomatis menghasilkan segmen dan subsegmen dummy yang tidak dikirim ke daemon, dan patch otomatis dinonaktifkan. Middlewares ditulis sebagai pembungkus atas pencatat global. Semua segmen dan subsegmen generasi melalui middleware juga menjadi segmen dummy dan subsegment dummy.
+ Menetapkan nilai `AWS_XRAY_SDK_ENABLED`melalui variabel lingkungan atau melalui interaksi langsung dengan objek `global_sdk_config` dari pustaka `aws_xray_sdk`. Pengaturan ke variabel lingkungan menimpa interaksi ini.
+ `AWS_XRAY_DAEMON_ADDRESS` – Mengatur host dan port listener daemon X-Ray. Secara default, SDK menggunakan `127.0.0.1:2000` untuk data pelacakan (UDP) dan pengambilan sampel (TCP). Gunakan variabel ini jika Anda telah mengonfigurasi daemon untuk [mendengarkan di port berbeda](xray-daemon-configuration.md) atau jika berjalan pada host yang berbeda.
**Format**
+ **Port yang sama** – `address:port`
+ **Port yang berbeda** – `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING`— Setel `RUNTIME_ERROR` untuk melempar pengecualian saat kode instrumentasi Anda mencoba merekam data saat tidak ada segmen yang terbuka.
**Nilai Valid**
+ `RUNTIME_ERROR`— Lempar pengecualian runtime.
+ `LOG_ERROR`— Log kesalahan dan lanjutkan (default).
+ `IGNORE_ERROR`— Abaikan kesalahan dan lanjutkan.
Kesalahan yang berkaitan dengan segmen atau subsegmen yang hilang dapat terjadi ketika Anda mencoba untuk menggunakan klien yang diinstrumentasi dalam kode perusahaan rintisan yang berjalan ketika tidak ada permintaan terbuka, atau dalam kode yang memunculkan thread baru.
variabel lingkungan menimpa nilai yang ditetapkan dalam kode.
# Menelusuri permintaan yang masuk dengan perangkat tengah SDK for Python X-Ray
**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
Ketika Anda menambahkan perangkat tengah ke aplikasi Anda dan mengonfigurasi nama segmen, SDK for Python X-Ray membuat segmen untuk setiap permintaan sampel. Segmen ini mencakup waktu, metode, dan disposisi permintaan HTTP. Instrumentasi tambahan membuat subsegmen pada segmen ini.
SDK for Python X-Ray mendukung perangkat tengah berikut ini untuk instrumen permintaan HTTP yang masuk:
+ Django
+ Flask
+ Botol
**catatan**
Untuk AWS Lambda fungsi, Lambda membuat segmen untuk setiap permintaan sampel. Lihat [AWS Lambda dan AWS X-Ray](xray-services-lambda.md) untuk informasi selengkapnya.
Lihat [Pekerja](scorekeep-lambda.md#scorekeep-lambda-worker) untuk contoh fungsi Python yang diinstrumentasikan di Lambda.
Untuk skrip atau aplikasi Python pada kerangka kerja lain, Anda dapat [membuat segmen secara manual](#xray-sdk-python-middleware-manual).
Setiap segmen memiliki nama yang mengidentifikasi aplikasi Anda dalam peta layanan. Segmen dapat diberi nama secara statis, atau Anda dapat mengonfigurasi SDK untuk nama itu secara dinamis berdasarkan header host dalam permintaan masuk. Penamaan dinamis memungkinkan Anda mengelompokkan pelacakan berdasarkan nama domain dalam permintaan, dan menerapkan nama default jika nama tersebut tidak cocok dengan pola yang diharapkan (misalnya, jika header host ditiru).
**Permintaan yang Diteruskan**
Jika penyeimbang beban atau perantara lainnya meneruskan permintaan ke aplikasi Anda, X-Ray akan mengambil IP klien dari header `X-Forwarded-For` dalam permintaan bukan dari sumber IP dalam paket IP. IP klien yang dicatat untuk permintaan yang diteruskan dapat ditiru, sehingga tidak dapat dipercaya.
Ketika permintaan diteruskan, SDK menetapkan bidang tambahan di segmen untuk menunjukkan ini. Jika segmen berisi bidang `x_forwarded_for` atur ke`true`, IP klien diambil dari header `X-Forwarded-For` dalam permintaan HTTP.
Perangkat tengah membuat segmen untuk setiap permintaan masuk dengan blok `http` yang berisi informasi berikut:
+ **Metode HTTP** – GET, POST, PUT, DELETE, dll
+ **Alamat klien** – Alamat IP klien yang mengirim permintaan.
+ **Kode respons** – Kode respons HTTP untuk permintaan yang selesai.
+ **Timing** – Waktu mulai (saat permintaan diterima) dan waktu akhir (saat respons dikirim).
+ **Agen pengguna** — `user-agent` dari permintaan.
+ **Panjang konten** — `content-length` dari respons.
**Topics**
+ [Menambahkan perangkat tengah ke aplikasi Anda (Django)](#xray-sdk-python-adding-middleware-django)
+ [Menambahkan perangkat tengah ke aplikasi Anda (flask)](#xray-sdk-python-adding-middleware-flask)
+ [Menambahkan perangkat tengah ke aplikasi Anda (Bottle)](#xray-sdk-python-adding-middleware-bottle)
+ [Menginstrumentasikan kode Python secara manual](#xray-sdk-python-middleware-manual)
+ [Mengonfigurasi strategi penamaan segmen](#xray-sdk-python-middleware-naming)
## Menambahkan perangkat tengah ke aplikasi Anda (Django)
Tambahkan perangkat tengah ke daftar `MIDDLEWARE` di file `settings.py` Anda. Perangkat tengah X-Ray harus menjadi baris pertama dalam file `settings.py` untuk memastikan bahwa permintaan yang gagal di perangkat tengah lain dicatat.
**Example settings.py - perangkat tengah SDK for Python X-Ray**
```
MIDDLEWARE = [
'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware'
]
```
Tambahkan aplikasi Django SDK X-Ray ke daftar `INSTALLED_APPS` di file `settings.py`. Tindakan ini akan mengizinkan pencatat X-Ray dikonfigurasi selama memulai aplikasi Anda.
**Example settings.py - aplikasi Django SDK for Python X-Ray**
```
INSTALLED_APPS = [
'aws_xray_sdk.ext.django',
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
]
```
Mengonfigurasi nama segmen di [file `settings.py`](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py - Nama segmen**
```
XRAY_RECORDER = {
'AWS_XRAY_TRACING_NAME': 'My application',
'PLUGINS': ('EC2Plugin',),
}
```
Ini memberitahu pencatat X-Ray untuk melacak permintaan yang dilayani oleh aplikasi Django Anda dengan tingkat pengambilan sampel default. Anda dapat [mengonfigurasi pencatat file pengaturan Django Anda](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django) untuk menerapkan aturan pengambilan sampel kustom atau mengubah pengaturan lainnya.
**catatan**
Karena `plugins` diteruskan sebagai tuple, pastikan untuk menyertakan `,` saat menentukan plugin tunggal. Sebagai contoh, `plugins = ('EC2Plugin',)`.
## Menambahkan perangkat tengah ke aplikasi Anda (flask)
Untuk instrumen aplikasi Flask Anda, pertama mengonfigurasi nama segmen pada `xray_recorder`. Kemudian, gunakan fungsi `XRayMiddleware` untuk mem-patch aplikasi Flask Anda dalam kode.
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(service='My application')
XRayMiddleware(app, xray_recorder)
```
Ini memberitahu pencatat X-Ray untuk melacak permintaan yang disediakan oleh aplikasi Flask Anda dengan tingkat pengambilan sampel default. Anda dapat [mengonfigurasi pencatat dalam kode](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) untuk menerapkan aturan pengambilan sampel kustom atau mengubah pengaturan lainnya.
## Menambahkan perangkat tengah ke aplikasi Anda (Bottle)
Untuk instrumen aplikasi Bottle Anda, pertama-tama konfigurasikan nama segmen pada `xray_recorder`. Kemudian, gunakan fungsi `XRayMiddleware` untuk melakukan patch aplikasi Bottle Anda dalam kode.
**Example app.py**
```
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.bottle.middleware import XRayMiddleware
app = Bottle()
xray_recorder.configure(service='fallback_name', dynamic_naming='My application')
app.install(XRayMiddleware(xray_recorder))
```
Ini memberitahu pencatat X-Ray untuk melacak permintaan yang disediakan oleh aplikasi Bottle Anda dengan tingkat pengambilan sampel default. Anda dapat [mengonfigurasi pencatat dalam kode](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code) untuk menerapkan aturan pengambilan sampel kustom atau mengubah pengaturan lainnya.
## Menginstrumentasikan kode Python secara manual
Jika Anda tidak menggunakan Django atau Flask, Anda dapat membuat segmen secara manual. Anda dapat membuat segmen untuk setiap permintaan yang masuk, atau membuat segmen di sekitar klien HTTP atau AWS SDK yang ditambal untuk menyediakan konteks bagi perekam untuk menambahkan subsegmen.
**Example main.py - instrumentasi manual**
```
from aws_xray_sdk.core import xray_recorder
# Start a segment
segment = xray_recorder.begin_segment('segment_name')
# Start a subsegment
subsegment = xray_recorder.begin_subsegment('subsegment_name')
# Add metadata and annotations
segment.put_metadata('key', dict, 'namespace')
subsegment.put_annotation('key', 'value')
# Close the subsegment and segment
xray_recorder.end_subsegment()
xray_recorder.end_segment()
```
## Mengonfigurasi strategi penamaan segmen
AWS X-Ray menggunakan *nama layanan* untuk mengidentifikasi aplikasi Anda dan membedakannya dari aplikasi lain, database, eksternal APIs, dan AWS sumber daya yang digunakan aplikasi Anda. Saat SDK X-Ray membuat segmen untuk permintaan masuk, SDK akan mencatat nama layanan aplikasi Anda di [kolom nama](xray-api-segmentdocuments.md#api-segmentdocuments-fields).
SDK X-Ray dapat memberi nama segmen setelah nama host di header permintaan HTTP. Namun, header ini dapat ditiru, yang dapat mengakibatkan simpul tak terduga di peta layanan Anda. Untuk mencegah SDK dari penamaan segmen salah karena permintaan dengan header host palsu, Anda harus menentukan nama default untuk permintaan masuk.
Jika aplikasi Anda menyuguhkan permintaan untuk beberapa domain, Anda dapat mengonfigurasi SDK untuk menggunakan strategi penamaan dinamis untuk mencerminkan ini dalam nama segmen. Strategi penamaan dinamis mengizinkan SDK menggunakan nama host untuk permintaan yang sesuai dengan pola yang diharapkan, dan menerapkan nama default untuk permintaan yang tidak sesuai.
Misalnya, Anda boleh memiliki satu aplikasi yang melayani permintaan untuk tiga subdomain– `www.example.com`, `api.example.com`, dan `static.example.com`. Anda dapat menggunakan strategi penamaan dinamis dengan pola `*.example.com` untuk mengidentifikasi segmen untuk setiap subdomain dengan nama yang berbeda, mengakibatkan tiga simpul layanan pada peta layanan. Jika aplikasi Anda menerima permintaan dengan nama host yang tidak cocok dengan pola, Anda akan melihat simpul keempat pada peta layanan dengan nama fallback yang Anda tentukan.
Untuk menggunakan nama yang sama untuk semua segmen permintaan, tentukan nama aplikasi Anda ketika mengonfigurasi pencatat, seperti yang ditunjukkan di [bagian sebelumnya](#xray-sdk-python-adding-middleware-django).
Strategi penamaan dinamis menentukan pola yang harus sesuai dengan nama host, dan nama default untuk digunakan jika nama host dalam permintaan HTTP tidak cocok dengan pola. Untuk menamai segmen secara dinamis di Django, tambahkan pengaturan `DYNAMIC_NAMING` ke file [settings.py](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-django).
**Example settings.py - Penamaan dinamis**
```
XRAY_RECORDER = {
'AUTO_INSTRUMENT': True,
'AWS_XRAY_TRACING_NAME': 'My application',
'DYNAMIC_NAMING': '*.example.com',
'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin')
}
```
Anda dapat menggunakan '\$1' dalam pola untuk mencocokkan string apa pun, atau '?' untuk mencocokkan setiap karakter tunggal. Untuk Flask, [konfigurasi pencatat dalam simpul](xray-sdk-python-configuration.md#xray-sdk-python-middleware-configuration-code).
**Example main.py - Nama segmen**
```
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='My application')
xray_recorder.configure(dynamic_naming='*.example.com')
```
**catatan**
Anda dapat mengganti nama layanan default yang Anda tentukan dalam kode dengan [variabel lingkungan](xray-sdk-python-configuration.md#xray-sdk-python-configuration-envvars) `AWS_XRAY_TRACING_NAME`.
# Pustaka patching ke instrumen panggilan hilir
**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
Untuk instrumen panggilan hilir, gunakan X-Ray SDK for Python untuk patch pustaka yang menggunakan aplikasi Anda. X-Ray SDK for Python dapat patch pustaka berikut.
**Pustaka yang didukung**
+ `[botocore](https://pypi.python.org/pypi/botocore)`, `[boto3](https://pypi.python.org/pypi/boto3)` — AWS SDK for Python (Boto) Klien instrumen.
+ `[pynamodb](https://pypi.python.org/pypi/pynamodb/)` – Versi PynamoDB Instrumen dari klien Amazon DynamoDB.
+ `[aiobotocore](https://pypi.python.org/pypi/aiobotocore)`, `[aioboto3](https://pypi.python.org/pypi/aioboto3)` – Instrumen [asyncio](https://docs.python.org/3/library/asyncio.html)-versi terintegrasi dari klien SDK for Python.
+ `[requests](https://pypi.python.org/pypi/requests)`, `[aiohttp](https://pypi.python.org/pypi/aiohttp)` – Instrumen klien HTTP tingkat tinggi.
+ `[httplib](https://docs.python.org/2/library/httplib.html)`, [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html) – Instrumen klien HTTP tingkat rendah dan pustaka tingkat yang lebih tinggi yang menggunakannya.
+ `[sqlite3](https://docs.python.org/3/library/sqlite3.html)`— SQLite Klien instrumen.
+ `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)` – Instrumen klien MySQL.
+ `[pg8000](https://pypi.org/project/pg8000/)` – Instrumen antarmuka Pure-Python PostgreSQL.
+ `[psycopg2](https://pypi.org/project/psycopg2/)` – Adaptor basis data Instrumen PostgreSQL.
+ `[pymongo](https://pypi.org/project/pymongo/)` – Instrumen klien MongoDB.
+ `[pymysql](https://pypi.org/project/PyMySQL/)`— Instrumen klien berbasis PyMy SQL untuk MySQL dan MariaDB.
Ketika Anda menggunakan pustaka yang dipatch, X-Ray SDK for Python membuat subsegmen untuk panggilan dan catatan informasi dari permintaan dan respons. Segmen harus tersedia untuk SDK untuk membuat subsegmen, baik dari SDK middleware atau dari AWS Lambda.
**catatan**
Jika Anda menggunakan SQLAlchemy ORM, Anda dapat menginstrumentasikan kueri SQL Anda dengan mengimpor versi sesi dan kelas kueri SDK. SQLAlchemy Lihat [Gunakan SQLAlchemy ORM](https://github.com/aws/aws-xray-sdk-python/blob/master/README.md#use-sqlalchemy-orm) untuk instruksi.
Untuk patch semua pustaka yang tersedia, gunakan fungsi `patch_all` di `aws_xray_sdk.core`. Beberapa pustaka, seperti `httplib` dan `urllib`, mungkin perlu mengaktifkan patch ganda dengan memanggil `patch_all(double_patch=True)`.
**Example main.py - Patch semua pustaka yang didukung**
```
import boto3
import botocore
import requests
import sqlite3
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all()
```
Untuk patch sebuah pustaka tunggal, hubungi `patch` dengan tupel dari nama pustaka. Untuk mencapai hal ini, Anda perlu menyediakan daftar elemen tunggal.
**Example main.py - Patch pustaka tertentu**
```
import boto3
import botocore
import requests
import mysql-connector-python
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch
libraries = (['botocore'])
patch(libraries)
```
**catatan**
Dalam beberapa kasus, kunci yang Anda gunakan untuk patch pustaka tidak cocok dengan nama pustaka. Beberapa kunci berfungsi sebagai alias untuk satu atau lebih pustaka.
`httplib`— `[httplib](https://docs.python.org/2/library/httplib.html)` dan [https://docs.python.org/3/library/http.client.html](https://docs.python.org/3/library/http.client.html)
`mysql` – `[mysql-connector-python](https://pypi.python.org/pypi/mysql-connector-python)`
## Menelusuri konteks untuk pekerjaan asynchronous
Untuk pustaka terintegrasi `asyncio`, atau untuk [membuat subsegment bagi fungsi asynchronous](xray-sdk-python-subsegments.md), Anda juga harus mengonfigurasi X-Ray SDK for Python dengan konteks async. Mengimpor kelas `AsyncContext` dan lulus instans nya untuk pencatat X-Ray.
**catatan**
Pustaka dukungan kerangka kerja web, seperti AIOHTTP, tidak ditangani melalui modul `aws_xray_sdk.core.patcher`. Mereka tidak akan muncul dalam katalog `patcher` dari pustaka yang didukung.
**Example main.py – Patch aioboto3**
```
import asyncio
import aioboto3
import requests
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())
from aws_xray_sdk.core import patch
libraries = (['aioboto3'])
patch(libraries)
```
# Menelusuri panggilan AWS SDK dengan X-Ray SDK untuk 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
[Saat aplikasi Anda melakukan panggilan Layanan AWS untuk menyimpan data, menulis ke antrian, atau mengirim notifikasi, X-Ray SDK untuk Python melacak panggilan hilir di subsegmen.](xray-sdk-python-subsegments.md) Ditelusuri Layanan AWS dan sumber daya yang Anda akses dalam layanan tersebut (misalnya, bucket Amazon S3 atau antrean Amazon SQS), muncul sebagai node hilir pada peta jejak di konsol X-Ray.
X-Ray SDK untuk Python secara otomatis menginstrumentasikan AWS semua klien SDK saat [Anda](xray-sdk-python-patching.md) menambal perpustakaan. `botocore` Anda tidak dapat instrumen klien individu.
Untuk semua layanan, Anda dapat melihat nama panggilan API di konsol X-Ray. Untuk subset layanan, X-Ray SDK menambahkan informasi ke segmen untuk memberikan lebih banyak perincian di peta layanan.
Sebagai contoh, ketika Anda melakukan panggilan dengan klien DynamoDB berinstrumen, SDK menambahkan nama tabel ke segmen untuk panggilan yang menargetkan tabel. Di konsol tersebut, setiap tabel muncul sebagai simpul terpisah di peta layanan, dengan simpul DynamoDB generik untuk panggilan yang tidak menargetkan tabel.
**Example Subsegmen untuk panggilan ke DynamoDB untuk menyimpan item**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Ketika Anda mengakses sumber daya bernama, panggilan ke layanan berikut membuat simpul tambahan di peta layanan. Panggilan yang tidak menargetkan sumber daya tertentu membuat simpul generik untuk layanan tersebut.
+ **Amazon DynamoDB** – Nama tabel
+ **Amazon Simple Storage Service** – Bucket dan nama kunci
+ **Amazon Simple Queue Service** – Nama antrean
# Menelusuri panggilan ke layanan web hilir HTTP menggunakan 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
Ketika aplikasi Anda melakukan panggilan ke microservices atau HTTP publik APIs, Anda dapat menggunakan X-Ray SDK untuk Python untuk instrumen panggilan tersebut dan menambahkan API ke grafik layanan sebagai layanan hilir.
Untuk klien HTTP instrumen, [patch pustaka](xray-sdk-python-patching.md) yang Anda gunakan untuk melakukan panggilan keluar. Jika Anda menggunakan `requests` atau Klien HTTP bawaan Python, itu semua yang perlu Anda lakukan. Untuk `aiohttp`, juga mengonfigurasi pencatat dengan [konteks asinkron](xray-sdk-python-patching.md#xray-sdk-python-patching-async).
Jika Anda menggunakan Klien API `aiohttp` 3, Anda juga perlu mengonfigurasi `ClientSession` dengan sebuah instans dari konfigurasi penelusuran yang disediakan oleh SDK.
**Example [`aiohttp`3 klien API](https://github.com/aws/aws-xray-sdk-python#trace-aiohttp-client-requests)**
```
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config
async def foo():
trace_config = aws_xray_trace_config()
async with ClientSession(loop=loop, trace_configs=[trace_config]) as session:
async with session.get(url) as resp
await resp.read()
```
Ketika Anda instrumen panggilan ke API web hilir, X-Ray SDK for Python mencatat subsegmen dengan informasi tentang permintaan HTTP dan respon. X-Ray menggunakan subsegmen untuk menghasilkan segmen disimpulkan untuk API jarak jauh.
**Example Subsegmen untuk panggilan HTTP downstream**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmen yang disimpulkan untuk panggilan HTTP downstream**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Menghasilkan subsegment kustom 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
Subsegmen memperluas [segmen](xray-concepts.md#xray-concepts-segments) pelacakan dengan detail tentang pekerjaan yang dilakukan untuk melayani permintaan. Setiap kali Anda melakukan panggilan dengan klien berinstrumen, X-Ray tersebut mencatat informasi yang dihasilkan dalam subsegmen. Anda dapat membuat subsegment tambahan untuk mengelompokkan subsegment lain, untuk mengukur performa bagian kode, atau untuk mencatat anotasi dan metadata.
Untuk mengelola subsegment, gunakan metode `begin_subsegment` dan `end_subsegment`.
**Example main.py - Subsegmen kustom**
```
from aws_xray_sdk.core import xray_recorder
subsegment = xray_recorder.begin_subsegment('annotations')
subsegment.put_annotation('id', 12345)
xray_recorder.end_subsegment()
```
Untuk membuat subsegmen untuk fungsi sinkron, gunakan dekorator `@xray_recorder.capture`. Anda dapat melewati nama untuk subsegment ke fungsi capture atau meninggalkannya agar menggunakan nama fungsi.
**Example main.py - Fungsi subsegmen**
```
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')
def create_user():
...
```
Untuk fungsi asynchronous, gunakan dekorator `@xray_recorder.capture_async`, dan lewati konteks async untuk mencatat.
**Example main.py - fungsi asynchronous subsegmen**
```
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()
```
Ketika Anda membuat subsegmen dalam segmen atau subsegmen lain, X-Ray SDK for Python membuat ID untuknya dan mencatat waktu mulai dan waktu akhir.
**Example Subsegmen dengan metadata**
```
"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"
}
},
```
# 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).
# Instrumenting kerangka kerja web dideploy ke lingkungan niserver
**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
AWS X-Ray SDK untuk Python mendukung kerangka kerja web instrumentasi yang digunakan dalam aplikasi tanpa server. Niserver adalah arsitektur asli cloud yang memungkinkan Anda mengalihkan lebih banyak tanggung jawab operasional Anda ke AWS, meningkatkan ketangkasan dan inovasi Anda.
Arsitektur niserver adalah model aplikasi perangkat lunak yang memungkinkan Anda untuk membangun dan menjalankan aplikasi dan layanan tanpa memikirkan server. Menghilangkan tugas-tugas manajemen infrastruktur seperti server atau penyediaan klaster, patching, pemeliharaan sistem operasi, dan penyediaan kapasitas. Anda dapat membangun solusi tanpa server untuk hampir semua tipe aplikasi atau layanan backend, dan semua yang diperlukan untuk menjalankan dan menskalakan aplikasi Anda dengan ketersediaan tinggi ditangani untuk Anda.
Tutorial ini menunjukkan kepada Anda bagaimana untuk secara otomatis instrumen AWS X-Ray pada kerangka web, seperti Flask atau Django, yang dikerahkan ke lingkungan tanpa server. Instrumentasi X-Ray aplikasi memungkinkan Anda untuk melihat semua panggilan hilir yang dibuat, mulai dari Amazon API Gateway melalui AWS Lambda fungsi Anda, dan panggilan keluar yang dilakukan aplikasi Anda.
X-Ray SDK for Python mendukung kerangka kerja aplikasi Python berikut:
+ Flask versi 0.8, atau lebih baru
+ Django versi 1.0, atau yang lebih baru
Tutorial ini mengembangkan contoh aplikasi niserver yang dideploy ke Lambda dan dipanggil oleh API Gateway. Tutorial ini menggunakan Zappa untuk secara otomatis mendeploy aplikasi untuk Lambda dan mengonfigurasi titik akhir API Gateway.
## Prasyarat
+ [Zappa](https://github.com/Miserlou/Zappa)
+ [Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html) – Versi 2.7 atau 3.6.
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)— Verifikasi bahwa Anda AWS CLI dikonfigurasi dengan akun dan Wilayah AWS di mana Anda akan menyebarkan aplikasi Anda.
+ [Pip](https://pypi.org/project/pip/)
+ [Virtualenv](https://virtualenv.pypa.io/en/latest/)
## Langkah 1: Buat lingkungan
Pada langkah ini, Anda membuat lingkungan virtual menggunakan `virtualenv` untuk meng-host aplikasi.
1. Menggunakan AWS CLI, buat direktori untuk aplikasi. Kemudian ubah ke direktori baru.
```
mkdir serverless_application
cd serverless_application
```
1. Berikutnya, buat lingkungan virtual dalam direktori baru Anda. Gunakan perintah berikut untuk mengaktifkannya.
```
# Create our virtual environment
virtualenv serverless_env
# Activate it
source serverless_env/bin/activate
```
1. Instal X-Ray, Flask, Zappa, dan pustaka Permintaan ke lingkungan Anda.
```
# Install X-Ray, Flask, Zappa, and Requests into your environment
pip install aws-xray-sdk flask zappa requests
```
1. Tambahkan kode aplikasi ke `serverless_application` direktori. Contohnya, kita dapat membangun dari contoh Flasks [Halo Dunia](https://flask.palletsprojects.com/en/3.0.x/quickstart/).
Di direktori `serverless_application`, buat file baru bernama `my_app.py`. Kemudian gunakan editor teks untuk menambahkan perintah berikut. Aplikasi ini instrumen pustaka Permintaan, patch middleware aplikasi Flask ini, dan membuka titik akhir `'/'`.
```
# Import the X-Ray modules
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
from aws_xray_sdk.core import patcher, xray_recorder
from flask import Flask
import requests
# Patch the requests module to enable automatic instrumentation
patcher.patch(('requests',))
app = Flask(__name__)
# Configure the X-Ray recorder to generate segments with our service name
xray_recorder.configure(service='My First Serverless App')
# Instrument the Flask application
XRayMiddleware(app, xray_recorder)
@app.route('/')
def hello_world():
resp = requests.get("https://aws.amazon.com")
return 'Hello, World: %s' % resp.url
```
## Langkah 2: Membuat dan men-deploy lingkungan zappa
Pada langkah ini Anda akan menggunakan Zappa untuk secara otomatis mengonfigurasi titik akhir API Gateway dan kemudian men-deploy ke Lambda.
1. Inisialisasi Zappa dari dalam `serverless_application` direktori. Sebagai contoh, kami menggunakan pengaturan default, tetapi jika Anda memiliki preferensi kustomisasi, Zappa menampilkan petunjuk konfigurasi.
```
zappa init
```
```
What do you want to call this environment (default 'dev'): dev
...
What do you want to call your bucket? (default 'zappa-*******'): zappa-*******
...
...
It looks like this is a Flask application.
What's the modular path to your app's function?
This will likely be something like 'your_module.app'.
We discovered: my_app.app
Where is your app's function? (default 'my_app.app'): my_app.app
...
Would you like to deploy this application globally? (default 'n') [y/n/(p)rimary]: n
```
1. Aktifkan X-Ray. Buka file `zappa_settings.json` dan memverifikasi bahwa itu terlihat mirip dengan contoh.
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********"
}
}
```
1. Tambahkan `"xray_tracing": true` sebagai entri ke file konfigurasi.
```
{
"dev": {
"app_function": "my_app.app",
"aws_region": "us-west-2",
"profile_name": "default",
"project_name": "serverless-exam",
"runtime": "python2.7",
"s3_bucket": "zappa-*********",
"xray_tracing": true
}
}
```
1. Men-deploy aplikasi. Ini secara otomatis mengonfigurasi titik akhir API Gateway dan mengunggah kode Anda ke Lambda.
```
zappa deploy
```
```
...
Deploying API Gateway..
Deployment complete!: https://**********.execute-api.us-west-2.amazonaws.com/dev
```
## Langkah 3: Aktifkan penelusuran X-Ray untuk API Gateway
Pada langkah ini Anda akan berinteraksi dengan konsol API Gateway untuk mengaktifkan pelacakan X-Ray.
1. Masuk ke Konsol Manajemen AWS dan buka konsol API Gateway di [https://console.aws.amazon.com/apigateway/](https://console.aws.amazon.com/apigateway/).
1. Temukan API yang baru dibuat. Harus terlihat seperti `serverless-exam-dev`.
1. Memilih **Tahapan**.
1. Pilih nama tahap deployment Anda. Nilai default-nya `dev`.
1. Pada tab **Masuk/Penelusuran**, pilih **Aktifkan penelusuran X-Ray**.
1. Pilih **Simpan Perubahan**.
1. Akses titik akhir di peramban Anda. Jika Anda menggunakan contoh aplikasi `Hello World`, aplikasi tersebut harus menampilkan hal berikut.
```
"Hello, World: https://aws.amazon.com/"
```
## Langkah 4: Lihat telusuran yang dibuat
Pada langkah ini Anda akan berinteraksi dengan konsol X-Ray untuk melihat telusuran pelacakan yang dibuat oleh aplikasi contoh. Untuk walkthrough yang lebih detail tentang analisis penelusuran, lihat [Melihat Peta Layanan](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap).
1. Masuk ke Konsol Manajemen AWS dan buka konsol X-Ray di [https://console.aws.amazon.com/xray/rumah](https://console.aws.amazon.com/xray/home).
1. Lihat segmen yang dihasilkan oleh API Gateway, fungsi Lambda, dan kontainer Lambda.
1. Di bawah segmen fungsi Lambda, melihat subsegmen bernama `My First Serverless App`. Ini diikuti oleh subsegmen kedua bernama `https://aws.amazon.com`.
1. Selama inisialisasi, Lambda mungkin juga menghasilkan subsegmen ketiga bernama `initialization`.
![\[Menelusuri tampilan segmen.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/serverless-traceView.png)
![\[Tampilan grafik layanan.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/serverless-serviceView.png)
## Langkah 5: Membersihkan
Selalu akhiri sumber daya yang tidak lagi Anda gunakan untuk menghindari akumulasi biaya tak terduga. Seperti tutorial ini menunjukkan, alat-alat seperti Zappa merampingkan redeployment niserver.
Untuk menghapus aplikasi Anda dari Lambda, API Gateway, dan Amazon S3, jalankan perintah berikut di direktori proyek Anda dengan menggunakan AWS CLI.
```
zappa undeploy dev
```
## Langkah selanjutnya
Tambahkan lebih banyak fitur ke aplikasi Anda dengan menambahkan AWS klien dan instrumentasi mereka dengan X-Ray. Pelajari selengkapnya tentang opsi komputasi niserver di [Nirserver AWS](https://aws.amazon.com/serverless).