AWS X-Ray SDK untuk Java - AWS X-Ray

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:

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

  • Artifactaws-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

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 X-Ray SDK untuk Submodul Java.

  2. Aktifkan MetricsSegmentListener() baru sebagai bagian dari pembangunan pencatatan global

    contoh 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()); } }
  3. 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

  4. Konfigurasikan SDK untuk berkomunikasi dengan CloudWatch agen. Secara default, SDK berkomunikasi dengan CloudWatch agen di alamat127.0.0.1. Anda dapat mengonfigurasi alamat alternatif dengan menetapkan variabel lingkungan atau properti Java ke address:port.

    contoh Variabel Lingkungan
    AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
    contoh Properti Java
    com.amazonaws.xray.metrics.daemonAddress=address:port
Untuk memvalidasi konfigurasi
  1. Masuk ke AWS Management Console dan buka CloudWatch konsol di https://console.aws.amazon.com/cloudwatch/.

  2. Buka tab Metrik untuk mengamati masuknya metrik Anda.

  3. (Opsional) Di CloudWatch konsol, pada tab Log, buka grup ServiceMetricsSDK log. Cari pengaliran log yang cocok dengan metrik host, dan konfirmasikan pesan log.