AWS X-Ray agen instrumentasi otomatis Java

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 respons-permintaan, Anda mungkin ingin mempertimbangkan instrumentasi manual dengan SDK sebagai gantinya. 

Agen X-Ray dibangun menggunakan toolkit Distributed Systems Comprehension, atau DisCo. DisCo adalah kerangka open source untuk membangun agen Java yang dapat digunakan dalam sistem terdistribusi. Meskipun tidak perlu memahami DisCo untuk menggunakan agen X-Ray, Anda dapat mempelajari lebih lanjut tentang proyek ini dengan mengunjungi beranda di GitHub. Agen X-Ray juga sepenuhnya bersumber terbuka. Untuk melihat kode sumber, memberikan kontribusi, atau mengangkat masalah tentang agen, kunjungi repositorinya di. GitHub

Aplikasi sampel

Aplikasi eb-java-scorekeepsampel 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.

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 lebih lanjut, lihat daemon X-Ray.

2. Unduh distribusi agen terbaru. 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

3. 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:/<path-to-disco>/disco-java-agent.jar=pluginPath=/<path-to-disco>/disco-plugins

4. 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.

5. Mulai ulang server atau kontainer Anda. Permintaan masuk dan panggilan hilir mereka sekarang ditelusuri. Jika Anda tidak melihat hasil yang diharapkan, lihat Pemecahan Masalah.

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. Lihat Variabel Lingkungan untuk informasi tentang properti yang dapat Anda ganti. 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	X RayInstrumentedService
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_ADDRESS	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.	N/A	N/A	PUSAT
traceIdInjectionAwalan	String	Semua string	Termasuk prefiks yang disediakan sebelum ID penelusuran teriinjeksi dalam 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
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
awsSdkVersion	Bilangan Bulat	1, 2	Versi AWS SDK for Java 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 pencatatanjuga 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.	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 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 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.

<dependencies> 
  <dependency> 
    <groupId>com.amazonaws</groupId> 
    <artifactId>aws-xray-recorder-sdk-core</artifactId> 
    <version>2.11.0</version> 
  </dependency> 
  </dependencies>

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 khusus selain anotasi, metadata, dan ID pengguna 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-Rayuntuk 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 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.

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 <NAME > 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 Mengonfigurasi aturan pengambilan sampel diJelajahi konsol X-Ray.