Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS X-Ray agen instrumentasi otomatis untuk Java
**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
Agen AWS X-Ray instrumentasi otomatis untuk Java adalah solusi penelusuran yang menginstruksikan aplikasi web Java Anda dengan upaya pengembangan minimal. Agen memungkinkan pelacakan untuk aplikasi berbasis servlet dan semua permintaan hilir agen dibuat dengan dukungan kerangka kerja dan pustaka. Ini termasuk permintaan HTTP Apache hilir, permintaan AWS SDK, dan kueri SQL dibuat menggunakan driver JDBC. Agen menyebarkan konteks X-Ray, termasuk semua segmen dan subsegmen aktif, di seluruh utas. Semua konfigurasi dan fleksibilitas X-Ray SDK masih tersedia dengan agen Java. Default yang sesuai dipilih untuk memastikan bahwa agen bekerja dengan sedikit usaha.
Solusi agen X-Ray paling cocok untuk server aplikasi web Java yang berbasis servlet. Jika aplikasi Anda menggunakan kerangka kerja asinkron, atau tidak dimodelkan dengan baik sebagai layanan respon permintaan, Anda mungkin ingin mempertimbangkan instrumentasi manual dengan SDK sebagai gantinya.
Agen X-Ray dibangun menggunakan toolkit Distributed Systems Comprehension, atau Di. SCo Di SCo adalah kerangka open source untuk membangun agen Java yang dapat digunakan dalam sistem terdistribusi. Meskipun tidak perlu memahami Di SCo untuk menggunakan agen X-Ray, Anda dapat mempelajari lebih lanjut tentang proyek ini dengan mengunjungi [beranda di GitHub](https://github.com/awslabs/disco). Agen X-Ray juga sepenuhnya bersumber terbuka. Untuk melihat kode sumber, memberikan kontribusi, atau mengangkat masalah tentang agen, kunjungi [repositorinya](https://github.com/aws/aws-xray-java-agent) di. GitHub
## Aplikasi sampel
Aplikasi [eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent)sampel disesuaikan untuk diinstrumentasi dengan agen X-Ray. Cabang ini tidak berisi filter servlet atau konfigurasi pencatat, karena fungsi-fungsi ini dilakukan oleh agen. Untuk menjalankan aplikasi lokal atau menggunakan sumber daya AWS , ikuti langkah-langkah dalam file readme aplikasi sampel. Petunjuk untuk menggunakan aplikasi sampel untuk menghasilkan penelusuran X-Ray ada pada [contoh tutorial aplikasi](xray-scorekeep.md).
## Memulai
Untuk memulai dengan X-Ray agen instrumentasi otomatis Java pada aplikasi Anda sendiri, ikuti langkah-langkah ini.
1. Jalankan daemon X-Ray di lingkungan Anda. Untuk informasi selengkapnya, lihat [AWS X-Ray daemon](xray-daemon.md).
1. Unduh [distribusi agen terbaru](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip). Unzip arsip dan perhatikan lokasinya dalam sistem file Anda. Isinya akan terlihat seperti berikut.
```
disco
├── disco-java-agent.jar
└── disco-plugins
├── aws-xray-agent-plugin.jar
├── disco-java-agent-aws-plugin.jar
├── disco-java-agent-sql-plugin.jar
└── disco-java-agent-web-plugin.jar
```
1. Modifikasi argumen JVM aplikasi Anda untuk memasukkan hal-hal berikut, yang memungkinkan agen. Pastikan argumen `-javaagent` ditempatkan *sebelum* argumen `-jar` jika berlaku. Proses untuk memodifikasi argumen JVM bervariasi tergantung pada alat dan kerangka kerja yang Anda gunakan untuk meluncurkan server Java Anda. Konsultasikan dokumentasi kerangka kerja server Anda untuk panduan khusus.
```
-javaagent://disco-java-agent.jar=pluginPath=//disco-plugins
```
1. Untuk menentukan bagaimana nama aplikasi Anda muncul di konsol X-Ray, atur variabel `AWS_XRAY_TRACING_NAME` lingkungan atau properti `com.amazonaws.xray.strategy.tracingName` sistem. Jika tidak ada nama yang diberikan, nama default digunakan.
1. Mulai ulang server atau kontainer Anda. Permintaan masuk dan panggilan hilir mereka sekarang ditelusuri. Jika Anda tidak melihat hasil yang diharapkan, lihat [Pemecahan masalah](#XRayAutoInstrumentationAgent-Troubleshooting).
## Konfigurasi
Agen X-Ray dikonfigurasi oleh file JSON eksternal yang disediakan pengguna. Secara default, file ini adalah akar dari classpath pengguna (misalnya, di `resources` direktori) bernama `xray-agent.json`. Anda dapat mengonfigurasi lokasi kustom untuk file konfigurasi dengan menetapkan sistem properti `com.amazonaws.xray.configFile` menuju sistem file jalur absolut dari file konfigurasi Anda.
Contoh file konfigurasi ditampilkan nanti.
```
{
"serviceName": "XRayInstrumentedService",
"contextMissingStrategy": "LOG_ERROR",
"daemonAddress": "127.0.0.1:2000",
"tracingEnabled": true,
"samplingStrategy": "CENTRAL",
"traceIdInjectionPrefix": "prefix",
"samplingRulesManifest": "/path/to/manifest",
"awsServiceHandlerManifest": "/path/to/manifest",
"awsSdkVersion": 2,
"maxStackTraceLength": 50,
"streamingThreshold": 100,
"traceIdInjection": true,
"pluginsEnabled": true,
"collectSqlQueries": false
}
```
### Spesifikasi konfigurasi
Tabel berikut mencakup nilai-nilai yang valid untuk setiap bidang. Nama properti merupakan kasus sensitif, namun tidak untuk kuncinya. Untuk properti yang dapat diganti oleh variabel lingkungan dan properti sistem, urutan prioritas selalu variabel lingkungan, lalu properti sistem, dan kemudian file konfigurasi. Untuk informasi tentang properti yang dapat Anda ganti, lihat[Variabel-variabel lingkungan](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars). Semua bidang bersifat opsional.
| Nama properti | Tipe | Nilai yang valid | Deskripsi | Variabel Lingkungan | Properti sistem | Default |
| --- | --- | --- | --- | --- | --- | --- |
| serviceName | String | Semua string | Nama layanan terinstrumentasi Anda karena akan muncul di konsol X-Ray. | AWS\_XRAY\_TRACING\_NAME | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService |
| contextMissingStrategy | String | LOG\_ERROR, IGNORE\_ERROR | Tindakan yang diambil oleh agen ketika mencoba untuk menggunakan konteks segmen X-Ray tetapi tidak ada yang hadir. | AWS\_XRAY\_CONTEXT\_MISSING | com.amazonaws.xray.strategy. contextMissingStrategy | LOG\_ERROR |
| daemonAddress | String | Alamat IP dan port terformat, atau daftar alamat TCP dan UDP | Alamat yang digunakan agen untuk berkomunikasi dengan daemon X-Ray. | AWS\_XRAY\_DAEMON\_ALAMAT | com.amazonaws.xray.emitter.daemonAddress | 127.0.0. 1:2000 |
| tracingEnabled | Boolean | Betul, Salah | Mengaktifkan instrumentasi oleh agen X-Ray. | AWS\_XRAY\_TRACING\_ENABLED | com.amazonaws.xray.tracingEnabled | BETUL |
| samplingStrategy | String | PUSAT, LOKAL, TIDAK ADA, SEMUA | Strategi sampling yang digunakan oleh agen. SEMUA menangkap semua permintaan, TIDAK ADA menangkap tidak ada permintaan. Lihat [aturan pengambilan sampel](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling). | N/A | N/A | PUSAT |
| traceIdInjectionAwalan | String | Semua string | Termasuk awalan yang disediakan sebelum jejak yang disuntikkan IDs di log. | N/A | N/A | Tidak ada (string kosong) |
| samplingRulesManifest | String | Path file absolut | Path pada file aturan sampling kustom yang akan digunakan sebagai sumber aturan sampling bagi strategi pengambilan sampel lokal, atau aturan mundur untuk strategi pusat. | N/A | N/A | [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json) |
| awsServiceHandlerManifestasi | String | Path file absolut | Path menuju parameter kustom mengizinkan daftar, yang menangkap informasi tambahan dari klien AWS SDK. | N/A | N/A | [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json) |
| awsSdkVersion | Bilangan Bulat | 1, 2 | Versi [AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/index.html) yang Anda gunakan. Diabaikan jika `awsServiceHandlerManifest` tidak diatur juga. | N/A | N/A | 2 |
| maxStackTracePanjangnya | Bilangan Bulat | Bilangan bulat non-negatif | Baris maksimum penelusuran tumpukan untuk mencatat dalam penelusuran. | N/A | N/A | 50 |
| streamingThreshold | Bilangan Bulat | Bilangan bulat non-negatif | Setelah setidaknya banyak subsegmen ini ditutup, mereka dialirkan ke daemon out-of-band untuk menghindari potongan yang terlalu besar. | N/A | N/A | 100 |
| traceIdInjection | Boolean | Betul, Salah | Mengaktifkan injeksi ID penelusuran X-Ray ke log jika dependensi dan konfigurasi yang dijelaskan dalam [konfigurasi pencatatan](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging)juga ditambahkan. Jika tidak, tidak melakukan apa-apa. | N/A | N/A | BETUL |
| pluginsEnabled | Boolean | Betul, Salah | Mengaktifkan plugin yang merekam metadata tentang AWS lingkungan tempat Anda beroperasi. Lihat [plugin](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins). | N/A | N/A | BETUL |
| collectSqlQueries | Boolean | Betul, Salah | Mencatat string kueri SQL di subsegment SQL dengan basis upaya-terbaik. | N/A | N/A | SALAH |
| contextPropagation | Boolean | Betul, Salah | Secara otomatis menyebarluaskan konteks X-Ray antara thread jika benar. Jika tidak, menggunakan Thread Local untuk menyimpan konteks dan propagasi manual di seluruh utas diperlukan. | N/A | N/A | BETUL |
### Konfigurasi log
Tingkat log agen X-Ray dapat dikonfigurasi dengan cara yang sama seperti X-Ray SDK for Java. Lihat [Pencatatan log](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) untuk informasi selengkapnya tentang mengonfigurasi log dengan X-Ray SDK for Java.
### Instrumentasi manual
Jika Anda ingin melakukan instrumentasi manual selain agen instrumentasi otomatis, tambahkan SDK X-Ray sebagai sebuah dependensi pada proyek Anda. Perhatikan bahwa filter servlet kustom SDK disebutkan dalam [Menelusuri Permintaan Masuk](xray-sdk-java-filters.md) tidak kompatibel dengan agen X-Ray.
**catatan**
Anda harus menggunakan versi terbaru SDK X-Ray untuk melakukan instrumentasi manual saat menggunakan agen juga.
Jika Anda bekerja di sebuah proyek Maven, tambahkan dependensi berikut untuk file `pom.xml` Anda.
```
com.amazonaws
aws-xray-recorder-sdk-core
2.11.0
```
Jika Anda bekerja di sebuah proyek Maven, tambahkan dependensi berikut untuk file `build.gradle` Anda.
```
implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0'
```
Anda dapat menambahkan [subsegmen kustom](xray-sdk-java-subsegments.md) selain [anotasi, metadata, dan pengguna IDs](xray-sdk-java-segment.md) saat menggunakan agen, seperti yang Anda lakukan dengan SDK normal. Agen secara otomatis menyebarkan konteks di thread, sehingga tidak ada workarounds untuk menyebarkan konteks yang diperlukan ketika bekerja dengan aplikasi multithreaded.
## Pemecahan masalah
Karena agen menawarkan instrumentasi otomatis sepenuhnya, akan sulit untuk mengidentifikasi akar penyebab masalah ketika Anda mengalami masalah. Jika agen X-Ray tidak bekerja seperti yang Anda harapkan, tinjau masalah dan solusi berikut ini. Agen X-Ray dan SDK menggunakan Jakarta Commons Logging (JCL). Untuk melihat output logging, pastikan bahwa jembatan yang menghubungkan JCL ke backend logging Anda ada di classpath, seperti pada contoh berikut: atau. `log4j-jcl` `jcl-over-slf4j`
### Masalah: Saya telah mengaktifkan agen Java pada aplikasi saya tetapi tidak ada apa pun di konsol X-Ray
**Apakah daemon X-Ray berjalan pada mesin yang sama?**
Jika tidak, lihat [Dokumentasi daemon X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html)untuk mengaturnya.
**Di log aplikasi Anda, apakah Anda melihat pesan seperti “Inisialisasi perekam agen X-Ray”?**
Jika Anda telah menambahkan agen dengan benar ke aplikasi Anda, pesan ini dicatat pada tingkat INFO saat aplikasi Anda dimulai, sebelum mulai menerima permintaan. Jika pesan ini tidak ada, maka agen Java tidak berjalan dengan proses Java Anda. Pastikan Anda telah mengikuti semua langkah pengaturan dengan benar tanpa adanya kesalahan ketik.
**Di log aplikasi Anda, apakah Anda melihat beberapa pesan kesalahan yang mengatakan sesuatu seperti “Menekan AWS X-Ray konteks yang hilang pengecualian”?**
Kesalahan ini terjadi karena agen mencoba untuk instrumen permintaan hilir, seperti permintaan AWS SDK atau kueri SQL, tetapi agen tidak dapat secara otomatis membuat segmen. Jika Anda melihat banyak kesalahan ini, agen mungkin bukan alat terbaik untuk kasus penggunaan Anda dan Anda mungkin ingin mempertimbangkan instrumentasi manual dengan SDK X-Ray sebagai gantinya. Selain itu, Anda dapat mengaktifkan X-Ray SDK [debug log](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) untuk melihat pelacakan tumpukan tempat pengecualian konteks hilang terjadi. Anda dapat membungkus bagian-bagian kode Anda dengan segmen kustom, yang harus menyelesaikan kesalahan ini. Untuk contoh membungkus permintaan hilir dengan segmen kustom, lihat kode sampel di [instrumenting kode startup](scorekeep-startup.md).
### Masalah: Beberapa segmen yang saya harapkan tidak muncul di konsol X-Ray
**Apakah aplikasi Anda menggunakan multithreading?**
Jika beberapa segmen yang Anda harapkan untuk dibuat tidak muncul di konsol Anda, latar belakang thread dalam aplikasi Anda mungkin menjadi penyebabnya. Jika aplikasi Anda melakukan tugas menggunakan utas latar belakang yang “fire and forget”, seperti melakukan panggilan satu kali ke fungsi Lambda dengan AWS SDK, atau melakukan polling beberapa titik akhir HTTP secara berkala, itu mungkin membingungkan agen saat menyebarkan konteks di seluruh utas. Untuk memverifikasi masalah Anda ini, aktifkan log debug X-Ray SDK dan periksa pesan seperti: *Tidak memancarkan segmen bernama seperti induknya di-progress subsegment*. Untuk mengatasi hal ini, Anda dapat mencoba bergabung dengan thread latar belakang sebelum server Anda kembali untuk memastikan semua pekerjaan yang dilakukan di dalamnya dicatat. Atau, Anda dapat mengatur konfigurasi `contextPropagation` agen ke `false` untuk menonaktifkan propagasi konteks di thread latar belakang. Jika Anda melakukan ini, Anda harus secara manual melakukan instrumen utas tersebut dengan segmen kustom atau mengabaikan konteks pengecualian yang hilang yang mereka hasilkan.
**Sudahkah Anda mengatur aturan pengambilan sampel?**
Jika segmen yang tampak acak atau tidak terduga muncul di konsol X-Ray, atau segmen yang Anda harapkan berada di konsol, Anda mungkin mengalami masalah pengambilan sampel. Agen X-Ray menerapkan pengambilan sampel terpusat ke semua segmen yang dibuatnya, menggunakan aturan dari konsol X-Ray. Aturan default adalah 1 segmen per detik, ditambah 5% dari segmen sesudahnya, dijadikan sampel. Ini berarti segmen yang dibuat cepat dengan agen mungkin tidak dijadikan sampel. Untuk mengatasi masalah ini, Anda harus membuat aturan pengambilan sampel kustom di konsol X-Ray yang secara tepat mencoba segmen yang diinginkan. Untuk informasi selengkapnya, lihat [sampling](xray-console-sampling.md).