Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
AWS X-Ray SDK untuk Java
X-Ray SDK untuk Java adalah seperangkat perpustakaan untuk aplikasi web Java yang menyediakan kelas dan metode untuk menghasilkan dan mengirim data jejak ke daemon X-Ray. Data pelacakan mencakup informasi tentang HTTP permintaan masuk yang dilayani oleh aplikasi, dan panggilan yang dilakukan aplikasi ke layanan hilir menggunakan AWS SDK, HTTP klien, atau konektor SQL database. Anda juga dapat membuat segmen secara manual dan menambahkan informasi debug dalam anotasi dan metadata.
X-Ray SDK untuk Java adalah proyek open source. Anda dapat mengikuti proyek dan mengirimkan masalah dan menarik permintaan di GitHub: github.com/aws/ aws-xray-sdk-java
Mulai dengan menambahkan AWSXRayServletFilter sebagai filter servlet untuk pelacakan permintaan yang masuk. Filter servlet membuat segmen. Saat segmen terbuka, Anda dapat menggunakan metode SDK klien untuk menambahkan informasi ke segmen dan membuat subsegmen untuk melacak panggilan hilir. Ini SDK juga secara otomatis mencatat pengecualian yang dilemparkan aplikasi Anda saat segmen terbuka.
Mulai rilis 1.3, Anda dapat menginstruksikan aplikasi Anda menggunakan pemrograman berorientasi aspek (AOP) di Musim Semi. Artinya, Anda dapat menginstruksikan aplikasi Anda, saat sedang berjalan AWS, tanpa menambahkan kode apa pun ke runtime aplikasi Anda.
Selanjutnya, gunakan X-Ray SDK untuk Java untuk menginstrumentasikan AWS SDK for Java klien Anda dengan menyertakan submodul SDK Instrumentor dalam konfigurasi build Anda. Setiap kali Anda melakukan panggilan ke hilir Layanan AWS atau sumber daya dengan klien yang diinstrumentasi, akan SDK 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 ke klien AWS SDK layanan.
X-Ray lainnya SDK untuk submodul Java menyediakan instrumentasi untuk panggilan hilir ke HTTP web APIs dan database. SQL Anda dapat menggunakan X-Ray SDK untuk versi Java HTTPClient dan HTTPClientBuilder dalam HTTP submodul Apache untuk instrumen klien HTTP Apache. Untuk SQL kueri instrumen, tambahkan pencegat ke sumber data Anda. SDK
Setelah Anda mulai menggunakanSDK, sesuaikan perilakunya dengan mengonfigurasi filter perekam dan servlet. Anda dapat menambahkan plugin untuk merekam data tentang sumber daya komputasi yang menjalankan aplikasi Anda, menyesuaikan perilaku pengambilan sampel dengan menentukan aturan pengambilan sampel, dan mengatur tingkat log untuk melihat lebih banyak atau lebih sedikit informasi dari log aplikasi Anda. SDK
Catat informasi tambahan tentang permintaan dan pekerjaan yang dilakukan aplikasi Anda dalam anotasi dan metadata. Anotasi adalah pasangan kunci-nilai sederhana yang diindeks untuk digunakan dengan ekspresi filter, sehingga Anda dapat mencari pelacakan yang berisi data tertentu. Entri metadata kurang membatasi dan dapat merekam seluruh objek dan array — apa pun yang dapat diserialisasikan. JSON
Anotasi dan Metadata
Anotasi dan metadata adalah teks arbitrer 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. 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 untuk Java dari Maven. X-Ray SDK untuk Java dibagi menjadi submodul berdasarkan kasus penggunaan, dengan tagihan bahan untuk manajemen versi:
-
aws-xray-recorder-sdk-core
(wajib) – Fungsi dasar untuk membuat segmen dan transmisi segmen. Termasuk AWSXRayServletFilter
untuk instrumenting permintaan masuk. -
aws-xray-recorder-sdk-aws-sdk
— Instrumen panggilan untuk Layanan AWS dilakukan dengan AWS SDK for Java klien dengan menambahkan klien penelusuran sebagai penangan permintaan. -
aws-xray-recorder-sdk-aws-sdk-v2
— Instrumen panggilan untuk Layanan AWS dilakukan dengan klien AWS SDK for Java 2.2 dan yang lebih baru dengan menambahkan klien penelusuran sebagai interekeptor permintaan. -
aws-xray-recorder-sdk-aws-sdk-instrumentor
— Dengan aws-xray-recorder-sdk-aws-sdk
, instrumen semua AWS SDK for Java klien secara otomatis. -
aws-xray-recorder-sdk-aws-sdk-v2-instrumentor
— Dengan aws-xray-recorder-sdk-aws-sdk-v2
, instrumen semua klien AWS SDK for Java 2.2 dan yang lebih baru secara otomatis. -
aws-xray-recorder-sdk-apache-http
— Instrumen HTTP panggilan keluar dibuat dengan klien ApacheHTTP. -
aws-xray-recorder-sdk-spring
- Menyediakan pencegat untuk aplikasi Spring AOP Framework. -
aws-xray-recorder-sdk-sql-postgres
— Instrumen panggilan keluar ke SQL database Postgre yang dibuat dengan. JDBC -
aws-xray-recorder-sdk-sql-mysql
— Instrumen panggilan keluar ke SQL database Saya dibuat denganJDBC. -
aws-xray-recorder-sdk-bom
– Menyediakan tagihan materi yang dapat Anda gunakan untuk menentukan versi yang akan digunakan untuk semua submodul. -
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, tambahkan X-Ray SDK untuk Java ke konfigurasi build Anda.
Untuk dokumentasi referensi kelas dan metode, lihat AWS X-Ray SDKAPIReferensi Java. SDK
Persyaratan
X-Ray SDK untuk Java membutuhkan Java 8 atau lebih baru, Servlet API 3, the AWS SDK, dan Jackson.
SDKTergantung pada pustaka berikut saat kompilasi dan runtime:
-
AWS SDKuntuk Java versi 1.11.398 atau yang lebih baru
-
Servlet 3.1.0 API
Dependensi ini dideklarasikan dalam pom.xml
file dan disertakan secara otomatis jika Anda membangun menggunakan Maven atau Gradle. SDK
Jika Anda menggunakan perpustakaan yang disertakan dalam X-Ray SDK untuk Java, Anda harus menggunakan versi yang disertakan. Misalnya, jika Anda sudah bergantung pada Jackson saat runtime dan menyertakan JAR file dalam penerapan Anda untuk ketergantungan itu, Anda harus menghapus JAR file-file tersebut karena SDK JAR menyertakan versi pustaka Jackson sendiri.
Manajemen dependensi
X-Ray SDK untuk 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, tambahkan dependensi SDK sebagai dalam file Anda. pom.xml
contoh pom.xml - dependensi
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-xray-recorder-sdk-bom</artifactId>
<version>2.11.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-xray-recorder-sdk-core</artifactId>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-xray-recorder-sdk-apache-http</artifactId>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId>
</dependency>
<dependency>
<groupId>com.amazonaws</groupId>
<artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId>
</dependency>
</dependencies>
Untuk Gradle, tambahkan dependensi waktu kompilasi SDK sebagai dalam file Anda. build.gradle
contoh 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 sebagai contoh yang menggunakan Gradle.
AWS X-Ray metrik untuk X-Ray SDK untuk Java
Topik ini menjelaskan AWS X-Ray namespace, metrik, dan dimensi. Anda dapat menggunakan X-Ray SDK untuk Java untuk mempublikasikan CloudWatch metrik Amazon yang tidak disampel 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 Panduan CloudWatch Pengguna Amazon.
CloudWatch Metrik X-Ray
Namespace ServiceMetrics/SDK
mencakup metrik berikut.
Metrik | Statistik tersedia | Deskripsi | Unit |
---|---|---|---|
|
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 |
|
Rata-rata, Jumlah |
Tingkat permintaan yang gagal dengan kode status |
Persen |
|
Rata-rata, Jumlah |
Tingkat penelusuran yang gagal dengan kode status |
Persen |
|
Rata-rata, Jumlah |
Tingkat penelusuran yang dihentikan yang mengembalikan kode status |
Persen |
|
Rata-rata, Jumlah |
Tingkat permintaan yang ditelusuri menghasilkan kode status |
Persen |
CloudWatch Dimensi X-Ray
Gunakan dimensi dalam tabel berikut untuk menyempurnakan metrik yang dikembalikan untuk aplikasi instrumentasi Java X-Ray Anda.
Dimensi | Deskripsi |
---|---|
|
Tipe layanan, misalnya |
|
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
-
Tambahkan
aws-xray-recorder-sdk-metrics
paket sebagai Apache Maven dependensi. Untuk informasi selengkapnya, lihat X-Ray SDK untuk Submodul Java. -
Aktifkan
MetricsSegmentListener()
baru sebagai bagian dari pembangunan pencatatan globalcontoh src/com/myapp/web/Startup.java
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()); } } -
Terapkan CloudWatch agen untuk mengumpulkan metrik menggunakan Amazon Elastic Compute Cloud (Amazon)EC2, Amazon Elastic Container Service (AmazonECS), atau Amazon Elastic Kubernetes Service (Amazon): EKS
-
Untuk mengonfigurasi AmazonEC2, lihat Menginstal CloudWatch agen.
-
Untuk mengonfigurasi AmazonECS, lihat Memantau ECS kontainer Amazon menggunakan Wawasan Kontainer.
-
Untuk mengonfigurasi AmazonEKS, lihat Menginstal CloudWatch agen menggunakan EKS add-on Amazon CloudWatch Observability.
-
-
Konfigurasikan SDK untuk berkomunikasi dengan CloudWatch agen. Secara default, SDK berkomunikasi dengan CloudWatch agen di alamat
127.0.0.1
. Anda dapat mengonfigurasi alamat alternatif dengan menetapkan variabel lingkungan atau properti Java keaddress:port
.contoh Variabel Lingkungan
AWS_XRAY_METRICS_DAEMON_ADDRESS=
address:port
contoh Properti Java
com.amazonaws.xray.metrics.daemonAddress=
address:port
Untuk memvalidasi konfigurasi
Masuk ke AWS Management Console dan buka CloudWatch konsol di https://console.aws.amazon.com/cloudwatch/
. -
Buka tab Metrik untuk mengamati masuknya metrik Anda.
-
(Opsional) Di CloudWatch konsol, pada tab Log, buka grup
ServiceMetricsSDK
log. Cari pengaliran log yang cocok dengan metrik host, dan konfirmasikan pesan log.