Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # AWS X-Ray SDK for 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 X-Ray SDK for Java adalah serangkaian pustaka untuk aplikasi web Java yang menyediakan kelas dan metode untuk menghasilkan dan mengirim pelacakan data 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. X-Ray SDK for Java merupakan 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-java)- xray-sdk-java Mulai dengan [menambahkan `AWSXRayServletFilter` sebagai filter servlet](xray-sdk-java-filters.md) untuk pelacakan permintaan yang masuk. Filter servlet membuat [segmen](xray-concepts.md#xray-concepts-segments). 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 bahwa aplikasi Anda melempar sementara segmen terbuka. Mulai rilis 1.3, Anda dapat instrumen aplikasi Anda menggunakan [berorientasi aspek pemrograman (AOP) di Spring](xray-sdk-java-aop-spring.md). Artinya, Anda dapat menginstruksikan aplikasi Anda, saat sedang berjalan AWS, tanpa menambahkan kode apa pun ke runtime aplikasi Anda. Selanjutnya, gunakan X-Ray SDK for Java untuk menginstrumentasikan klien AWS SDK untuk Java Anda [dengan menyertakan submodul SDK Instrumentor dalam](#xray-sdk-java-dependencies) konfigurasi build Anda. Setiap kali Anda melakukan panggilan ke hilir Layanan AWS atau sumber daya dengan klien yang diinstrumentasi, SDK akan mencatat informasi tentang panggilan di 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. Jika Anda tidak ingin menginstrumentasikan semua panggilan hilir Layanan AWS, Anda dapat meninggalkan submodul Instrumentor dan memilih klien mana yang akan diinstrumensikan. Instrumen klien individu [dengan menambahkan `TracingHandler`](xray-sdk-java-awssdkclients.md) ke klien layanan AWS SDK. Submodul X-Ray SDK for Java lainnya menyediakan instrumentasi untuk panggilan hilir ke web HTTP APIs dan database SQL. Anda dapat [menggunakan X-Ray SDK for Java dari versi `HTTPClient` dan `HTTPClientBuilder`](xray-sdk-java-httpclients.md) di submodul Apache HTTP untuk instrumen klien Apache HTTP. Untuk instrumen kueri SQL, [tambahkan interceptor SDK pada sumber data Anda](xray-sdk-java-sqlclients.md). Setelah Anda mulai menggunakan SDK, sesuaikan perilakunya dengan [mengonfigurasi filter perekam dan servlet](xray-sdk-java-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-java-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 banyak subsegmen, satu untuk setiap panggilan yang dibuat dengan klien berinstrumen. Anda dapat mengatur dan mengelompokkan subsegmen dengan membungkus panggilan klien di [subsegmen kustom](xray-sdk-java-subsegments.md). Anda dapat membuat subsegmen kustom untuk seluruh fungsi atau bagian dari kode apa pun, dan mencatat metadata dan anotasi pada subsegmen alih-alih menulis semuanya pada segmen induk. ## Submodul Anda dapat mengunduh X-Ray SDK for Java dari Maven. X-Ray SDK for Java dibagi menjadi submodul dengan kasus penggunaan, dengan tagihan bahan untuk manajemen versi: + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/) (wajib) – Fungsi dasar untuk membuat segmen dan transmisi segmen. Termasuk `AWSXRayServletFilter` untuk instrumenting permintaan masuk. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/)— Instrumen panggilan untuk Layanan AWS dilakukan dengan AWS SDK untuk Java klien dengan menambahkan klien penelusuran sebagai penangan permintaan. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/)— Instrumen panggilan untuk Layanan AWS dilakukan dengan klien AWS SDK untuk Java 2.2 dan yang lebih baru dengan menambahkan klien penelusuran sebagai interekeptor permintaan. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/)— Dengan`aws-xray-recorder-sdk-aws-sdk`, instrumen semua AWS SDK untuk Java klien secara otomatis. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/)— Dengan`aws-xray-recorder-sdk-aws-sdk-v2`, instrumen semua klien AWS SDK untuk Java 2.2 dan yang lebih baru secara otomatis. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/) – Instrumen panggilan HTTP keluar yang dibuat dengan klien HTTP Apache. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/)- Menyediakan pencegat untuk aplikasi Spring AOP Framework. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/) – Instrumen panggilan keluar ke basis data PostgreSQL yang dibuat dengan JDBC. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/) – Instrumen panggilan keluar ke basis data MySQL yang dibuat dengan JDBC. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/) – Menyediakan tagihan materi yang dapat Anda gunakan untuk menentukan versi yang akan digunakan untuk semua submodul. + [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/)— Publikasikan CloudWatch metrik Amazon tanpa sampel dari segmen X-Ray yang Anda kumpulkan. Jika Anda menggunakan Maven atau Gradle untuk membangun aplikasi Anda, [Menambahkan X-Ray SDK for Java ke konfigurasi pembuatan Anda](#xray-sdk-java-dependencies). Untuk dokumentasi referensi kelas SDK dan metode, lihat [AWS X-Ray Referensi API SDK for Java](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc). ## Persyaratan X-Ray SDK for Java memerlukan Java 8 atau lebih baru, Servlet API 3, SDK, AWS dan Jackson. SDK tergantung pada pustaka berikut saat kompilasi dan waktu aktif: + AWS SDK for Java versi 1.11.398 atau yang lebih baru + API Servlet 3.1.0 Dependensi ini dinyatakan dalam file `pom.xml` dan disertakan secara otomatis jika Anda membangun menggunakan Maven atau Gradle. Jika Anda menggunakan pustaka yang disertakan dalam X-Ray SDK for Java, Anda harus menggunakan versi yang disertakan. Misalnya, jika Anda sudah bergantung pada Jackson saat waktu aktif dan termasuk file JAR dalam deployment Anda untuk ketergantungan itu, Anda harus menghapus file-file JAR karena SDK JAR termasuk versi sendiri dari Jackson pustaka. ## Manajemen dependensi X-Ray SDK for Java tersedia dari Maven: + **Grup** - `com.amazonaws` + **Artifact** – `aws-xray-recorder-sdk-bom` + **Versi** - `2.11.0` Jika Anda menggunakan Maven untuk membangun aplikasi Anda, menambahkan SDK sebagai ketergantungan di file `pom.xml` Anda. **Example pom.xml - dependensi** ``` com.amazonaws aws-xray-recorder-sdk-bom 2.11.0 pom import com.amazonaws aws-xray-recorder-sdk-core com.amazonaws aws-xray-recorder-sdk-apache-http com.amazonaws aws-xray-recorder-sdk-aws-sdk com.amazonaws aws-xray-recorder-sdk-aws-sdk-instrumentor com.amazonaws aws-xray-recorder-sdk-sql-postgres com.amazonaws aws-xray-recorder-sdk-sql-mysql ``` Untuk Gradle, tambahkan SDK sebagai dependensi waktu kompilasi di file `build.gradle`. **Example build.gradle – dependensi** ``` dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile("org.springframework.boot:spring-boot-starter-test") compile("com.amazonaws:aws-java-sdk-dynamodb") compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") compile("com.amazonaws:aws-xray-recorder-sdk-apache-http") compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres") compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql") testCompile("junit:junit:4.11") } dependencyManagement { imports { mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39') mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0') } } ``` Jika Anda menggunakan Elastic Beanstalk untuk mendeploy aplikasi Anda, Anda dapat menggunakan Maven atau Gradle untuk membangun on-instans setiap kali Anda mendeploy, alih-alih membangun dan mengunggah arsip besar yang mencakup semua dependensi Anda. Lihat [aplikasi sampel](xray-scorekeep.md) sebagai contoh yang menggunakan Gradle. # 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\$1XRAY\$1TRACING\$1NAME | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService | | contextMissingStrategy | String | LOG\$1ERROR, IGNORE\$1ERROR | Tindakan yang diambil oleh agen ketika mencoba untuk menggunakan konteks segmen X-Ray tetapi tidak ada yang hadir. | AWS\$1XRAY\$1CONTEXT\$1MISSING | com.amazonaws.xray.strategy. contextMissingStrategy | LOG\$1ERROR | | daemonAddress | String | Alamat IP dan port terformat, atau daftar alamat TCP dan UDP | Alamat yang digunakan agen untuk berkomunikasi dengan daemon X-Ray. | AWS\$1XRAY\$1DAEMON\$1ALAMAT | com.amazonaws.xray.emitter.daemonAddress | 127.0.0. 1:2000 | | tracingEnabled | Boolean | Betul, Salah | Mengaktifkan instrumentasi oleh agen X-Ray. | AWS\$1XRAY\$1TRACING\$1ENABLED | 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). # Mengonfigurasi X-Ray SDK for 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 X-Ray SDK for Java mencakup kelas bernama `AWSXRay` yang menyediakan pencatat global. Ini adalah `TracingHandler` yang dapat Anda gunakan untuk menginstrumentasikan kode Anda. Anda dapat mengonfigurasi pencatat global untuk menyesuaikan `AWSXRayServletFilter` yang membuat segmen untuk panggilan HTTP masuk. **Topics** + [Plugin layanan](#xray-sdk-java-configuration-plugins) + [Aturan pengambilan sampel](#xray-sdk-java-configuration-sampling) + [Pencatatan log](#xray-sdk-java-configuration-logging) + [Listener segmen](#xray-sdk-java-configuration-listeners) + [Variabel-variabel lingkungan](#xray-sdk-java-configuration-envvars) + [Properti sistem](#xray-sdk-java-configuration-sysprops) ## 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. + Amazon EKS — `EKSPlugin` menambahkan ID kontainer, nama cluster, ID pod, dan Grup CloudWatch Log. ![\[Data sumber daya segmen dengan Amazon EC2 dan plugin Elastic Beanstalk.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources.png) Untuk menggunakan plugin, hubungi `withPlugin` di `AWSXRayRecorderBuilder` Anda. **Example src/main/java/scorekeep/WebConfig.java - perekam** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } } ``` 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 memberikan aturan cadangan di Spring, konfigurasi pencatat global dengan `CentralizedSamplingStrategy` di kelas konfigurasi. **Example src/main/java/myapp/WebConfig.java - konfigurasi perekam** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); @Configuration public class WebConfig { static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } ``` Untuk Tomcat, tambahkan listener yang memperluas `ServletContextListener` dan mendaftarkan listener di pendeskripsi deployment. **Example src/com/myapp/web/Startup.jawa** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html); import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html); import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html); import java.net.URL; import javax.servlet.ServletContextEvent; import javax.servlet.ServletContextListener; public class Startup implements ServletContextListener { @Override public void contextInitialized(ServletContextEvent event) { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()); URL ruleFile = Startup.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } @Override public void contextDestroyed(ServletContextEvent event) { } } ``` **Example WEB-INF/web.xml** ``` ... com.myapp.web.Startup ``` Untuk menggunakan aturan lokal saja, ganti `CentralizedSamplingStrategy` dengan `LocalizedSamplingStrategy`. ``` builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); ``` ## Pencatatan log Secara default, SDK menghasilkan pesan tingkat `ERROR` untuk log aplikasi Anda. Anda dapat mengaktifkan pencatatan tingkat debug di SDK untuk menghasilkan log lebih terperinci ke berkas log aplikasi Anda. Tingkat log yang valid adalah `DEBUG`, `INFO`, `WARN`, `ERROR`, dan`FATAL`. Tingkat log `FATAL` mengheningkan semua pesan log karena SDK tidak mencatat di tingkat fatal. **Example application.properties** Atur tingkat pencatatan dengan properti `logging.level.com.amazonaws.xray`. ``` logging.level.com.amazonaws.xray = DEBUG ``` Gunakan log debug untuk mengidentifikasi masalah, seperti subsegmen yang tidak tertutup, saat Anda [menghasilkan subsegmen secara manual](xray-sdk-java-subsegments.md). ### Injeksi ID pelacakan ke log Untuk mengekspos ID pelacakan yang memenuhi syarat ke pernyataan log Anda, Anda dapat menyuntikkan ID ke dalam konteks diagnostik yang dipetakan (MDC). Menggunakan antarmuka `SegmentListener`, metode dipanggil dari pencatat X-Ray selama peristiwa siklus hidup segmen. Ketika segmen atau subsegmen dimulai, ID pelacakan yang memenuhi syarat disuntikkan ke MDC dengan kunci`AWS-XRAY-TRACE-ID`. Ketika segmen tersebut berakhir, kunci akan dihapus dari MDC. Hal ini memperlihatkan ID pelacakan ke pustaka pencatatan yang digunakan. Ketika subsegmen berakhir, ID induknya disuntikkan ke MDC. **Example ID pelacakan yang memenuhi syarat** ID yang memenuhi syarat direpresentasikan sebagai `TraceID@EntityID` ``` 1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3 ``` Fitur ini bekerja dengan aplikasi Java yang diinstrumentasi dengan AWS X-Ray SDK for Java, dan mendukung konfigurasi logging berikut: + SLF4J front-end API dengan backend Logback + SLF4API front-end J dengan backend Log4J2 + API front-end Log4J2 dengan backend Log4J2 Lihat tab berikut untuk kebutuhan setiap front end dan backend. ------ #### [ SLF4J Frontend ] 1. Tambahkan dependensi Maven berikut ke proyek Anda: ``` com.amazonaws aws-xray-recorder-sdk-slf4j 2.11.0 ``` 1. Sertakan metode `withSegmentListener` ketika membangun `AWSXRayRecorder`. Ini menambahkan `SegmentListener` kelas, yang secara otomatis menyuntikkan jejak baru IDs ke SLF4 J MDC. `SegmentListener` mengambil string opsional sebagai parameter untuk mengonfigurasi prefiks pernyataan log. Prefiks dapat dikonfigurasi dengan cara berikut: + **Tidak ada** – Menggunakan prefiks `AWS-XRAY-TRACE-ID` default. + **Kosong** - Menggunakan string kosong (misalnya `""`). + **Kustom** - Menggunakan prefiks kustom sebagaimana ditentukan dalam string. **Example Pernyataan `AWSXRayRecorderBuilder`** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Log4J2 front end ] 1. Tambahkan dependensi Maven berikut ke proyek Anda: ``` com.amazonaws aws-xray-recorder-sdk-log4j 2.11.0 ``` 1. Sertakan metode `withSegmentListener` ketika membangun `AWSXRayRecorder`. Ini akan menambahkan `SegmentListener` kelas, yang secara otomatis menyuntikkan jejak baru yang sepenuhnya memenuhi syarat IDs ke SLF4 J MDC. `SegmentListener` mengambil string opsional sebagai parameter untuk mengonfigurasi prefiks pernyataan log. Prefiks dapat dikonfigurasi dengan cara berikut: + **Tidak ada** – Menggunakan prefiks `AWS-XRAY-TRACE-ID` default. + **Kosong** - Menggunakan string kosong (misalnya `""`) dan menghapus prefiks. + **Kustom** - Menggunakan prefiks kustom sebagaimana ditentukan dalam string. **Example Pernyataan `AWSXRayRecorderBuilder`** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX")); ``` ------ #### [ Logback backend ] Untuk memasukkan ID pelacakan ke log acara Anda, Anda harus mengubah `PatternLayout` pencatat, yang membuat format setiap pernyataan pencatatan. 1. Temukan tempat `patternLayout` dikonfigurasi. Anda dapat melakukan ini secara terprogram, atau melalui file konfigurasi XML. Untuk mempelajari selengkapnya, lihat [Konfigurasi Longback](http://logback.qos.ch/manual/configuration.html). 1. Sisipkan `%X{AWS-XRAY-TRACE-ID}` dimanapun di `patternLayout` untuk memasukkan ID pelacakan dalam laporan pencatatan mendatang. `%X{}`menunjukkan bahwa Anda mengambil nilai dengan kunci yang disediakan dari MDC. Untuk mempelajari lebih lanjut tentang PatternLayouts Logback, lihat [PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout). ------ #### [ Log4J2 backend ] 1. Temukan tempat `patternLayout` dikonfigurasi. Anda dapat melakukan ini secara terprogram, atau melalui file konfigurasi yang ditulis dalam format XML, JSON, YAML, atau properti. Untuk mempelajari selengkapnya tentang mengonfigurasi Log4J2 melalui file konfigurasi, lihat [Konfigurasi](https://logging.apache.org/log4j/2.x/manual/configuration.html). Untuk mempelajari selengkapnya tentang mengonfigurasi Log4J2 secara terprogram, lihat [Konfigurasi Terprogram](https://logging.apache.org/log4j/2.x/manual/customconfig.html). 1. Sisipkan `%X{AWS-XRAY-TRACE-ID}` dimanapun di `PatternLayout` untuk memasukkan ID pelacakan dalam laporan pencatatan mendatang. `%X{}`menunjukkan bahwa Anda mengambil nilai dengan kunci yang disediakan dari MDC. [Untuk mempelajari selengkapnya PatternLayouts di Log4J2, lihat Pattern Layout.](https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout) ------ **Contoh Injeksi ID pelacakan** Berikut menunjukkan string `PatternLayout` yang diubah untuk menyertakan pelacakan ID. ID pelacakan dicetak setelah nama thread (`%t`) dan sebelum tingkat log (`%-5p`). **Example `PatternLayout` Dengan Injeksi ID** ``` %d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n ``` AWS X-Ray secara otomatis mencetak kunci dan ID jejak dalam pernyataan log untuk memudahkan penguraian. Berikut ini menunjukkan pernyataan log menggunakan `PatternLayout` yang diubah. **Example Pernyataan log dengan injeksi ID** ``` 2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here ``` Pesan pencatatan itu sendiri ditempatkan dalam pola `%m`dan diatur saat memanggil pencatat. ## Listener segmen Pendengar segmen adalah antarmuka untuk mencegat peristiwa siklus hidup seperti awal dan akhir segmen yang dihasilkan oleh. `AWSXRayRecorder` Pelaksanaan fungsi peristiwa listener segmen mungkin bertujuan untuk menambahkan anotasi yang sama untuk semua subsegmen ketika dibuat dengan [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-), mencatat pesan setelah setiap segmen dikirim ke daemon menggunakan [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-), atau untuk mencatat kueri yang dikirim oleh penghalang SQL menggunakan [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-) untuk memverifikasi subsegmen sebagai perwakilan kueri SQL, menambahkan metadata tambahan jika memang demikian. Untuk melihat daftar lengkap fungsi `SegmentListener`, kunjungi dokumentasi untuk [API SDK for Java Pencatat AWS X-Ray](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html). Contoh berikut menunjukkan cara menambahkan anotasi yang konsisten untuk semua subsegmen pada pembuatan dengan [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) dan untuk mencetak pesan log di akhir setiap segmen dengan [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-). **Example MySegmentListener.jawa** ``` import com.amazonaws.xray.entities.Segment; import com.amazonaws.xray.entities.Subsegment; import com.amazonaws.xray.listeners.SegmentListener; public class MySegmentListener implements SegmentListener { ..... @Override public void onBeginSubsegment(Subsegment subsegment) { subsegment.putAnnotation("annotationKey", "annotationValue"); } @Override public void afterEndSegment(Segment segment) { // Be mindful not to mutate the segment logger.info("Segment with ID " + segment.getId()); } } ``` Listener segmen kustom ini kemudian direferensikan ketika membangun `AWSXRayRecorder`. **Example AWSXRayRecorderBuilder pernyataan** ``` AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard().withSegmentListener(new MySegmentListener()); ``` ## Variabel-variabel lingkungan Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for Java. SDK mendukung variabel berikut. + `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. + `AWS_XRAY_DAEMON_ADDRESS` – Mengatur host dan port pendengar 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_LOG_GROUP`— Tetapkan nama grup log ke grup log yang terkait dengan aplikasi Anda. Jika grup log Anda menggunakan AWS akun dan wilayah yang sama dengan aplikasi Anda, X-Ray akan secara otomatis mencari data segmen aplikasi Anda menggunakan grup log yang ditentukan ini. Untuk informasi selengkapnya tentang grup log, lihat [Bekerja dengan grup log dan aliran](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html). + `AWS_XRAY_TRACING_NAME` – Menetapkan nama layanan yang digunakan SDK untuk segmen. Menimpa nama layanan yang Anda tetapkan pada [strategi penamaan segmen](xray-sdk-java-filters.md#xray-sdk-java-filters-naming) filter servlet. Variabel lingkungan mengesampingkan [Properti sistem](#xray-sdk-java-configuration-sysprops) yang setara dan nilai yang ditetapkan dalam kode. ## Properti sistem Anda dapat menggunakan properti sistem sebagai alternatif khusus JVM bagi [Variabel lingkungan](#xray-sdk-java-configuration-envvars). File mendukung properti berikut: + `com.amazonaws.xray.strategy.tracingName` – Setara dengan `AWS_XRAY_TRACING_NAME`. + `com.amazonaws.xray.emitters.daemonAddress` – Setara dengan `AWS_XRAY_DAEMON_ADDRESS`. + `com.amazonaws.xray.strategy.contextMissingStrategy` – Setara dengan `AWS_XRAY_CONTEXT_MISSING`. Jika kedua properti sistem dan variabel lingkungan setara ditetapkan, nilai variabel lingkungan digunakan. Salah satu metode menimpa nilai yang diatur dalam kode. # Menelusuri permintaan yang masuk dengan X-Ray SDK for 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 Anda dapat menggunakan X-Ray SDK untuk melacak permintaan HTTP masuk yang disajikan aplikasi Anda pada instans EC2 di Amazon EC2,, AWS Elastic Beanstalk atau Amazon ECS. Gunakan `Filter` untuk menginstrumentasikan permintaan HTTP yang masuk. Ketika Anda menambahkan filter servlet X-Ray ke aplikasi Anda, X-Ray SDK for Java membuat segmen untuk setiap permintaan sampel. Segmen ini mencakup waktu, metode, dan disposisi permintaan HTTP. Instrumentasi tambahan membuat subsegmen pada segmen ini. **catatan** Untuk AWS Lambda fungsi, Lambda membuat segmen untuk setiap permintaan sampel. Untuk informasi selengkapnya, lihat [AWS Lambda dan AWS X-Ray](xray-services-lambda.md). 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 yang berisi bidang `x_forwarded_for` ditetapkan ke `true`, IP klien diambil dari header `X-Forwarded-For` dalam permintaan HTTP. Penangan pesan membuat segmen untuk setiap permintaan masuk dengan blok `http` yang berisi informasi berikut: + **Metode HTTP** – DAPATKAN, POSTING, LETAKKAN, HAPUS, 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 filter penelusuran ke aplikasi Anda (Tomcat)](#xray-sdk-java-filters-tomcat) + [Menambahkan filter penelusuran ke aplikasi Anda (spring)](#xray-sdk-java-filters-spring) + [Mengonfigurasi strategi penamaan segmen](#xray-sdk-java-filters-naming) ## Menambahkan filter penelusuran ke aplikasi Anda (Tomcat) Untuk Tomcat, tambahkan `` ke file proyek `web.xml`. Gunakan parameter `fixedName` untuk menentukan [nama layanan](#xray-sdk-java-filters-naming) untuk diterapkan ke segmen yang dibuat untuk permintaan masuk. **Example WEB-INF/web.xml - Tomcat** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter fixedName MyApp AWSXRayServletFilter * ``` ## Menambahkan filter penelusuran ke aplikasi Anda (spring) Untuk Spring, tambahkan `Filter` ke kelas `WebConfig` Anda. Teruskan nama segmen ke konstruktor [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) sebagai string. **Example src/main/java/myapp/WebConfig.java - musim semi** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## 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 Anda memulai filter servlet, seperti yang ditampilkan dalam [bagian sebelumnya](#xray-sdk-java-filters-tomcat). Ini memiliki efek yang sama seperti membuat fixed [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)dengan memanggil `SegmentNamingStrategy.fixed()` dan meneruskannya ke [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html)konstruktor. **catatan** Anda dapat menimpa nama layanan default yang Anda tentukan dalam kode dengan [variabel lingkungan](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars)`AWS_XRAY_TRACING_NAME`. 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 nama segmen dinamis di Tomcat, gunakan `dynamicNamingRecognizedHosts` dan `dynamicNamingFallbackName` untuk menentukan pola dan nama default, masing-masing. **Example WEB-INF/web.xml - filter servlet dengan penamaan dinamis** ``` AWSXRayServletFilter com.amazonaws.xray.javax.servlet.AWSXRayServletFilter dynamicNamingRecognizedHosts *.example.com dynamicNamingFallbackName MyApp AWSXRayServletFilter * ``` Untuk Spring, buat dinamika [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)dengan memanggil`SegmentNamingStrategy.dynamic()`, dan meneruskannya ke `AWSXRayServletFilter` konstruktor. **Example src/main/java/myapp/WebConfig.java - filter servlet dengan penamaan dinamis** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com")); } } ``` # Menelusuri panggilan AWS SDK dengan X-Ray SDK for 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 [Saat aplikasi Anda melakukan panggilan Layanan AWS untuk menyimpan data, menulis ke antrian, atau mengirim notifikasi, X-Ray SDK for Java melacak panggilan hilir di subsegmen.](xray-sdk-java-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 for Java secara otomatis menginstrumentasikan semua klien AWS SDK ketika Anda menyertakan [submodul](xray-sdk-java.md#xray-sdk-java-submodules) `aws-sdk` dan suatu `aws-sdk-instrumentor` dalam pembangunan Anda. Jika Anda tidak menyertakan submodul Instrumentor, Anda dapat memilih untuk menginstrumentasikan beberapa klien selagi mengeliminasi yang lain. Untuk menginstrumentasikan klien individual, hapus `aws-sdk-instrumentor` submodule dari build Anda dan tambahkan `XRayClient` as a `TracingHandler` pada klien AWS SDK Anda menggunakan pembuat klien layanan. Misalnya, untuk menginstrumentasikan klien `AmazonDynamoDB`, teruskan penangan pelacakan ke `AmazonDynamoDBClientBuilder`. **Example MyModel.java - DynamoDB klien** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html); ... public class MyModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Regions.fromName(System.getenv("AWS_REGION"))) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); ... ``` Untuk semua layanan, Anda dapat melihat nama API yang dipanggil 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 Untuk menginstrumentasikan panggilan hilir ke Layanan AWS AWS SDK untuk Java 2.2 dan yang lebih baru, Anda dapat menghilangkan `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` modul dari konfigurasi build Anda. Sebaliknya, sertakan `aws-xray-recorder-sdk-aws-sdk-v2 module`, lalu instrumentasikan klien individu dengan mengonfigurasi mereka dengan `TracingInterceptor`. **Example AWS SDK untuk Java 2.2 dan kemudian - melacak pencegat** ``` import com.amazonaws.xray.interceptors.TracingInterceptor; import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration import software.amazon.awssdk.services.dynamodb.DynamoDbClient; //... public class MyModel { private DynamoDbClient client = DynamoDbClient.builder() .region(Region.US_WEST_2) .overrideConfiguration(ClientOverrideConfiguration.builder() .addExecutionInterceptor(new TracingInterceptor()) .build() ) .build(); //... ``` # Menelusuri panggilan ke layanan web downstream HTTP dengan X-Ray SDK for 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 Ketika aplikasi Anda membuat panggilan ke microservices atau HTTP publik APIs, Anda dapat menggunakan X-Ray SDK untuk versi Java `HttpClient` untuk instrumen panggilan tersebut dan menambahkan API ke grafik layanan sebagai layanan hilir. X-Ray SDK for Java `DefaultHttpClient` mencakup `HttpClientBuilder` dan kelas yang dapat digunakan sebagai pengganti HttpComponents Apache yang setara dengan instrumen panggilan HTTP keluar. + `com.amazonaws.xray.proxies.apache.http.DefaultHttpClient` - `org.apache.http.impl.client.DefaultHttpClient` + `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` - `org.apache.http.impl.client.HttpClientBuilder` Pustaka ini berada di submodul [`aws-xray-recorder-sdk-apache-http`](xray-sdk-java.md). Anda dapat mengganti pernyataan impor yang ada dengan X-Ray yang setara untuk instrumen semua klien, atau menggunakan nama yang sepenuhnya memenuhi syarat saat Anda menginisialisasi klien untuk instrumen klien tertentu. **Example HttpClientBuilder** ``` import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.http.HttpEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.util.EntityUtils; import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html); ... public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://names.example.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } } ``` Ketika Anda menginstrumen panggilan ke api web downstream, X-Ray SDK for Java mencatat subsegmen dengan informasi tentang permintaan dan respons HTTP. X-Ray menggunakan subsegmen untuk membuat 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 } ``` # Menelusuri kueri SQL dengan X-Ray SDK for 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 ## Pencegat SQL Instrumen kueri basis data SQL dengan menambahkan X-Ray SDK for Java JDBC pencegat untuk konfigurasi sumber data Anda. + **PostgreSQL** – `com.amazonaws.xray.sql.postgres.TracingInterceptor` + **MySQL** – `com.amazonaws.xray.sql.mysql.TracingInterceptor` Pencegat ini berada di [`aws-xray-recorder-sql-postgres` dan submodul `aws-xray-recorder-sql-mysql`](xray-sdk-java.md), masing-masing. Mereka menerapkan `org.apache.tomcat.jdbc.pool.JdbcInterceptor` dan kompatibel dengan koneksi kolam Tomcat. **catatan** SQL pencegat tidak mencatat kueri SQL itu sendiri dalam subsegmen untuk tujuan keamanan. Untuk Spring, tambahkan pencegat dalam file properti dan membangun sumber data dengan Spring Boot `DataSourceBuilder`. **Example `src/main/java/resources/application.properties` - PostgreSQL JDBC pencegat** ``` spring.datasource.continue-on-error=true spring.jpa.show-sql=false spring.jpa.hibernate.ddl-auto=create-drop spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect ``` **Example `src/main/java/myapp/WebConfig.java` - Sumber data** ``` import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.data.jpa.repository.config.EnableJpaRepositories; import javax.servlet.Filter; import javax.sql.DataSource; import java.net.URL; @Configuration @EnableAutoConfiguration @EnableJpaRepositories("myapp") public class RdsWebConfig { @Bean @ConfigurationProperties(prefix = "spring.datasource") public DataSource dataSource() { logger.info("Initializing PostgreSQL datasource"); return DataSourceBuilder.create() .driverClassName("org.postgresql.Driver") .url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb") .username(System.getenv("RDS_USERNAME")) .password(System.getenv("RDS_PASSWORD")) .build(); } ... } ``` Untuk Tomcat, panggilan `setJdbcInterceptors` pada sumber data JDBC dengan referensi ke kelas X-Ray SDK for Java. **Example `src/main/myapp/model.java` - Sumber data** ``` import org.apache.tomcat.jdbc.pool.DataSource; ... DataSource source = new DataSource(); source.setUrl(url); source.setUsername(user); source.setPassword(password); source.setDriverClassName("com.mysql.jdbc.Driver"); source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;"); ``` Pustaka Sumber Data JDBC Tomcat disertakan dalam X-Ray SDK for Java, tetapi Anda dapat mendeklarasikannya sebagai dependensi yang disediakan untuk dokumen yang Anda gunakan. **Example `pom.xml` - Sumber data JDBC.** ``` org.apache.tomcat tomcat-jdbc 8.0.36 provided ``` ## Dekorator Penelusuran SQL Asli + Tambahkan [https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql](https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql)ke dependensi Anda. + Hiasi sumber data database, koneksi, atau pernyataan Anda. ``` dataSource = TracingDataSource.decorate(dataSource) connection = TracingConnection.decorate(connection) statement = TracingStatement.decorateStatement(statement) preparedStatement = TracingStatement.decoratePreparedStatement(preparedStatement, sql) callableStatement = TracingStatement.decorateCallableStatement(callableStatement, sql) ``` # Membuat subsegmen kustom dengan X-Ray SDK for 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 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 `beginSubsegment` dan `endSubsegment`. **Example GameModel.java - subsegmen khusus** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("Save Game"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` Dalam contoh ini, kode dalam subsegmen memuat sesi game dari DynamoDB dengan metode pada model sesi, dan menggunakan AWS SDK untuk Java pemetaan DynamoDB untuk menyimpan game. Membungkus kode ini di subsegmen membuat panggilan DynamoDB anak subsegmen `Save Game` dalam tampilan penelusuran di konsol tersebut. ![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png) Jika kode di subsegmen Anda melempar pengecualian yang diperiksa, bungkus dalam blok `try` dan panggilan `AWSXRay.endSubsegment()` dalam blok `finally` untuk memastikan bahwa subsegmen selalu tertutup. Jika subsegmen tidak ditutup, segmen induk tidak dapat diselesaikan dan tidak akan dikirim ke X-Ray. Untuk kode yang tidak membuang pengecualian yang diperiksa, Anda dapat melewati kode untuk `AWSXRay.CreateSubsegment` sebagai fungsi Lambda. **Example Subsegmen fungsi Lambda** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); AWSXRay.createSubsegment("getMovies", (subsegment) -> { // function code }); ``` Ketika Anda membuat subsegmen dalam segmen atau subsegmen lain, X-Ray SDK for Java 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" } }, ``` Untuk pemrograman asinkron dan multi-threaded, Anda harus secara manual melewati subsegment ke metode `endSubsegment()` untuk memastikan ditutup dengan benar karena konteks X-Ray dapat diubah selama eksekusi asinkron. Jika subsegmen asinkron ditutup setelah segmen induknya ditutup, metode ini akan secara otomatis mengalirkan seluruh segmen ke daemon X-Ray. **Example Subsegmen Asinkron** ``` @GetMapping("/api") public ResponseEntity api() { CompletableFuture.runAsync(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("Async Work"); try { Thread.sleep(3000); } catch (InterruptedException e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(subsegment); } }); return ResponseEntity.ok().build(); } ``` # Tambahkan anotasi dan metadata ke segmen dengan X-Ray SDK for 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 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-java-segment-userid) pada segmen. Pengguna IDs direkam dalam bidang terpisah pada segmen dan diindeks untuk digunakan dengan pencarian. **Topics** + [Mencatat anotasi dengan X-Ray SDK for Java](#xray-sdk-java-segment-annotations) + [Mencatat metadata dengan X-Ray SDK for Java](#xray-sdk-java-segment-metadata) + [Merekam pengguna IDs dengan X-Ray SDK for Java](#xray-sdk-java-segment-userid) ## Mencatat anotasi dengan X-Ray SDK for Java 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 `AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` atau ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. Panggil `putAnnotation` dengan kunci String, serta nilai Boolean, Nomor, atau String. ``` document.putAnnotation("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"); ``` SDK mencatat penjelasan sebagai pasangan nilai kunci dalam objek `annotations` di dokumen segmen. Memanggil `putAnnotation` 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). **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – Anotasi dan metadata** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## Mencatat metadata dengan X-Ray SDK for Java 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 `AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` atau ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Subsegment document = AWSXRay.getCurrentSubsegment(); ``` 1. Panggil `putMetadata` dengan namespace String, kunci String, dan nilai Boolean, Nomor, String, atau Objek. ``` document.putMetadata("my namespace", "my key", "my value"); ``` atau Panggil `putMetadata` hanya dengan kunci dan nilai. ``` document.putMetadata("my key", "my value"); ``` Jika Anda tidak menentukan namespace, SDK menggunakan `default`. Memanggil `putMetadata` dua kali dengan tombol yang sama akan menimpa nilai yang tercatat sebelumnya pada segmen atau subsegmen yang sama. **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – Anotasi dan metadata** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` ## Merekam pengguna IDs dengan X-Ray SDK for Java Rekam segmen pengguna IDs berdasarkan permintaan untuk mengidentifikasi pengguna yang mengirim permintaan. **Untuk merekam pengguna IDs** 1. Dapatkan referensi ke segmen saat ini dari `AWSXRay`. ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); ... Segment document = AWSXRay.getCurrentSegment(); ``` 1. Panggil `setUser` dengan ID String pengguna yang mengirim permintaan. ``` document.setUser("U12345"); ``` Anda dapat menelepon `setUser` di pengendali Anda untuk mencatat ID pengguna segera setelah aplikasi mulai memproses permintaan. Jika Anda hanya akan menggunakan segmen untuk mengatur ID pengguna, Anda dapat mengaitkan panggilan dalam satu baris. **Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) — ID Pengguna** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); } ``` Untuk menemukan pelacakan untuk ID pengguna, gunakan kata kunci `user` dalam [Ekspresi filter](xray-console-filters.md). ## AWS X-Ray metrik untuk X-Ray SDK for 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 Topik ini menjelaskan AWS X-Ray namespace, metrik, dan dimensi. Anda dapat menggunakan X-Ray SDK for Java untuk mempublikasikan metrik CloudWatch Amazon tanpa sampel dari segmen X-Ray yang dikumpulkan. Metrik ini berasal dari waktu mulai dan akhir segmen, dan kesalahan, dan bendera status yang dibatasi. Gunakan metrik pelacakan ini untuk menampilkan masalah pengulangan dan ketergantungan dalam subsegmen. CloudWatch adalah repositori metrik. Metrik adalah konsep dasar dalam CloudWatch dan mewakili serangkaian titik data yang diatur waktu. Anda (atau Layanan AWS) mempublikasikan titik data metrik ke dalam CloudWatch dan Anda mengambil statistik tentang titik data tersebut sebagai kumpulan data deret waktu yang diurutkan. Metrik ditentukan secara unik dari suatu nama, namespace, dan satu dimensi atau lebih. Setiap titik data dalam metrik memiliki stempel waktu, dan secara opsional, unit pengukuran. Bila Anda meminta statistik, aliran data yang dikembalikan akan diidentifikasi dengan namespace, nama metrik dan dimensi. Untuk informasi selengkapnya CloudWatch, lihat [https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/). ### CloudWatch Metrik X-Ray Namespace `ServiceMetrics/SDK` mencakup metrik berikut. | Metrik | Statistik tersedia | Deskripsi | Unit | | --- | --- | --- | --- | | `Latency` | Rata-rata, Minimum, Maksimum, Total | Perbedaan antara waktu mulai dan akhir. Rata-rata, minimum, dan maksimum, semuanya menggambarkan latensi operasional. Total menggambarkan jumlah panggilan. | Milidetik | | `ErrorRate` | Rata-rata, Jumlah | Tingkat permintaan yang gagal dengan kode status `4xx Client Error`, mengakibatkan kesalahan. | Persen | | `FaultRate` | Rata-rata, Jumlah | Tingkat penelusuran yang gagal dengan kode status `5xx Server Error`, mengakibatkan kesalahan. | Persen | | `ThrottleRate` | Rata-rata, Jumlah | Tingkat penelusuran yang dihentikan yang mengembalikan kode status `429`. Ini adalah subset metrik `ErrorRate`. | Persen | | `OkRate` | Rata-rata, Jumlah | Tingkat permintaan yang ditelusuri menghasilkan kode status `OK`. | Persen | ### CloudWatch Dimensi X-Ray Gunakan dimensi dalam tabel berikut untuk menyempurnakan metrik yang dikembalikan untuk aplikasi instrumentasi Java X-Ray Anda. | Dimensi | Deskripsi | | --- | --- | | `ServiceType` | Tipe layanan, misalnya `AWS::EC2::Instance` atau `NONE`, jika tidak diketahui. | | `ServiceName` | Nama kanonis untuk layanan ini. | ### Aktifkan CloudWatch metrik X-Ray Gunakan prosedur berikut untuk mengaktifkan metrik jejak dalam aplikasi instrumentasi Java Anda. **Untuk mengonfigurasi metrik penelusuran** 1. Tambahkan `aws-xray-recorder-sdk-metrics` paket sebagai Apache Maven dependensi. Untuk informasi selengkapnya, lihat [Submodul X-Ray SDK for Java](#xray-sdk-java-submodules). 1. Aktifkan `MetricsSegmentListener()` baru sebagai bagian dari pembangunan pencatatan global **Example src/com/myapp/web/Startup.jawa** ``` import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder .standard() .withPlugin(new EC2Plugin()) .withPlugin(new ElasticBeanstalkPlugin()) .withSegmentListener(new MetricsSegmentListener()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); } } ``` 1. Terapkan CloudWatch agen untuk mengumpulkan metrik menggunakan Amazon Elastic Compute Cloud (Amazon) EC2, Amazon Elastic Container Service (Amazon ECS) Service Elastic Container (Amazon ECS), atau Amazon Elastic Kubernetes Service (Amazon EKS): + Untuk mengonfigurasi Amazon EC2, lihat [Menginstal CloudWatch agen](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html). + Untuk mengonfigurasi Amazon ECS, lihat [Memantau kontainer Amazon ECS menggunakan Wawasan Kontainer](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html). + Untuk mengonfigurasi Amazon EKS, lihat [Menginstal CloudWatch agen menggunakan add-on Amazon CloudWatch Observability EKS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html). 1. Konfigurasikan SDK untuk berkomunikasi dengan CloudWatch agen. Secara default, SDK berkomunikasi dengan CloudWatch agen pada alamat. `127.0.0.1` Anda dapat mengonfigurasi alamat alternatif dengan menetapkan variabel lingkungan atau properti Java ke `address:port`. **Example Variabel Lingkungan** ``` AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port ``` **Example Properti Java** ``` com.amazonaws.xray.metrics.daemonAddress=address:port ``` **Untuk memvalidasi konfigurasi** 1. Masuk ke Konsol Manajemen AWS dan buka CloudWatch konsol di [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Buka tab **Metrik** untuk mengamati masuknya metrik Anda. 1. (Opsional) Di CloudWatch konsol, pada tab **Log**, buka grup `ServiceMetricsSDK` log. Cari pengaliran log yang cocok dengan metrik host, dan konfirmasikan pesan log. # Melewati konteks segmen antara benang dalam aplikasi multithreaded **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 membuat thread baru dalam aplikasi Anda, `AWSXRayRecorder` tidak mempertahankan referensi ke segmen saat ini atau subsegmen [Entitas](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html). Jika Anda menggunakan klien berinstrumen di utas baru, SDK akan mencoba menulis ke segmen yang tidak ada, menyebabkan file. [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html) Untuk menghindari melempar pengecualian selama pengembangan, Anda dapat mengonfigurasi perekam dengan [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html)yang memberitahunya untuk mencatat kesalahan sebagai gantinya. Anda dapat mengonfigurasi strategi dalam kode dengan [SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy)), atau mengonfigurasi opsi yang setara dengan [variabel lingkungan](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) atau [properti sistem](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops). Salah satu cara untuk mengatasi kesalahan adalah dengan menggunakan segmen baru dengan memanggil [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String)) ketika Anda memulai thread dan [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--) ketika Anda menutupnya. Hal ini bekerja jika Anda menginstrumen kode yang tidak berjalan dalam menanggapi permintaan HTTP, seperti kode yang berjalan ketika aplikasi Anda dimulai. Jika Anda menggunakan beberapa thread untuk menangani permintaan masuk, Anda dapat melewati segmen saat ini atau subsegmen untuk thread baru dan memberikan ke pencatat global. Hal ini memastikan bahwa informasi yang tercatat dalam thread baru dikaitkan dengan segmen yang sama dengan sisa informasi yang tercatat tentang permintaan tersebut. Setelah segmen tersedia di thread baru, Anda dapat mengeksekusi runnable apa pun dengan akses ke konteks segmen itu menggunakan metode `segment.run(() -> { ... })`. Lihat [Menggunakan klien berinstrumen di utas pekerja](scorekeep-workerthreads.md) sebagai contoh. ## Menggunakan X-Ray dengan Program Asinkron X-Ray SDK for Java dapat digunakan dalam program Java asinkron dengan. [SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html) SegmentContextExecutor Mengimplementasikan antarmuka Executor, yang berarti dapat diteruskan ke semua operasi asinkron dari file. [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) Hal ini memastikan bahwa setiap operasi asinkron akan dieksekusi dengan segmen yang benar dalam konteksnya. **Example Contoh App.java: Melewati SegmentContextExecutor ke CompletableFuture** ``` DynamoDbAsyncClient client = DynamoDbAsyncClient.create(); AWSXRay.beginSegment(); // ... client.getItem(request).thenComposeAsync(response -> { // If we did not provide the segment context executor, this request would not be traced correctly. return client.getItem(request2); }, SegmentContextExecutors.newSegmentContextExecutor()); ``` # AOP dengan Spring dan X-Ray SDK for 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 Topik ini menjelaskan cara menggunakan SDK X-Ray dan Kerangka Kerja Spring untuk menginstrumentasikan aplikasi Anda tanpa mengubah logika intinya. Ini berarti bahwa sekarang ada cara non-invasif untuk instrumen aplikasi Anda berjalan dari jarak jauh. AWS **Untuk mengaktifkan AOP di Spring** 1. [Konfigurasikan Musim Semi](#xray-sdk-java-aop-spring-configuration) 1. [Tambahkan filter penelusuran ke aplikasi Anda](#xray-sdk-java-aop-filters-spring) 1. [Beri anotasi kode Anda atau terapkan antarmuka](#xray-sdk-java-aop-annotate-or-implement) 1. [Aktifkan X-Ray di aplikasi Anda](#xray-sdk-java-aop-activate-xray) ## Mengonfigurasi Spring Anda dapat menggunakan Maven atau Gradle untuk mengonfigurasi Spring menggunakan AOP untuk instrumen aplikasi Anda. Jika Anda menggunakan Maven untuk membangun aplikasi Anda, tambahkan ketergantungan berikut di file `pom.xml` Anda. ``` com.amazonaws aws-xray-recorder-sdk-spring 2.11.0 ``` Untuk Gradle, tambahkan ketergantungan berikut di file `build.gradle` Anda. ``` compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0' ``` ## Mengkonfigurasi Spring Boot Selain ketergantungan Spring yang dijelaskan di bagian sebelumnya, jika Anda menggunakan Spring Boot, tambahkan dependensi berikut jika belum ada di classpath Anda. Maven: ``` org.springframework.boot spring-boot-starter-aop 2.5.2 ``` Gradle: ``` compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2' ``` ## Menambahkan filter pelacakan ke aplikasi Anda Tambahkan `Filter` ke kelas `WebConfig` Anda. Teruskan nama segmen ke konstruktor [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) sebagai string. Untuk informasi selengkapnya tentang filter pelacakan dan menginstrumentasikan permintaan masuk, lihat [Menelusuri permintaan yang masuk dengan X-Ray SDK for Java](xray-sdk-java-filters.md). **Example src/main/java/myapp/WebConfig.java - musim semi** ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } } ``` ## Support Jakarta Spring 6 menggunakan [Jakarta](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga) sebagai pengganti Javax untuk Enterprise Edition. Untuk mendukung namespace baru ini, X-Ray telah menciptakan serangkaian kelas paralel yang hidup di namespace Jakarta mereka sendiri. Untuk kelas filter, ganti `javax` dengan`jakarta`. Saat mengonfigurasi strategi penamaan segmen, tambahkan `jakarta` sebelum nama kelas strategi penamaan, seperti pada contoh berikut: ``` package myapp; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Bean; import jakarta.servlet.Filter; import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter; import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy; @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep")); } } ``` ## Anotasi kode Anda atau menerapkan antarmuka Kelas Anda harus dianotasikan dengan `@XRayEnabled`, atau menerapkan antarmuka `XRayTraced`. Langkah ini memberitahu sistem AOP untuk membungkus fungsi kelas yang terdampak untuk instrumentasi X-Ray. ## Mengaktifkan X-Ray dalam aplikasi Untuk mengaktifkan pelacakan X-Ray dalam aplikasi Anda, kode Anda harus memperpanjang kelas abstrak `BaseAbstractXRayInterceptor`dengan menimpa metode berikut. + `generateMetadata`—Fungsi ini mengizinkan kustomisasi metadata yang terlampir pada pelacakan fungsi saat ini. Secara default, nama kelas dari fungsi yang sedang berjalan dicatat dalam metadata. Anda dapat menambahkan lebih banyak data jika Anda memerlukan informasi tambahan. + `xrayEnabledClasses`—Fungsi ini kosong, dan harus tetap demikian. Berfungsi sebagai host untuk pointcut yang menginstruksikan penghalang tentang metode yang digunakan untuk membungkus. Tentukan pointcut dengan menentukan kelas yang dianotasikan dengan`@XRayEnabled` untuk melacak. Pernyataan pointcut berikut memberitahu penghalang untuk membungkus semua pengendali bean yang teranotasi dengan anotasi `@XRayEnabled`. ``` @Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”) ``` Jika proyek Anda menggunakan Spring Data JPA, pertimbangkan untuk memperpanjang dari `AbstractXRayInterceptor` bukan. `BaseAbstractXRayInterceptor` ## Contoh Kode berikut memperluas kelas abstrak `BaseAbstractXRayInterceptor`. ``` @Aspect @Component public class XRayInspector extends BaseAbstractXRayInterceptor { @Override protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception { return super.generateMetadata(proceedingJoinPoint, subsegment); } @Override @Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)") public void xrayEnabledClasses() {} } ``` Kode berikut adalah kelas yang akan diinstrumentasi oleh X-Ray. ``` @Service @XRayEnabled public class MyServiceImpl implements MyService { private final MyEntityRepository myEntityRepository; @Autowired public MyServiceImpl(MyEntityRepository myEntityRepository) { this.myEntityRepository = myEntityRepository; } @Transactional(readOnly = true) public List getMyEntities(){ try(Stream entityStream = this.myEntityRepository.streamAll()){ return entityStream.sorted().collect(Collectors.toList()); } } } ``` Jika Anda telah mengonfigurasi aplikasi Anda dengan benar, Anda akan melihat tumpukan panggilan aplikasi yang lengkap, dari pengendali hingga panggilan layanan seperti yang ditunjukkan pada tangkapan layar konsol tersebut. ![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/aop-spring-console.png)