Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS X-Ray aplikasi sampel
**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
Aplikasi [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray)sampel AWS X-Ray, tersedia di GitHub, menunjukkan penggunaan AWS X-Ray SDK untuk instrumen panggilan HTTP yang masuk, klien SDK DynamoDB, dan klien HTTP. Aplikasi sampel digunakan CloudFormation untuk membuat tabel DynamoDB, mengkompilasi kode Java pada instance, dan menjalankan daemon X-Ray tanpa konfigurasi tambahan.
Lihat [tutorial Scorekeep](scorekeep-tutorial.md) untuk mulai menginstal dan menggunakan aplikasi sampel berinstrumen, menggunakan atau. Konsol Manajemen AWS AWS CLI
![\[Scorekeep menggunakan AWS X-Ray SDK untuk instrumen panggilan HTTP yang masuk, klien DynamoDB SDK, dan klien HTTP\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-flow.png)
Sampel mencakup aplikasi web front-end, API yang dipanggilnya, dan tabel DynamoDB yang digunakan untuk menyimpan data. Instrumentasi dasar dengan [filter](xray-sdk-java-filters.md), [plugin](xray-sdk-java-configuration.md), dan [klien AWS SDK berinstrumen](xray-sdk-java-awssdkclients.md) ditampilkan di cabang proyek. `xray-gettingstarted` Ini adalah cabang yang Anda deploy di [tutorial memulai](scorekeep-tutorial.md). Karena cabang ini hanya mencakup instrumentasi dasar, Anda dapat membedakannya dengan cabang `master` agar dapat memahami instrumentasi dasar dengan cepat.
![\[Service map showing client interaction with Scorekeep container and related Layanan AWS.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png)
Aplikasi sampel menunjukkan instrumentasi dasar dalam file ini:
+ **Filter permintaan HTTP** – [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java)
+ **AWS Instrumentasi klien SDK** — [https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle](https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle)
`xray`[Cabang aplikasi mencakup penggunaan [HTTPClient](xray-sdk-java-httpclients.md), [Anotasi](xray-sdk-java-segment.md), [kueri SQL](xray-sdk-java-sqlclients.md), [subsegmen kustom](xray-sdk-java-subsegments.md), [AWS Lambda](xray-services-lambda.md)fungsi instrumentasi, dan kode inisialisasi instrumentasi dan skrip.](scorekeep-startup.md)
Untuk mendukung login dan AWS SDK untuk JavaScript penggunaan pengguna di browser, `xray-cognito` cabang menambahkan Amazon Cognito untuk mendukung otentikasi dan otorisasi pengguna. Dengan kredensial yang diambil dari Amazon Cognito, aplikasi web juga mengirimkan data pelacakan ke X-Ray untuk mencatat informasi permintaan dari sudut pandang klien. Klien browser muncul sebagai simpulnya sendiri di peta jejak, dan mencatat informasi tambahan, termasuk URL halaman yang dilihat pengguna, dan ID pengguna.
Akhirnya, cabang `xray-worker` menambahkan fungsi Python Lambda yang diinstrumentasi yang berjalan secara independen, memproses item dari antrean Amazon SQS. Scorekeep menambahkan item ke antrean setiap kali game berakhir. Pekerja Lambda, yang dipicu oleh CloudWatch Peristiwa, menarik item dari antrian setiap beberapa menit dan memprosesnya untuk menyimpan catatan game di Amazon S3 untuk dianalisis.
**Topics**
+ [Memulai dengan aplikasi sampel Scorekeep](scorekeep-tutorial.md)
+ [Menginstrumentasi klien AWS SDK secara manual](scorekeep-sdkclients.md)
+ [Membuat subsegmen tambahan](scorekeep-subsegments.md)
+ [Merekam anotasi, metadata, dan pengguna IDs](scorekeep-annotations.md)
+ [Instrumentasi panggilan HTTP keluar](scorekeep-httpclient.md)
+ [Menginstrumentasi panggilan ke basis data PostgreSQL](scorekeep-postgresql.md)
+ [Fungsi instrumentasi AWS Lambda](scorekeep-lambda.md)
+ [Menginstrumentasi kode perusahaan rintisan](scorekeep-startup.md)
+ [Skrip instrumentasi](scorekeep-scripts.md)
+ [Menginstrumentasi klien aplikasi web](scorekeep-client.md)
+ [Menggunakan klien berinstrumen di utas pekerja](scorekeep-workerthreads.md)
# Memulai dengan aplikasi sampel Scorekeep
**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
Tutorial ini menggunakan `xray-gettingstarted` cabang [aplikasi sampel Scorekeep](xray-scorekeep.md), yang digunakan CloudFormation untuk membuat dan mengonfigurasi sumber daya yang menjalankan aplikasi sampel dan daemon X-Ray di Amazon ECS. Aplikasi ini menggunakan framework Spring untuk mengimplementasikan API web JSON dan AWS SDK untuk Java untuk mempertahankan data ke Amazon DynamoDB. Filter servlet dalam instrumen aplikasi semua permintaan masuk yang dilayani oleh aplikasi, dan penangan permintaan pada instrumen klien AWS SDK panggilan hilir ke DynamoDB.
Anda dapat mengikuti tutorial ini menggunakan salah satu Konsol Manajemen AWS atau AWS CLI.
**Topics**
+ [Prasyarat](#xray-gettingstarted-prereqs)
+ [Instal aplikasi Scorekeep menggunakan CloudFormation](#xray-gettingstarted-deploy)
+ [Hasilkan data pelacakan](#xray-gettingstarted-generate-traces)
+ [Lihat peta jejak di Konsol Manajemen AWS](#xray-gettingstarted-console)
+ [Mengonfigurasi notifikasi Amazon SNS](#xray-gettingstarted-notifications)
+ [Jelajahi aplikasi sampel](#xray-gettingstarted-sample)
+ [Opsional: Kebijakan hak istimewa terbatas](#xray-gettingstarted-security)
+ [Bersihkan](#xray-gettingstarted-cleanup)
+ [Langkah selanjutnya](#xray-gettingstarted-nextsteps)
## Prasyarat
Tutorial ini digunakan CloudFormation untuk membuat dan mengkonfigurasi sumber daya yang menjalankan aplikasi sampel dan daemon X-Ray. Prasyarat berikut diperlukan untuk menginstal dan menjalankan tutorial:
1. Jika Anda menggunakan pengguna IAM dengan izin terbatas, tambahkan kebijakan pengguna berikut di konsol [IAM](https://console.aws.amazon.com/iam):
+ `AWSCloudFormationFullAccess`— untuk mengakses dan menggunakan CloudFormation
+ `AmazonS3FullAccess`— untuk mengunggah file template untuk CloudFormation menggunakan Konsol Manajemen AWS
+ `IAMFullAccess`— untuk membuat peran instans Amazon ECS dan Amazon EC2
+ `AmazonEC2FullAccess`— untuk membuat sumber daya Amazon EC2
+ `AmazonDynamoDBFullAccess`— untuk membuat tabel DynamoDB
+ `AmazonECS_FullAccess`— untuk membuat sumber daya Amazon ECS
+ `AmazonSNSFullAccess`— untuk membuat topik Amazon SNS
+ `AWSXrayReadOnlyAccess`— untuk izin untuk melihat peta jejak dan jejak di konsol X-Ray
1. Untuk menjalankan tutorial menggunakan AWS CLI, [instal CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) versi 2.7.9 atau yang lebih baru, dan konfigurasikan [CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) dengan pengguna dari langkah sebelumnya. Pastikan wilayah dikonfigurasi saat mengonfigurasi AWS CLI dengan pengguna. Jika suatu wilayah tidak dikonfigurasi, Anda harus menambahkan `--region AWS-REGION` ke setiap perintah CLI.
1. Pastikan bahwa [Git](https://github.com/git-guides/install-git) diinstal, untuk mengkloning repo aplikasi sampel.
1. Gunakan contoh kode berikut untuk mengkloning `xray-gettingstarted` cabang repositori Scorekeep:
```
git clone https://github.com/aws-samples/eb-java-scorekeep.git xray-scorekeep -b xray-gettingstarted
```
## Instal aplikasi Scorekeep menggunakan CloudFormation
------
#### [ Konsol Manajemen AWS ]
**Instal aplikasi sampel menggunakan Konsol Manajemen AWS**
1. Buka [konsol CloudFormation](https://console.aws.amazon.com/cloudformation/)
1. Pilih **Buat tumpukan** lalu pilih **Dengan sumber daya baru** dari menu drop-down.
1. Di bagian **Tentukan templat**, pilih **Unggah file templat**.
1. Pilih **Pilih file**, navigasikan ke `xray-scorekeep/cloudformation` folder yang dibuat saat Anda mengkloning git repo, dan pilih file. `cf-resources.yaml`
1. Pilih **Next** untuk melanjutkan.
1. Masukkan `scorekeep` ke dalam kotak teks **nama Stack**, lalu pilih **Berikutnya** di bagian bawah halaman untuk melanjutkan. Perhatikan bahwa sisa tutorial ini mengasumsikan tumpukan diberi nama`scorekeep`.
1. Gulir ke bagian bawah halaman **Configure stack options** dan pilih **Next** untuk melanjutkan.
1. **Gulir ke bagian bawah halaman **Tinjauan**, pilih kotak centang yang mengakui yang CloudFormation dapat membuat sumber daya IAM dengan nama khusus, dan pilih Buat tumpukan.**
1. CloudFormation Tumpukan sekarang sedang dibuat. Status tumpukan akan `CREATE_IN_PROGRESS` sekitar lima menit sebelum diubah menjadi`CREATE_COMPLETE`. Status akan disegarkan secara berkala, atau Anda dapat me-refresh halaman.
------
#### [ AWS CLI ]
**Instal aplikasi sampel menggunakan AWS CLI**
1. Arahkan ke `cloudformation` folder `xray-scorekeep` repositori yang Anda kloning sebelumnya dalam tutorial:
```
cd xray-scorekeep/cloudformation/
```
1. Masukkan AWS CLI perintah berikut untuk membuat CloudFormation tumpukan:
```
aws cloudformation create-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml
```
1. Tunggu sampai status CloudFormation tumpukan`CREATE_COMPLETE`, yang akan memakan waktu sekitar lima menit. Gunakan AWS CLI perintah berikut untuk memeriksa status:
```
aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus"
```
------
## Hasilkan data pelacakan
Aplikasi sampel termasuk aplikasi web front-end. Gunakan aplikasi web untuk menghasilkan lalu lintas ke API dan mengirim data pelacakan ke X-Ray. Pertama, ambil URL aplikasi web menggunakan Konsol Manajemen AWS atau: AWS CLI
------
#### [ Konsol Manajemen AWS ]
**Temukan URL aplikasi menggunakan Konsol Manajemen AWS**
1. Buka [konsol CloudFormation](https://console.aws.amazon.com/cloudformation/)
1. Pilih `scorekeep` tumpukan dari daftar.
1. Pilih tab **Output** pada halaman `scorekeep` tumpukan, dan pilih tautan `LoadBalancerUrl` URL untuk membuka aplikasi web.
------
#### [ AWS CLI ]
**Temukan URL aplikasi menggunakan AWS CLI**
1. Gunakan perintah berikut untuk menampilkan URL aplikasi web:
```
aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].Outputs[0].OutputValue"
```
1. Salin URL ini dan buka di browser untuk menampilkan aplikasi web Scorekeep.
------
**Gunakan aplikasi web untuk menghasilkan data jejak**
1. Pilih **Buat** untuk membuat pengguna dan sesi.
1. Ketik **nama game**, atur **Aturan** ke **Tic Tac Toe**, lalu pilih **Buat** untuk membuat game.
1. Pilih **Mainkan** untuk memulai game.
1. Pilih ubin untuk bergerak dan mengubah status game.
Masing-masing langkah ini menghasilkan permintaan HTTP ke API, dan panggilan hilir ke DynamoDB untuk membaca dan menulis pengguna, sesi, game, gerak, dan data status.
## Lihat peta jejak di Konsol Manajemen AWS
Anda dapat melihat peta jejak dan jejak yang dihasilkan oleh aplikasi sampel di X-Ray dan CloudWatch konsol.
------
#### [ X-Ray console ]
**Gunakan konsol X-Ray**
1. Buka halaman peta jejak [konsol X-Ray](https://console.aws.amazon.com/xray/home#/service-map).
1. Konsol menunjukkan representasi grafik layanan yang dihasilkan X-Ray dari pelacakan data yang dikirim oleh aplikasi. Pastikan untuk menyesuaikan periode waktu peta jejak jika diperlukan, untuk memastikan bahwa itu akan menampilkan semua jejak sejak Anda pertama kali memulai aplikasi web.
![\[Periode waktu peta jejak X-Ray\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/xray-console-time-period-15-minutes.png)
Peta jejak menunjukkan klien aplikasi web, API yang berjalan di Amazon ECS, dan setiap tabel DynamoDB yang digunakan aplikasi. Setiap permintaan ke aplikasi, hingga jumlah maksimum permintaan yang dapat dikonfigurasi per detik, dilacak saat menyentuh API, menghasilkan permintaan ke layanan hilir, dan selesai.
Anda dapat memilih simpul apa pun dalam layanan grafik untuk melihat pelacakan untuk permintaan yang menghasilkan lalu lintas ke simpul tersebut. Saat ini, node Amazon SNS berwarna kuning. Telusuri paling detail untuk mencari tahu penyebabnya.
![\[Halaman peta jejak konsol X-Ray\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png)
**Untuk menemukan penyebab kesalahan**
1. Pilih simpul bernama **SNS**. Panel detail simpul ditampilkan.
1. Pilih **Lihat pelacakan **untuk mengakses layar **Gambaran umum pelacakan.**
1. Pilih pelacakan dari **Daftar pelacakan.** Pelacakan ini tidak memiliki metode atau URL karena dicatat selama startup bukan sebagai respons permintaan masuk.
![\[Memilih pelacakan dari daftar pelacakan\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-gettingstarted-tracelist-sns.png)
1. Pilih ikon status kesalahan dalam segmen Amazon SNS di bagian bawah halaman, untuk membuka halaman **Pengecualian** untuk subsegmen SNS.
![\[Pilih ikon status kesalahan untuk membuka halaman Pengecualian untuk subsegmen Amazon SNS\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-gettingstarted-timeline-sns-ecs.png)
1. X-Ray SDK secara otomatis menangkap pengecualian yang dilemparkan oleh instrumentasi AWS SDK klien dan mencatat pelacakan tumpukan.
![\[Tab pengecualian menampilkan pengecualian yang ditangkap dan mencatat pelacakan tumpukan\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-gettingstarted-exception.png)
------
#### [ CloudWatch console ]
**Gunakan CloudWatch konsol**
1. Buka halaman [peta jejak X-Ray](https://console.aws.amazon.com/cloudwatch/home#xray:service-map/map) CloudWatch konsol.
1. Konsol menunjukkan representasi grafik layanan yang dihasilkan X-Ray dari pelacakan data yang dikirim oleh aplikasi. Pastikan untuk menyesuaikan periode waktu peta jejak jika diperlukan, untuk memastikan bahwa itu akan menampilkan semua jejak sejak Anda pertama kali memulai aplikasi web.
![\[CloudWatch melacak periode waktu peta\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/cw-console-service-map-time-period-15-minutes.png)
Peta jejak menunjukkan klien aplikasi web, API yang berjalan di Amazon EC2, dan setiap tabel DynamoDB yang digunakan aplikasi. Setiap permintaan ke aplikasi, hingga jumlah maksimum permintaan yang dapat dikonfigurasi per detik, dilacak saat menyentuh API, menghasilkan permintaan ke layanan hilir, dan selesai.
Anda dapat memilih simpul apa pun dalam layanan grafik untuk melihat pelacakan untuk permintaan yang menghasilkan lalu lintas ke simpul tersebut. Saat ini, node Amazon SNS berwarna oranye. Telusuri paling detail untuk mencari tahu penyebabnya.
![\[Halaman peta jejak konsol X-Ray\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-gettingstarted-cw-servicemap-before-ECS.png)
**Untuk menemukan penyebab kesalahan**
1. Pilih simpul bernama **SNS**. Panel detail node SNS ditampilkan di bawah peta.
1. Pilih **Lihat jejak** untuk mengakses halaman **Jejak**.
1. Tambahkan bagian bawah halaman, pilih jejak dari daftar **Jejak**. Pelacakan ini tidak memiliki metode atau URL karena dicatat selama startup bukan sebagai respons permintaan masuk.
![\[Memilih pelacakan dari daftar pelacakan\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-gettingstarted-cw-tracelist-sns-ecs.png)
1. Pilih subsegmen Amazon SNS di bagian bawah timeline segmen, dan pilih tab **Pengecualian** untuk subsegmen SNS untuk melihat detail pengecualian.
![\[Lihat tab Pengecualian untuk subsegmen Amazon SNS\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-gettingstarted-cw-timeline-sns-ecs.png)
------
Penyebabnya menunjukkan bahwa alamat email yang diberikan dalam panggilan ke `createSubscription` yang dibuat di kelas `WebConfig` tidak valid. Di bagian selanjutnya, kita akan memperbaikinya.
## Mengonfigurasi notifikasi Amazon SNS
Scorekeep menggunakan Amazon SNS untuk mengirim notifikasi saat pengguna menyelesaikan game. Saat aplikasi dijalankan, ia mencoba membuat langganan untuk alamat email yang ditentukan dalam parameter CloudFormation tumpukan. Panggilan itu saat ini gagal. Konfigurasikan email notifikasi untuk mengaktifkan notifikasi, dan selesaikan kegagalan yang disorot di peta jejak.
------
#### [ Konsol Manajemen AWS ]
**Untuk mengonfigurasi notifikasi Amazon SNS menggunakan Konsol Manajemen AWS**
1. Buka [konsol CloudFormation](https://console.aws.amazon.com/cloudformation/)
1. Pilih tombol radio di sebelah nama `scorekeep` tumpukan dalam daftar, lalu pilih **Perbarui**.
1. Pastikan bahwa **Use current template** dipilih, lalu klik **Next** pada halaman **Update stack**.
1. Temukan parameter **Email** dalam daftar, dan ganti nilai default dengan alamat email yang valid.
![\[Perbarui konfigurasi email\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-cf-email-update.png)
1. Gulir ke bagian bawah halaman dan pilih **Berikutnya**.
1. **Gulir ke bagian bawah halaman **Tinjauan**, pilih kotak centang yang mengakui yang CloudFormation dapat membuat sumber daya IAM dengan nama khusus, dan pilih Perbarui tumpukan.**
1. CloudFormation Tumpukan sekarang sedang diperbarui. Status tumpukan akan `UPDATE_IN_PROGRESS` sekitar lima menit sebelum diubah menjadi`UPDATE_COMPLETE`. Status akan disegarkan secara berkala, atau Anda dapat me-refresh halaman.
------
#### [ AWS CLI ]
**Untuk mengonfigurasi notifikasi Amazon SNS menggunakan AWS CLI**
1. Arahkan ke `xray-scorekeep/cloudformation/` folder yang sebelumnya Anda buat, dan buka `cf-resources.yaml` file di editor teks.
1. Temukan `Default` nilai dalam parameter **Email** dan ubah dari *UPDATE\$1ME* ke alamat email yang valid.
```
Parameters:
Email:
Type: String
Default: UPDATE_ME # <- change to a valid abc@def.xyz email address
```
1. Dari `cloudformation` folder, perbarui CloudFormation tumpukan dengan AWS CLI perintah berikut:
```
aws cloudformation update-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml
```
1. Tunggu sampai status CloudFormation tumpukan`UPDATE_COMPLETE`, yang akan memakan waktu beberapa menit. Gunakan AWS CLI perintah berikut untuk memeriksa status:
```
aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus"
```
------
Ketika pembaruan selesai, Scorekeep memulai ulang dan membuat langganan topik SNS. Periksa email Anda dan konfirmasikan langganan untuk melihat pembaruan saat Anda menyelesaikan game. Buka peta jejak untuk memverifikasi bahwa panggilan ke SNS tidak lagi gagal.
## Jelajahi aplikasi sampel
Aplikasi sampel adalah API web HTTP di Java yang dikonfigurasi untuk menggunakan X-Ray SDK for Java. Ketika Anda menerapkan aplikasi dengan CloudFormation template, itu akan membuat tabel DynamoDB, Amazon ECS Cluster, dan layanan lain yang diperlukan untuk menjalankan Scorekeep di ECS. File definisi tugas untuk ECS dibuat melalui CloudFormation. File ini mendefinisikan gambar kontainer yang digunakan per tugas dalam cluster ECS. Gambar-gambar ini diperoleh dari ECR publik X-Ray resmi. Image container API scorekeep memiliki API yang dikompilasi dengan Gradle. Gambar kontainer dari wadah frontend Scorekeep melayani frontend menggunakan server proxy nginx. Server ini merutekan permintaan ke jalur yang dimulai dengan /api ke API.
Untuk instrumentasi permintaan HTTP masuk, aplikasi menambahkan `TracingFilter` yang disediakan oleh SDK.
**Example src/main/java/scorekeep/WebConfig.java - filter servlet**
```
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");
}
...
```
Filter ini mengirimkan pelacakan data tentang semua permintaan masuk yang melayani aplikasi, termasuk permintaan URL, metode, status respons, waktu mulai, dan waktu berakhir.
Aplikasi ini juga membuat panggilan hilir ke DynamoDB menggunakan AWS SDK untuk Java. Untuk instrumen panggilan ini, aplikasi hanya mengambil submodul AWS terkait SDK sebagai dependensi, dan X-Ray SDK for Java secara otomatis menginstrumentasikan semua klien SDK. AWS
Aplikasi ini menggunakan `Docker` untuk membangun kode sumber on-instance dengan `Gradle Docker Image` dan `Scorekeep API Dockerfile` file untuk menjalankan JAR yang dapat dieksekusi yang dihasilkan Gradle. `ENTRYPOINT`
**Example penggunaan Docker untuk membangun melalui Gradle Docker Image**
```
docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build
```
**Example TITIK MASUK Dockerfile**
```
ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ]
```
File `build.gradle` mengunduh submodul SDK dari Maven selama kompilasi dengan menyatakannya sebagai dependensi.
**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")
...
}
dependencyManagement {
imports {
mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67")
mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0")
}
}
```
Submodul Instrumentor inti, AWS AWS SDK, dan SDK adalah semua yang diperlukan untuk secara otomatis instrumen panggilan hilir yang dibuat dengan SDK. AWS
Untuk menyampaikan data segmen mentah ke X-Ray API, daemon X-Ray diperlukan untuk mendengarkan lalu lintas pada port UDP 2000. *Untuk melakukannya, aplikasi memiliki daemon X-Ray yang dijalankan dalam wadah yang digunakan bersama aplikasi Scorekeep pada ECS sebagai wadah sespan.* Lihat topik [daemon X-Ray](xray-daemon.md) untuk informasi lebih lanjut.
**Example Definisi Kontainer Daemon X-Ray dalam Definisi Tugas ECS**
```
...
Resources:
ScorekeepTaskDefinition:
Type: AWS::ECS::TaskDefinition
Properties:
ContainerDefinitions:
...
- Cpu: '256'
Essential: true
Image: amazon/aws-xray-daemon
MemoryReservation: '128'
Name: xray-daemon
PortMappings:
- ContainerPort: '2000'
HostPort: '2000'
Protocol: udp
...
```
X-Ray SDK for Java menyediakan kelas bernama `AWSXRay` yang menyediakan pencatat global, sebuah `TracingHandler` yang dapat Anda gunakan untuk instrumentasi kode Anda. Anda dapat mengonfigurasi pencatat global untuk menyesuaikan `AWSXRayServletFilter` yang membuat segmen untuk panggilan HTTP masuk. Sampel mencakup blok statis di kelas `WebConfig` yang mengonfigurasi pencatat global dengan plugin dan aturan sampling.
**Example src/main/java/scorekeep/WebConfig.java - perekam**
```
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.plugins.ECSPlugin;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
...
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new ECSPlugin()).withPlugin(new EC2Plugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
...
}
}
```
Contoh ini menggunakan builder untuk memuat aturan sampling dari file bernama `sampling-rules.json`. Aturan sampling menentukan tingkat saat SDK mencatat segmen untuk permintaan masuk.
**Example src/main/java/resources/sampling-aturan.json**
```
{
"version": 1,
"rules": [
{
"description": "Resource creation.",
"service_name": "*",
"http_method": "POST",
"url_path": "/api/*",
"fixed_target": 1,
"rate": 1.0
},
{
"description": "Session polling.",
"service_name": "*",
"http_method": "GET",
"url_path": "/api/session/*",
"fixed_target": 0,
"rate": 0.05
},
{
"description": "Game polling.",
"service_name": "*",
"http_method": "GET",
"url_path": "/api/game/*/*",
"fixed_target": 0,
"rate": 0.05
},
{
"description": "State polling.",
"service_name": "*",
"http_method": "GET",
"url_path": "/api/state/*/*/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
File aturan sampling menentukan empat aturan sampling kustom dan aturan default. Untuk setiap permintaan masuk, SDK mengevaluasi aturan kustom sesuai urutan penentuannya. SDK menerapkan aturan pertama yang cocok dengan permintaan metode, jalur, dan nama layanan. Untuk Scorekeep, aturan pertama menangkap semua permintaan POST (panggilan pembuatan sumber daya) dengan menerapkan target tetap dari satu permintaan per detik dan tingkat 1,0, atau 100 persen permintaan setelah target tetap terpenuhi.
Tiga aturan kustom lainnya menerapkan tingkat lima persen tanpa target tetap untuk sesi, game, dan baca status (permintaan GET). Hal ini meminimalkan jumlah pelacakan untuk panggilan periodik yang dibuat front end secara otomatis setiap beberapa detik untuk memastikan konten diperbarui. Untuk semua permintaan lainnya, file menentukan tingkat default dari satu permintaan per detik dan tingkat 10 persen.
Aplikasi sampel juga menunjukkan cara menggunakan fitur lanjutan seperti instrumentasi klien SDK manual, membuat tambahan subsegmen, dan panggilan HTTP keluar. Untuk informasi selengkapnya, lihat [AWS X-Ray aplikasi sampel](xray-scorekeep.md).
## Opsional: Kebijakan hak istimewa terbatas
Kontainer Scorekeep ECS mengakses sumber daya menggunakan kebijakan akses penuh, seperti dan. `AmazonSNSFullAccess` `AmazonDynamoDBFullAccess` Menggunakan kebijakan akses penuh bukanlah praktik terbaik untuk aplikasi produksi. Contoh berikut memperbarui kebijakan DynamoDB IAM untuk meningkatkan keamanan aplikasi. Untuk mempelajari lebih lanjut tentang praktik terbaik keamanan dalam kebijakan IAM, lihat [Identitas dan manajemen akses untuk AWS X-Ray](security-iam.md).
**Example template cf-resources.yaml Definisi peran ECSTask**
```
ECSTaskRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
-
Effect: "Allow"
Principal:
Service:
- "ecs-tasks.amazonaws.com"
Action:
- "sts:AssumeRole"
ManagedPolicyArns:
- "arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess"
- "arn:aws:iam::aws:policy/AmazonSNSFullAccess"
- "arn:aws:iam::aws:policy/AWSXrayFullAccess"
RoleName: "scorekeepRole"
```
Untuk memperbarui kebijakan Anda, pertama-tama Anda mengidentifikasi ARN sumber daya DynamoDB Anda. Kemudian Anda menggunakan ARN dalam kebijakan IAM khusus. Terakhir, Anda menerapkan kebijakan itu ke profil instans Anda.
**Untuk mengidentifikasi ARN sumber daya DynamoDB Anda:**
1. Buka [Konsol DynamoDB](https://console.aws.amazon.com/dynamodbv2).
1. Pilih **Tabel** dari bilah navigasi kiri.
1. Pilih salah satu `scorekeep-*` untuk menampilkan halaman detail tabel.
1. Di bawah tab **Ikhtisar**, pilih **Info tambahan** untuk memperluas bagian dan melihat Nama Sumber Daya Amazon (ARN). Salin nilai ini.
1. Masukkan ARN ke dalam kebijakan IAM berikut, ganti `AWS_ACCOUNT_ID` nilai `AWS_REGION` dan dengan wilayah dan ID akun spesifik Anda. Kebijakan baru ini hanya mengizinkan tindakan yang ditentukan, bukan `AmazonDynamoDBFullAccess` kebijakan yang mengizinkan tindakan apa pun.
**Example**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ScorekeepDynamoDB",
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:Scan",
"dynamodb:Query"
],
"Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/scorekeep-*"
}
]
}
```
------
Tabel yang dibuat aplikasi mengikuti konvensi penamaan yang konsisten. Anda dapat menggunakan `scorekeep-*` format untuk menunjukkan semua tabel Scorekeep.
**Ubah kebijakan IAM Anda**
1. Buka [peran tugas Scorekeep (ScoreKeeProle](https://console.aws.amazon.com/iamv2/home#/roles/details/scorekeepRole)) dari konsol IAM.
1. Pilih kotak centang di samping `AmazonDynamoDBFullAccess` kebijakan dan pilih **Hapus** untuk menghapus kebijakan ini.
1. Pilih **Tambahkan izin**, lalu **Lampirkan kebijakan**, dan terakhir **Buat kebijakan**.
1. Pilih tab **JSON** dan tempel kebijakan yang dibuat di atas.
1. Pilih **Berikutnya: Tag** di bagian bawah halaman.
1. Pilih **Berikutnya: Tinjau** di bagian bawah halaman.
1. Untuk **Nama**, tetapkan nama untuk kebijakan tersebut.
1. Pilih **Buat kebijakan** di bagian bawah halaman.
1. Lampirkan kebijakan yang baru dibuat ke `scorekeepRole` peran. Mungkin perlu beberapa menit agar kebijakan terlampir berlaku.
Jika Anda telah melampirkan kebijakan baru ke `scorekeepRole` peran, Anda harus melepaskannya sebelum menghapus CloudFormation tumpukan, karena kebijakan terlampir ini akan memblokir tumpukan agar tidak dihapus. Kebijakan dapat dipisahkan secara otomatis dengan menghapus kebijakan.
**Hapus kebijakan IAM kustom Anda**
1. Buka [konsol IAM](https://console.aws.amazon.com/iam).
1. Pilih **Kebijakan** dari bilah navigasi kiri.
1. Cari nama kebijakan kustom yang Anda buat sebelumnya di bagian ini, dan pilih tombol radio di sebelah nama kebijakan untuk menyorotnya.
1. Pilih drop-down **Tindakan** dan kemudian pilih **Hapus**.
1. Ketik nama kebijakan kustom, lalu pilih **Hapus** untuk mengonfirmasi penghapusan. Ini akan secara otomatis melepaskan kebijakan dari `scorekeepRole` peran.
## Bersihkan
Ikuti langkah-langkah berikut untuk menghapus sumber daya aplikasi Scorekeep:
**catatan**
Jika Anda membuat dan melampirkan kebijakan kustom menggunakan bagian sebelumnya dari tutorial ini, Anda harus menghapus kebijakan dari `scorekeepRole` sebelum menghapus CloudFormation tumpukan.
------
#### [ Konsol Manajemen AWS ]
**Hapus aplikasi sampel menggunakan Konsol Manajemen AWS**
1. Buka [konsol CloudFormation](https://console.aws.amazon.com/cloudformation/)
1. Pilih tombol radio di sebelah nama `scorekeep` tumpukan dalam daftar, lalu pilih **Hapus**.
1. CloudFormation Tumpukan sekarang sedang dihapus. Status tumpukan akan berlangsung `DELETE_IN_PROGRESS` selama beberapa menit sampai semua sumber daya dihapus. Status akan disegarkan secara berkala, atau Anda dapat me-refresh halaman.
------
#### [ AWS CLI ]
**Hapus aplikasi sampel menggunakan AWS CLI**
1. Masukkan AWS CLI perintah berikut untuk menghapus CloudFormation tumpukan:
```
aws cloudformation delete-stack --stack-name scorekeep
```
1. Tunggu sampai CloudFormation tumpukan tidak ada lagi, yang akan memakan waktu sekitar lima menit. Gunakan AWS CLI perintah berikut untuk memeriksa status:
```
aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus"
```
------
## Langkah selanjutnya
Pelajari selengkapnya tentang X-Ray di bab berikutnya, [AWS X-Ray konsep](xray-concepts.md).
Untuk menggunakan aplikasi Anda sendiri, pelajari lebih lanjut tentang X-Ray SDK for Java atau salah satu SDKs X-Ray lainnya:
+ **X-Ray SDK for Java** – [AWS X-Ray SDK for Java](xray-sdk-java.md)
+ **X-Ray SDK for Node.js** – [AWS X-Ray SDK untuk Node.js](xray-sdk-nodejs.md)
+ **X-Ray SDK for .NET** – [AWS X-Ray SDK for .NET](xray-sdk-dotnet.md)
Untuk menjalankan daemon X-Ray secara lokal atau aktif, lihat. AWS[AWS X-Ray daemon](xray-daemon.md)
Untuk berkontribusi pada aplikasi sampel GitHub, lihat [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted).
# Menginstrumentasi klien AWS SDK secara manual
**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 secara otomatis menginstrumentasikan AWS semua klien SDK saat [Anda menyertakan submodul SDK Instrumentor AWS dalam](xray-sdk-java.md#xray-sdk-java-dependencies) dependensi build Anda.
Anda dapat menonaktifkan instrumentasi klien otomatis dengan menghapus submodul Instrumentor. Hal ini memungkinkan Anda untuk menginstruksikan beberapa klien secara manual sambil mengabaikan yang lain, atau menggunakan pengendali pelacakan yang berbeda pada klien yang berbeda.
Untuk mengilustrasikan dukungan untuk menginstrumentasi klien AWS SDK tertentu, aplikasi meneruskan penangan penelusuran `AmazonDynamoDBClientBuilder` sebagai penangan permintaan dalam model pengguna, game, dan sesi. Perubahan kode ini memberi tahu SDK untuk memasukkan semua panggilan ke DynamoDB menggunakan klien tersebut.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java)— Instrumentasi klien AWS SDK manual**
```
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 SessionModel {
private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
.withRegion(Constants.REGION)
.withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder()))
.build();
private DynamoDBMapper mapper = new DynamoDBMapper(client);
```
Jika Anda menghapus submodul AWS SDK Instrumentor dari dependensi proyek, hanya klien AWS SDK yang diinstrumentasi secara manual yang muncul di peta jejak.
# Membuat subsegmen tambahan
**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
Di kelas model pengguna, aplikasi secara manual membuat subsegmen untuk mengelompokkan semua panggilan hilir yang dibuat dalam fungsi `saveUser` dan menambahkan metadata.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java) - Subsegmen kustom**
```
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);
...
public void saveUser(User user) {
// Wrap in subsegment
Subsegment subsegment = AWSXRay.beginSubsegment("## UserModel.saveUser");
try {
mapper.save(user);
} catch (Exception e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment();
}
}
```
# Merekam anotasi, metadata, dan pengguna IDs
**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
Di kelas model game, aplikasi mencatat objek `Game` di blok [metadata](xray-sdk-java-segment.md#xray-sdk-java-segment-metadata) setiap kali game disimpan di DynamoDB. Secara terpisah, aplikasi merekam game IDs dalam [anotasi](xray-sdk-java-segment.md#xray-sdk-java-segment-annotations) untuk digunakan dengan [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();
}
}
```
Dalam pengontrol bergerak, aplikasi merekam [pengguna IDs](xray-sdk-java-segment.md#xray-sdk-java-segment-userid) dengan`setUser`. Pengguna IDs direkam dalam bidang terpisah pada segmen dan diindeks untuk digunakan dengan pencarian.
**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);
}
```
# Instrumentasi panggilan HTTP keluar
**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
Kelas pabrik pengguna menunjukkan bagaimana aplikasi menggunakan versi X-Ray SDK for Java dari `HTTPClientBuilder` untuk menginstrumen panggilan HTTP keluar.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java)— HTTPClient instrumentasi**
```
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://uinames.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();
}
}
```
Jika saat ini Anda menggunakan `org.apache.http.impl.client.HttpClientBuilder`, Anda cukup menukar pernyataan impor untuk kelas tersebut dengan satu untuk `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder`.
# Menginstrumentasi panggilan ke basis data PostgreSQL
**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
`application-pgsql.properties` file menambahkan pencegat penelusuran X-Ray PostgreSQL ke sumber data yang dibuat di [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java).
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties) – Instrumentasi basis data PostgreSQL**
```
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
```
**catatan**
Lihat [Mengonfigurasi basis data dengan Elastic Beanstalk](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.managing.db.html) di *AWS Elastic Beanstalk Panduan Developer* untuk detail tentang cara menambahkan basis data PostgreSQL ke lingkungan aplikasi.
Versi demo X-Ray di cabang `xray` termasuk demo yang menggunakan sumber data berinstrumen untuk menghasilkan pelacakan yang menunjukkan informasi tentang kueri SQL yang dihasilkannya. Navigasikan ke jalur `/#/xray` dalam aplikasi yang sedang berjalan atau pilih **Didukung oleh AWS X-Ray** di bilah navigasi untuk melihat halaman demo.
![\[AWS X-Ray integration demo page showing game session tracing and SQL query tracing options.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-demo.png)
Pilih **Lacak kueri SQL** untuk menyimulasikan sesi game dan menyimpan hasil dalam basis data terlampir. Kemudian, pilih **Lihat jejak di AWS X-Ray** untuk melihat daftar jejak yang difilter yang mengenai `/api/history` rute API.
Pilih salah satu pelacakan dari daftar untuk melihat linimasa, termasuk kueri SQL.
![\[Timeline view of a trace showing method, response, duration, and age for a GET request.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-trace-sql.png)
# Fungsi instrumentasi AWS Lambda
**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
Scorekeep menggunakan dua AWS Lambda fungsi. Yang pertama adalah fungsi Node.js dari cabang `lambda` yang menghasilkan nama acak untuk pengguna baru. Ketika pengguna membuat sesi tanpa memasukkan nama, aplikasi memanggil fungsi bernama `random-name` dengan AWS SDK untuk Java. X-Ray SDK for Java merekam informasi tentang panggilan ke Lambda di subsegmen seperti panggilan lain yang dibuat dengan klien SDK berinstrumen. AWS
**catatan**
Menjalankan fungsi Lambda `random-name` membutuhkan pembuatan sumber daya tambahan di luar lingkungan Elastic Beanstalk. Lihat readme untuk informasi selengkapnya dan petunjuk: [Integrasi AWS Lambda](https://github.com/awslabs/eb-java-scorekeep/tree/xray/README.md#aws-lambda-integration).
Fungsi kedua, `scorekeep-worker`, adalah fungsi Python yang berjalan secara independen dari API Scorekeep. Saat game berakhir, API menulis ID sesi dan ID game ke antrean SQS. Fungsi pekerja membaca item dari antrean, dan memanggil API Scorekeep untuk membuat catatan lengkap dari setiap sesi game untuk penyimpanan di Amazon S3.
Scorekeep mencakup CloudFormation template dan skrip untuk membuat kedua fungsi. Karena Anda harus memaketkan X-Ray SDK dengan kode fungsi, templat membuat fungsi tanpa kode apa pun. Ketika Anda men-deploy Scorekeep, file konfigurasi yang disertakan dalam folder `.ebextensions` membuat paket bundel sumber yang meliputi SDK, dan memperbarui kode fungsi dan konfigurasi dengan AWS Command Line Interface.
**Topics**
+ [Nama acak](#scorekeep-lambda-randomname)
+ [Pekerja](#scorekeep-lambda-worker)
## Nama acak
Scorekeep memanggil fungsi nama acak ketika pengguna memulai sesi game tanpa masuk atau menentukan nama pengguna. Saat Lambda memproses panggilan ke `random-name`, Lambda membaca [header pelacakan](xray-concepts.md#xray-concepts-tracingheader), yang berisi ID pelacakan dan keputusan pengambilan sampel yang ditulis oleh X-Ray SDK for Java.
Untuk setiap permintaan sampel, Lambda menjalankan daemon X-Ray dan menulis dua segmen. Segmen pertama mencatat informasi tentang panggilan ke Lambda yang memanggil fungsi. Segmen ini berisi informasi yang sama dengan subsegmen yang dicatat oleh Scorekeep, namun dari sudut pandang Lambda. Segmen kedua menunjukkan pekerjaan yang dilakukan fungsi.
Lambda melewati segmen fungsi ke X-Ray SDK melalui konteks fungsi. Saat Anda menginstrumentasi fungsi Lambda, Anda tidak boleh menggunakan SDK untuk [membuat segmen untuk permintaan masuk](xray-sdk-nodejs-middleware.md). Lambda menyediakan segmen tersebut, dan Anda menggunakan SDK untuk menginstrumentasi klien dan menulis subsegment.
![\[Lacak peta yang menunjukkan bagaimana scorekeep memanggil fungsi Lambda untuk mendapatkan nama acak untuk pengguna baru\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-servicemap-lambda-node.png)
Fungsi `random-name` diimplementasikan dalam Node.js. Ini menggunakan SDK untuk JavaScript di Node.js untuk mengirim notifikasi dengan Amazon SNS, dan X-Ray SDK untuk Node.js untuk instrumen AWS klien SDK. Untuk menulis anotasi, fungsi membuat subsegmen kustom dengan `AWSXRay.captureFunc`, dan menulis anotasi dalam fungsi yang diinstrumentasi. Di Lambda, Anda tidak dapat menulis anotasi langsung ke segmen fungsi, namun hanya ke subsegmen yang Anda buat.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js) – Fungsi Lambda nama acak**
```
var AWSXRay = require('aws-xray-sdk-core');
var AWS = AWSXRay.captureAWS(require('aws-sdk'));
AWS.config.update({region: process.env.AWS_REGION});
var Chance = require('chance');
var myFunction = function(event, context, callback) {
var sns = new AWS.SNS();
var chance = new Chance();
var userid = event.userid;
var name = chance.first();
AWSXRay.captureFunc('annotations', function(subsegment){
subsegment.addAnnotation('Name', name);
subsegment.addAnnotation('UserID', event.userid);
});
// Notify
var params = {
Message: 'Created randon name "' + name + '"" for user "' + userid + '".',
Subject: 'New user: ' + name,
TopicArn: process.env.TOPIC_ARN
};
sns.publish(params, function(err, data) {
if (err) {
console.log(err, err.stack);
callback(err);
}
else {
console.log(data);
callback(null, {"name": name});
}
});
};
exports.handler = myFunction;
```
Fungsi ini dibuat secara otomatis ketika Anda men-deploy aplikasi sampel ke Elastic Beanstalk. Cabang `xray` termasuk skrip untuk membuat fungsi Lambda kosong. File konfigurasi dalam `.ebextensions` folder membangun paket fungsi dengan `npm install` selama penerapan, dan kemudian memperbarui fungsi Lambda dengan CLI. AWS
## Pekerja
Fungsi pekerja yang diinstrumentasi disediakan di cabangnya sendiri, `xray-worker`, karena tidak dapat berjalan kecuali Anda membuat fungsi pekerja dan sumber daya terkait terlebih dahulu. Lihat [readme cabang](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/README.md) untuk instruksi.
Fungsi ini dipicu oleh CloudWatch acara Amazon Events yang dibundel setiap 5 menit. Ketika berjalan, fungsi menarik item dari antrean Amazon SQS yang dikelola Scorekeep. Setiap pesan berisi informasi tentang game yang sudah selesai.
Pekerja menarik catatan dan dokumen game dari tabel lain tempat game mencatat referensi.. Misalnya, catatan game di DynamoDB meliputi daftar gerakan yang dieksekusi selama game berlangsung. Daftar ini tidak berisi gerakan itu sendiri, melainkan IDs gerakan yang disimpan dalam tabel terpisah.
Sesi, dan status juga disimpan sebagai referensi. Hal ini membuat entri dalam tabel game menjadi terlalu besar, tetapi membutuhkan panggilan tambahan untuk mendapatkan semua informasi tentang game. Pekerja melakukan deferensi pada semua entri ini dan membuat catatan lengkap game sebagai dokumen tunggal di Amazon S3. Saat Anda ingin melakukan analitik pada data, Anda dapat melakukan kueri langsung di atasnya di Amazon S3 dengan Amazon Athena tanpa menjalankan migrasi data baca-berat untuk mendapatkan data Anda dari DynamoDB.
![\[Lacak peta yang menunjukkan bagaimana fungsi scorekeep worker menggunakan Amazon SQS, Amazon S3, dan API scorekeep.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-servicemap-lambdaworker-node.png)
Fungsi pekerja juga mengaktifkan pelacakan aktif dalam konfigurasinya di AWS Lambda. Tidak seperti fungsi nama acak, pekerja tidak menerima permintaan dari aplikasi yang diinstrumentasi, sehingga AWS Lambda tidak menerima header penelusuran. Dengan pelacakan aktif, Lambda membuat ID pelacakan dan membuat keputusan pengambilan sampel.
X-Ray SDK untuk Python hanyalah beberapa baris di bagian atas fungsi yang mengimpor SDK dan menjalankan `patch_all` fungsinya untuk menambal AWS SDK for Python (Boto) dan yang digunakannya untuk memanggil Amazon SQS HTTclients dan Amazon S3. Ketika pekerja memanggil API Scorekeep, SDK menambahkan [header pelacakan](xray-concepts.md#xray-concepts-tracingheader) pada permintaan untuk melacak panggilan melalui API.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py) – Fungsi Lambda pekerja**
```
import os
import boto3
import json
import requests
import time
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all()
queue_url = os.environ['WORKER_QUEUE']
def lambda_handler(event, context):
# Create SQS client
sqs = boto3.client('sqs')
s3client = boto3.client('s3')
# Receive message from SQS queue
response = sqs.receive_message(
QueueUrl=queue_url,
AttributeNames=[
'SentTimestamp'
],
MaxNumberOfMessages=1,
MessageAttributeNames=[
'All'
],
VisibilityTimeout=0,
WaitTimeSeconds=0
)
...
```
# Menginstrumentasi kode perusahaan rintisan
**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 secara otomatis membuat segmen untuk permintaan masuk. Selama permintaan berada dalam cakupan, Anda dapat menggunakan klien berinstrumen dan mencatat subsegmen tanpa masalah. Namun, jika Anda mencoba menggunakan klien yang diinstrumentasi dalam kode startup, Anda akan mendapatkan [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html)file.
Kode startup berjalan di luar request/response aliran standar aplikasi web, jadi Anda perlu membuat segmen secara manual untuk menginstrumennya. Scorekeep menunjukkan instrumentasi kode perusahaan rintisan dalam file `WebConfig`. Scorekeep memanggil basis data SQL dan Amazon SNS selama perusahaan rintisan.
![\[Diagram showing client requests to Scorekeeper-init, which connects to SQL database and SNS.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-servicemap-init.png)
Kelas `WebConfig` default membuat langganan Amazon SNS untuk notifikasi. Untuk menyediakan segmen bagi SDK X-Ray untuk menulis ketika klien Amazon SNS digunakan, Scorekeep memanggil `beginSegment` dan `endSegment` pada catatan global.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49)— Klien AWS SDK yang diinstrumentasi dalam kode startup**
```
AWSXRay.beginSegment("Scorekeep-init");
if ( System.getenv("NOTIFICATION_EMAIL") != null ){
try { Sns.createSubscription(); }
catch (Exception e ) {
logger.warn("Failed to create subscription for email "+ System.getenv("NOTIFICATION_EMAIL"));
}
}
AWSXRay.endSegment();
```
Di `RdsWebConfig`, yang Scorekeep gunakan saat basis data Amazon RDS terhubung, konfigurasi juga membuat segmen untuk klien SQL yang digunakan Hibernate saat menerapkan skema basis data selama perusahaan rintisan.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83) – Klien basis data SQL yang diinstrumentasi dalam kode perusahaan rintisan**
```
@PostConstruct
public void schemaExport() {
EntityManagerFactoryImpl entityManagerFactoryImpl = (EntityManagerFactoryImpl) localContainerEntityManagerFactoryBean.getNativeEntityManagerFactory();
SessionFactoryImplementor sessionFactoryImplementor = entityManagerFactoryImpl.getSessionFactory();
StandardServiceRegistry standardServiceRegistry = sessionFactoryImplementor.getSessionFactoryOptions().getServiceRegistry();
MetadataSources metadataSources = new MetadataSources(new BootstrapServiceRegistryBuilder().build());
metadataSources.addAnnotatedClass(GameHistory.class);
MetadataImplementor metadataImplementor = (MetadataImplementor) metadataSources.buildMetadata(standardServiceRegistry);
SchemaExport schemaExport = new SchemaExport(standardServiceRegistry, metadataImplementor);
AWSXRay.beginSegment("Scorekeep-init");
schemaExport.create(true, true);
AWSXRay.endSegment();
}
```
`SchemaExport` berjalan secara otomatis dan menggunakan klien SQL. Karena klien diinstrumentasi, Scorekeep harus mengganti implementasi default dan menyediakan segmen SDK untuk digunakan ketika klien dipanggil.
# Skrip instrumentasi
**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 juga dapat menginstrumentasi kode yang bukan bagian dari aplikasi Anda. Ketika daemon X-Ray berjalan, ia akan menyampaikan segmen apa pun yang diterimanya ke X-Ray, meskipun tidak dihasilkan oleh SDK X-Ray. Scorekeep menggunakan skrip sendiri untuk instrumen membangun yang mengompilasi aplikasi selama deployment.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh) – Skrip bangunan berinstrumen**
```
SEGMENT=$(python bin/xray_start.py)
gradle build --quiet --stacktrace &> /var/log/gradle.log; GRADLE_RETURN=$?
if (( GRADLE_RETURN != 0 )); then
echo "Gradle failed with exit status $GRADLE_RETURN" >&2
python bin/xray_error.py "$SEGMENT" "$(cat /var/log/gradle.log)"
exit 1
fi
python bin/xray_success.py "$SEGMENT"
```
[https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py), [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py) dan [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py) adalah skrip Python sederhana yang mengonstruksi objek segmen, mengonversinya menjadi dokumen JSON, dan mengirimkannya ke daemon melalui UDP. Jika build Gradle gagal, Anda dapat menemukan pesan kesalahan dengan mengklik node **scorekeep-build** di peta jejak konsol X-Ray.
![\[Diagram showing client connection to Scorekeep-build with average time of 14.6s and 0.07/min.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-servicemap-builderror.png)
![\[Timeline view showing Scorekeep-build process with 14.6 second duration and warning icon.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-timeline-builderror.png)
![\[Error message showing build failure due to missing ElasticBeanstalkPlugin symbol in RdsWebConfig class.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-exception-builderror.png)
# Menginstrumentasi klien aplikasi web
**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
Di cabang [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito), Scorekeep menggunakan Amazon Cognito untuk memungkinkan pengguna membuat akun dan masuk dengan akun tersebut untuk mengambil informasi pengguna mereka dari kolam pengguna Amazon Cognito. Saat pengguna masuk, Scorekeep menggunakan kumpulan identitas Amazon Cognito untuk mendapatkan kredensi AWS sementara untuk digunakan dengan. AWS SDK untuk JavaScript
Kolam identitas dikonfigurasi untuk membiarkan masuk pengguna menulis penelusuran data ke AWS X-Ray. Aplikasi web menggunakan kredensialnya untuk mencatat ID pengguna yang masuk, jalur peramban, dan tampilan panggilan klien ke API Skorrekeep.
Sebagian besar pekerjaan dilakukan di kelas layanan bernama `xray`. Kelas layanan ini menyediakan metode untuk menghasilkan pengidentifikasi yang diperlukan, menciptakan segmen yang sedang berlangsung, menyelesaikan segmen, dan mengirimkan dokumen segmen ke API X-Ray.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js) – Catat dan unggah segmen**
```
...
service.beginSegment = function() {
var segment = {};
var traceId = '1-' + service.getHexTime() + '-' + service.getHexId(24);
var id = service.getHexId(16);
var startTime = service.getEpochTime();
segment.trace_id = traceId;
segment.id = id;
segment.start_time = startTime;
segment.name = 'Scorekeep-client';
segment.in_progress = true;
segment.user = sessionStorage['userid'];
segment.http = {
request: {
url: window.location.href
}
};
var documents = [];
documents[0] = JSON.stringify(segment);
service.putDocuments(documents);
return segment;
}
service.endSegment = function(segment) {
var endTime = service.getEpochTime();
segment.end_time = endTime;
segment.in_progress = false;
var documents = [];
documents[0] = JSON.stringify(segment);
service.putDocuments(documents);
}
service.putDocuments = function(documents) {
var xray = new AWS.XRay();
var params = {
TraceSegmentDocuments: documents
};
xray.putTraceSegments(params, function(err, data) {
if (err) {
console.log(err, err.stack);
} else {
console.log(data);
}
})
}
```
Metode ini disebut di header dan fungsi`transformResponse` di layanan sumber daya yang digunakan aplikasi web untuk memanggil API Skorrekeep. Untuk menyertakan segmen klien dalam pelacakan yang sama sebagai segmen yang menghasilkan API, aplikasi web harus menyertakan ID pelacakan dan ID segmen di [header pelacakan](xray-concepts.md#xray-concepts-tracingheader) (`X-Amzn-Trace-Id`) yang dapat dibaca X-Ray SDK. Ketika aplikasi Java instrumented menerima permintaan dengan header ini, X-Ray SDK for Java menggunakan ID penelusuran yang sama dan membuat segmen dari klien aplikasi web induk dari segmennya.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js) - Mencatat segmen untuk panggilan sumber daya sudut dan menulis header pelacakan**
```
var module = angular.module('scorekeep');
module.factory('SessionService', function($resource, api, XRay) {
return $resource(api + 'session/:id', { id: '@_id' }, {
segment: {},
get: {
method: 'GET',
headers: {
'X-Amzn-Trace-Id': function(config) {
segment = XRay.beginSegment();
return XRay.getTraceHeader(segment);
}
},
transformResponse: function(data) {
XRay.endSegment(segment);
return angular.fromJson(data);
},
},
...
```
Peta jejak yang dihasilkan menyertakan node untuk klien aplikasi web.
![\[\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-servicemap-client.png)
Penelusuran yang mencakup segmen dari aplikasi web menampilkan URL yang dilihat pengguna di peramban (jalur yang dimulai dengan `/#/`). Tanpa instrumentasi klien, Anda hanya mendapatkan URL sumber daya API yang dipanggil aplikasi web (path dimulai dengan `/api/`).
![\[\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-traces-client.png)
# Menggunakan klien berinstrumen di utas pekerja
**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
Scorekeep menggunakan utas pekerja untuk memublikasikan notifikasi ke Amazon SNS ketika pengguna memenangkan game. Penerbitan notifikasi membutuhkan waktu lebih lama daripada gabungan operasi permintaan lainnya, dan tidak memengaruhi klien atau pengguna. Oleh karena itu, melakukan tugas secara asinkron adalah cara yang baik untuk meningkatkan waktu respons.
Namun, X-Ray SDK for Java tidak mengetahui segmen mana yang aktif saat utas dibuat. Akibatnya, ketika Anda mencoba menggunakan AWS SDK untuk Java klien yang diinstrumentasi di dalam utas, itu akan melempar utas yang `SegmentNotFoundException` rusak.
**Example Web-1.error.log**
```
Exception in thread "Thread-2" com.amazonaws.xray.exceptions.SegmentNotFoundException: Failed to begin subsegment named 'AmazonSNS': segment cannot be found.
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)
at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
...
```
Untuk memperbaikinya, aplikasi menggunakan `GetTraceEntity` untuk mendapatkan referensi ke segmen di utas utama, dan `Entity.run()` untuk menjalankan kode utas pekerja dengan aman dengan akses ke konteks segmen.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70) – Melewati konteks pelacakan ke utas pekerja**
```
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.AWSXRayRecorder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html);
import [com.amazonaws.xray.entities.Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.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);
...
Entity segment = recorder.getTraceEntity();
Thread comm = new Thread() {
public void run() {
segment.run(() -> {
Subsegment subsegment = AWSXRay.beginSubsegment("## Send notification");
Sns.sendNotification("Scorekeep game completed", "Winner: " + userId);
AWSXRay.endSubsegment();
}
}
```
Karena permintaan sekarang diselesaikan sebelum panggilan ke Amazon SNS, aplikasi membuat subsegmen terpisah untuk utas. Hal ini mencegah X-Ray SDK menutup segmen sebelum mencatat respons dari Amazon SNS. Jika tidak ada subsegmen yang terbuka saat Scorekeep menyelesaikan permintaan, respons dari Amazon SNS bisa hilang.
![\[\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-workerthread.png)
Lihat [Melewati konteks segmen antara benang dalam aplikasi multithreaded](xray-sdk-java-multithreading.md) untuk informasi selengkapnya tentang multithreading.