Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# AWS X-Ray SDK for Ruby
**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 Ruby adalah serangkaian pustaka untuk aplikasi web Java yang menyediakan kelas dan metode untuk menghasilkan dan mengirim penelusuran data ke daemon X-Ray. Data pelacakan mencakup informasi tentang permintaan HTTP masuk yang disajikan oleh aplikasi, dan panggilan yang dilakukan aplikasi ke layanan hilir menggunakan AWS SDK, klien HTTP, atau klien rekaman aktif. Anda juga dapat membuat segmen secara manual dan menambahkan informasi debug dalam anotasi dan metadata.
Anda dapat mengunduh SDK dengan menambahkannya ke gemfile Anda dan menjalankan `bundle install`.
**Example Gemfile**
```
gem 'aws-sdk'
```
Jika Anda menggunakan Rails, mulailah dengan [Menambahkan middleware SDK X-Ray](xray-sdk-ruby-middleware.md) untuk menelusuri permintaan yang masuk. Sebuah filter permintaan membuat [segmen](xray-concepts.md#xray-concepts-segments). Ketika segmen terbuka, Anda dapat menggunakan metode klien SDK untuk menambahkan informasi ke segmen dan membuat subsegmen untuk penelusuran panggilan hilir. SDK juga secara otomatis mencatat pengecualian bahwa aplikasi Anda melempar sementara segmen terbuka. Untuk aplikasi Non-Rail, Anda dapat [membuat segmen secara manual](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual).
Selanjutnya, gunakan X-Ray SDK untuk instrumen klien AWS SDK untuk Ruby, HTTP, dan SQL Anda dengan [mengonfigurasi perekam](xray-sdk-ruby-patching.md) untuk menambal pustaka terkait. Setiap kali Anda melakukan panggilan ke hilir Layanan AWS atau sumber daya dengan klien yang diinstrumentasi, SDK akan mencatat informasi tentang panggilan di subsegmen. Layanan AWS dan sumber daya yang Anda akses dalam layanan muncul sebagai node hilir pada peta jejak untuk membantu Anda mengidentifikasi kesalahan dan masalah pembatasan pada koneksi individual.
Setelah menjalankan SDK, sesuaikan perilakunya dengan [mengonfigurasi pencatat dan penangan pesan](xray-sdk-ruby-configuration.md). Anda dapat menambahkan plugin untuk mencatat data mengenai sumber daya komputasi yang berjalan di aplikasi Anda, menyesuaikan perilaku sampling dengan mendefinisikan aturan sampling, dan mengatur tingkat log untuk melihat lebih atau kurang informasi dari SDK dalam log aplikasi Anda.
Catat informasi tambahan tentang permintaan dan pekerjaan yang dilakukan aplikasi Anda dalam [anotasi dan metadata](xray-sdk-ruby-segment.md). Anotasi adalah pasangan kunci-nilai sederhana yang diindeks untuk digunakan dengan [ekspresi filter](xray-console-filters.md), sehingga Anda dapat mencari pelacakan yang berisi data tertentu. Entri metadata kurang bersifat membatasi dan dapat mencatat seluruh objek dan array — segala yang dapat disambungkan ke dalam JSON.
**Anotasi dan Metadata**
Anotasi dan metadata adalah teks abritari yang Anda tambahkan ke segmen dengan X-Ray SDK. Anotasi diindekskan untuk digunakan dengan ekspresi filter. Metadata tidak diindeks, tetapi dapat dilihat di segmen mentah dengan konsol X-Ray atau API. Siapa pun yang Anda berikan akses baca ke X-Ray dapat melihat data ini.
Bila Anda memiliki banyak klien diinstrumentasi dalam kode Anda, segmen permintaan tunggal dapat berisi sejumlah besar subsegmen, satu untuk setiap panggilan yang dilakukan dengan klien yang diinstrumentasi. Anda dapat mengatur dan mengelompokkan subsegmen dengan menggabungkan panggilan klien di [subsegmen kustom](xray-sdk-ruby-subsegments.md). Anda dapat membuat subsegmen kustom untuk seluruh fungsi atau bagian dari kode, dan mencatat metadata dan anotasi pada subsegmen bukan menulis segala sesuatu pada segmen induk.
Untuk dokumentasi referensi kelas SDK dan metode, lihat [AWS X-Ray Referensi API SDK for Ruby](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference).
## Persyaratan
SDK X-Ray memerlukan Ruby 2.3 atau yang lebih baru dan kompatibel dengan pustaka berikut ini:
+ AWS SDK untuk Ruby versi 3.0 atau yang lebih baru
+ Versi rail 5.1 atau lebih baru
# Mengonfigurasi X-Ray SDK for Ruby
**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 Ruby mencakup kelas bernama `XRay.recorder` yang menyediakan pencatat global. Anda dapat mengonfigurasi pencatat global untuk menyesuaikan yang membuat segmen untuk panggilan HTTP masuk.
**Topics**
+ [Plugin layanan](#xray-sdk-ruby-configuration-plugins)
+ [Aturan pengambilan sampel](#xray-sdk-ruby-configuration-sampling)
+ [Pencatatan log](#xray-sdk-ruby-configuration-logging)
+ [Konfigurasi pencatat dalam kode](#xray-sdk-ruby-configuration-code)
+ [Konfigurasi pencatat dengan rail](#xray-sdk-ruby-middleware-configuration-rails)
+ [Variabel-variabel lingkungan](#xray-sdk-ruby-configuration-envvars)
## Plugin layanan
Gunakan `plugins` untuk mencatat informasi tentang layanan yang meng-hosting aplikasi Anda.
**Plugin**
+ Amazon EC2 – `ec2` menambahkan ID instans, Availability Zone, dan Grup CloudWatch Logs.
+ Elastic Beanstalk – `elastic_beanstalk` menambahkan nama lingkungan, label versi, dan ID deployment.
+ Amazon ECS – `ecs` menambahkan ID kontainer.
![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)
Untuk menggunakan plugin, tentukan di objek konfigurasi yang Anda lewati ke pencatat.
**Example main.rb – Konfigurasi plugin**
```
my_plugins = %I[ec2 elastic_beanstalk]
config = {
plugins: my_plugins,
name: 'my app',
}
XRay.recorder.configure(config)
```
Anda juga dapat menggunakan [variabel lingkungan](#xray-sdk-ruby-configuration-envvars), yang diutamakan daripada nilai-nilai yang ditetapkan dalam kode, untuk mengonfigurasi pencatat.
SDK juga menggunakan pengaturan plugin untuk mengatur bidang `origin` pada segmen. Ini menunjukkan jenis AWS sumber daya yang menjalankan aplikasi Anda. Saat Anda menggunakan beberapa plugin, SDK menggunakan urutan resolusi berikut untuk menentukan asal: ElasticBeanstalk > EKS > ECS > EC2.
## Aturan pengambilan sampel
SDK menggunakan aturan pengambilan sampel yang Anda tetapkan di konsol X-Ray untuk menentukan permintaan yang akan dicatat. Aturan default menelusuri permintaan pertama setiap detik, dan lima persen permintaan tambahan di semua layanan yang mengirim pelacakan ke X-Ray. [Buat aturan tambahan di konsol X-Ray](xray-console-sampling.md) untuk menyesuaikan jumlah data yang dicatat untuk setiap aplikasi Anda.
SDK menerapkan aturan kustom sesuai urutan penetapannya. Jika permintaan cocok dengan beberapa aturan kustom, SDK hanya menerapkan aturan pertama.
**catatan**
Jika SDK tidak dapat mencapai X-Ray untuk mendapatkan aturan pengambilan sampel, SDK akan beralih ke aturan lokal default dari permintaan pertama setiap detik, dan lima persen permintaan tambahan per host. Hal ini dapat terjadi jika host tidak memiliki izin untuk memanggil sampling APIs, atau tidak dapat terhubung ke daemon X-Ray, yang bertindak sebagai proxy TCP untuk panggilan API yang dilakukan oleh SDK.
Anda juga dapat mengonfigurasi SDK untuk memuat aturan sampling dari dokumen JSON. SDK dapat menggunakan aturan lokal sebagai cadangan jika terjadi kasus tidak dapat mengambil sampel X-Ray, atau menggunakan aturan lokal secara eksklusif.
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
Contoh ini menentukan satu aturan kustom dan aturan default. Aturan kustom menerapkan tingkat pengambilan sampel lima persen tanpa jumlah minimum permintaan untuk melacak jalur di `/api/move/`. Aturan default menelusuri permintaan pertama setiap detik dan 10 persen dari permintaan tambahan.
Kerugian dari menentukan aturan secara lokal adalah bahwa target tetap diterapkan oleh setiap instans pencatat secara independen, alih-alih dikelola oleh layanan X-Ray. Ketika Anda men-deploy lebih banyak host, laju tetap akan dikalikan, sehingga sulit untuk mengontrol jumlah data yang dicatat.
Untuk mengonfigurasi aturan cadangan, menentukan hash untuk dokumen di objek konfigurasi yang Anda berikan ke pencatat.
**Example main.rb - Konfigurasi aturan pencadangan**
```
require 'aws-xray-sdk'
my_sampling_rules = {
version: 1,
default: {
fixed_target: 1,
rate: 0.1
}
}
config = {
sampling_rules: my_sampling_rules,
name: 'my app',
}
XRay.recorder.configure(config)
```
Untuk menyimpan aturan sampling secara independen, menentukan hash dalam file terpisah dan memerlukan file untuk menariknya ke dalam aplikasi Anda.
**Example config/sampling-rules.rb**
```
my_sampling_rules = {
version: 1,
default: {
fixed_target: 1,
rate: 0.1
}
}
```
**Example main.rb - Aturan sampling dari file**
```
require 'aws-xray-sdk'
require 'config/sampling-rules.rb'
config = {
sampling_rules: my_sampling_rules,
name: 'my app',
}
XRay.recorder.configure(config)
```
Untuk menggunakan hanya aturan lokal, memerlukan aturan pengambilan sampel dan mengonfigurasi `LocalSampler`.
**Example main.rb - Aturan pengambilan sampel lokal**
```
require 'aws-xray-sdk'
require 'aws-xray-sdk/sampling/local/sampler'
config = {
sampler: LocalSampler.new,
name: 'my app',
}
XRay.recorder.configure(config)
```
Anda juga dapat mengonfigurasi pencatat global untuk menonaktifkan pengambilan sampel dan instrumen semua permintaan masuk.
**Example main.rb – Nonaktifkan pengambilan sampel**
```
require 'aws-xray-sdk'
config = {
sampling: false,
name: 'my app',
}
XRay.recorder.configure(config)
```
## Pencatatan log
Secara default, pencatat output peristiwa tingkat info untuk `$stdout`. Anda dapat menyesuaikan log dengan mendefinisikan [Pencatat](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html) di objek konfigurasi yang Anda lulus ke pencatat.
**Example main.rb – Logging**
```
require 'aws-xray-sdk'
config = {
logger: my_logger,
name: 'my app',
}
XRay.recorder.configure(config)
```
Gunakan log debug untuk mengidentifikasi masalah, seperti subsegmen yang tidak tertutup, saat Anda [menghasilkan subsegmen secara manual](xray-sdk-ruby-subsegments.md).
## Konfigurasi pencatat dalam kode
Pengaturan tambahan tersedia dari metode `configure` pada `XRay.recorder`.
+ `context_missing` – Mengatur ke `LOG_ERROR` untuk menghindari mengembalikan pengecualian ketika kode instrumentasi Anda mencoba mencatat data ketika tidak ada segmen yang terbuka.
+ `daemon_address` – Mengatur host dan port listener daemon X-Ray.
+ `name` – Atur nama layanan yang digunakan SDK untuk segmen.
+ `naming_pattern` – Atur pola nama domain untuk menggunakan [Penamaan dinamis](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming).
+ `plugins` – Catat informasi tentang sumber daya AWS aplikasi dengan [plugin](#xray-sdk-ruby-configuration-plugins).
+ `sampling` – Atur ke `false` untuk menonaktifkan pengambilan sampel.
+ `sampling_rules` – Atur hash yang berisi [Aturan pengambilan sampel](#xray-sdk-ruby-configuration-sampling).
**Example main.rb - Menonaktifkan konteks pengecualian hilang**
```
require 'aws-xray-sdk'
config = {
context_missing: 'LOG_ERROR'
}
XRay.recorder.configure(config)
```
## Konfigurasi pencatat dengan rail
Jika Anda menggunakan kerangka kerja Rails, Anda dapat mengonfigurasi opsi pada pencatat global dalam file Ruby di bawah `app_root/initializers`. SDK X-Ray mendukung kunci konfigurasi tambahan untuk digunakan dengan Rails.
+ `active_record` – Atur ke `true` untuk mencatat subsegmen untuk transaksi basis data Catatan Aktif.
Mengonfigurasi pengaturan yang tersedia di objek konfigurasi bernama `Rails.application.config.xray`.
**Example config/initializers/aws\$1xray.rb**
```
Rails.application.config.xray = {
name: 'my app',
patch: %I[net_http aws_sdk],
active_record: true
}
```
## Variabel-variabel lingkungan
Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for Ruby. SDK mendukung variabel berikut:
+ `AWS_XRAY_TRACING_NAME` – Atur nama layanan yang digunakan SDK untuk segmen. Menimpa nama layanan yang Anda tetapkan pada [strategi penamaan segmen](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming) filter servlet.
+ `AWS_XRAY_DAEMON_ADDRESS` – Atur host dan port pendengar daemon X-Ray. Secara default, SDK mengirimkan pelacakan data ke `127.0.0.1:2000`. Gunakan variabel ini jika Anda telah mengonfigurasi daemon untuk[mendengarkan pada port yang berbeda](xray-daemon-configuration.md) atau jika berjalan pada host yang berbeda.
+ `AWS_XRAY_CONTEXT_MISSING`— Setel `RUNTIME_ERROR` untuk melempar pengecualian saat kode instrumentasi Anda mencoba merekam data saat tidak ada segmen yang terbuka.
**Nilai Valid**
+ `RUNTIME_ERROR`— Lempar pengecualian runtime.
+ `LOG_ERROR`— Log kesalahan dan lanjutkan (default).
+ `IGNORE_ERROR`— Abaikan kesalahan dan lanjutkan.
Kesalahan yang berkaitan dengan segmen atau subsegmen yang hilang dapat terjadi ketika Anda mencoba untuk menggunakan klien yang diinstrumentasi dalam kode perusahaan rintisan yang berjalan ketika tidak ada permintaan terbuka, atau dalam kode yang memunculkan thread baru.
variabel lingkungan menimpa nilai yang ditetapkan dalam kode.
# Menelusuri permintaan yang masuk dengan X-Ray SDK for Ruby
**catatan**
Pemberitahuan SDK/Daemon Pemeliharaan X-Ray - Pada 25 Februari 2026, AWS SDKs/Daemon X-Ray akan memasuki mode pemeliharaan, di mana AWS akan membatasi rilis X-Ray SDK dan Daemon untuk mengatasi masalah keamanan saja. Untuk informasi selengkapnya tentang garis waktu dukungan, lihat[Garis waktu Dukungan X-Ray SDK dan Daemon](xray-sdk-daemon-timeline.md). Kami merekomendasikan untuk bermigrasi ke OpenTelemetry. Untuk informasi lebih lanjut tentang migrasi ke OpenTelemetry, lihat [Migrasi dari instrumentasi X-Ray ke instrumentasi](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Anda dapat menggunakan X-Ray SDK untuk melacak permintaan HTTP masuk yang disajikan aplikasi Anda pada instans EC2 di Amazon EC2,, AWS Elastic Beanstalk atau Amazon ECS.
Jika Anda menggunakan Rails, gunakan middleware Rails untuk instrumen permintaan HTTP masuk. Ketika Anda menambahkan perangkat tengah X-Ray ke aplikasi Anda, X-Ray SDK for Ruby membuat segmen untuk setiap permintaan sampel. Setiap segmen yang dibuat oleh instrumentasi tambahan menjadi subsegment dari segmen tingkat permintaan yang memberikan informasi tentang permintaan HTTP dan respons. Informasi ini mencakup waktu, metode, dan disposisi permintaan.
Setiap segmen memiliki nama yang mengidentifikasi aplikasi Anda dalam peta layanan. Segmen dapat diberi nama secara statis, atau Anda dapat mengonfigurasi SDK untuk nama itu secara dinamis berdasarkan header host dalam permintaan masuk. Penamaan dinamis memungkinkan Anda mengelompokkan pelacakan berdasarkan nama domain dalam permintaan, dan menerapkan nama default jika nama tersebut tidak cocok dengan pola yang diharapkan (misalnya, jika header host ditiru).
**Permintaan yang Diteruskan**
Jika penyeimbang beban atau perantara lainnya meneruskan permintaan ke aplikasi Anda, X-Ray akan mengambil IP klien dari header `X-Forwarded-For` dalam permintaan bukan dari sumber IP dalam paket IP. IP klien yang dicatat untuk permintaan yang diteruskan dapat ditiru, sehingga tidak dapat dipercaya.
Ketika permintaan diteruskan, SDK menetapkan bidang tambahan di segmen untuk menunjukkan ini. Jika segmen berisi bidang `x_forwarded_for` atur ke`true`, IP klien diambil dari header `X-Forwarded-For` dalam permintaan HTTP.
Perangkat tengah membuat segmen untuk setiap permintaan masuk dengan blok `http` yang berisi informasi berikut:
+ **Metode HTTP** – GET, POST, PUT, DELETE, dll
+ **Alamat klien** – Alamat IP klien yang mengirim permintaan.
+ **Kode respons** – Kode respons HTTP untuk permintaan yang selesai.
+ **Timing** – Waktu mulai (saat permintaan diterima) dan waktu akhir (saat respons dikirim).
+ **Agen pengguna** — `user-agent` dari permintaan.
+ **Panjang konten** — `content-length` dari respons.
## Menggunakan middleware rail
Untuk menggunakan middleware, perbarui gemfile Anda untuk menyertakan [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html).
**Example Gemfile - rail**
```
gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie']
```
Untuk menggunakan middleware, Anda juga harus [mengonfigurasi perekam](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails) dengan nama yang mewakili aplikasi di peta jejak.
**Example config/initializers/aws\$1xray.rb**
```
Rails.application.config.xray = {
name: 'my app'
}
```
## Mengonfigurasi kode secara manual
Jika Anda tidak menggunakan Rails, buat segmen secara manual. Anda dapat membuat segmen untuk setiap permintaan yang masuk, atau membuat segmen di sekitar klien HTTP atau AWS SDK yang ditambal untuk menyediakan konteks bagi perekam untuk menambahkan subsegmen.
```
# Start a segment
segment = XRay.recorder.begin_segment 'my_service'
# Start a subsegment
subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote'
# Add metadata or annotation here if necessary
my_annotations = {
k1: 'v1',
k2: 1024
}
segment.annotations.update my_annotations
# Add metadata to default namespace
subsegment.metadata[:k1] = 'v1'
# Set user for the segment (subsegment is not supported)
segment.user = 'my_name'
# End segment/subsegment
XRay.recorder.end_subsegment
XRay.recorder.end_segment
```
## Mengonfigurasi strategi penamaan segmen
AWS X-Ray menggunakan *nama layanan* untuk mengidentifikasi aplikasi Anda dan membedakannya dari aplikasi lain, database, eksternal APIs, dan AWS sumber daya yang digunakan aplikasi Anda. Saat SDK X-Ray membuat segmen untuk permintaan masuk, SDK akan mencatat nama layanan aplikasi Anda di [kolom nama](xray-api-segmentdocuments.md#api-segmentdocuments-fields).
SDK X-Ray dapat memberi nama segmen setelah nama host di header permintaan HTTP. Namun, header ini dapat ditiru, yang dapat mengakibatkan simpul tak terduga di peta layanan Anda. Untuk mencegah SDK dari penamaan segmen salah karena permintaan dengan header host palsu, Anda harus menentukan nama default untuk permintaan masuk.
Jika aplikasi Anda menyuguhkan permintaan untuk beberapa domain, Anda dapat mengonfigurasi SDK untuk menggunakan strategi penamaan dinamis untuk mencerminkan ini dalam nama segmen. Strategi penamaan dinamis mengizinkan SDK menggunakan nama host untuk permintaan yang sesuai dengan pola yang diharapkan, dan menerapkan nama default untuk permintaan yang tidak sesuai.
Misalnya, Anda boleh memiliki satu aplikasi yang melayani permintaan untuk tiga subdomain– `www.example.com`, `api.example.com`, dan `static.example.com`. Anda dapat menggunakan strategi penamaan dinamis dengan pola `*.example.com` untuk mengidentifikasi segmen untuk setiap subdomain dengan nama yang berbeda, mengakibatkan tiga simpul layanan pada peta layanan. Jika aplikasi Anda menerima permintaan dengan nama host yang tidak cocok dengan pola, Anda akan melihat simpul keempat pada peta layanan dengan nama fallback yang Anda tentukan.
Untuk menggunakan nama yang sama untuk semua segmen permintaan, tentukan nama aplikasi Anda ketika mengonfigurasi pencatat, seperti yang ditunjukkan di [bagian sebelumnya](#xray-sdk-ruby-middleware-rails).
Strategi penamaan dinamis menentukan pola yang harus sesuai dengan nama host, dan nama default untuk digunakan jika nama host dalam permintaan HTTP tidak cocok dengan pola. Untuk nama segmen dinamis, menentukan pola penamaan di hash config.
**Example main.rb – Penamaan dinamis**
```
config = {
naming_pattern: '*mydomain*',
name: 'my app',
}
XRay.recorder.configure(config)
```
Anda dapat menggunakan '\$1' dalam pola untuk mencocokkan string apa pun, atau '?' untuk mencocokkan setiap karakter tunggal.
**catatan**
Anda dapat menimpa nama layanan default yang Anda tentukan dalam kode dengan [variabel lingkungan](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars).`AWS_XRAY_TRACING_NAME`
# Pustaka patching ke instrumen panggilan hilir
**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
Untuk instrumen panggilan hilir, gunakan X-Ray SDK for Ruby untuk patch pustaka yang menggunakan aplikasi Anda. X-Ray SDK for Ruby dapat patch pustaka berikut.
**Pustaka Didukung**
+ `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)` – Instrumen klien HTTP.
+ `[aws-sdk](https://aws.amazon.com/sdk-for-ruby)`— AWS SDK untuk Ruby Klien instrumen.
Ketika Anda menggunakan pustaka yang dipatch, X-Ray SDK for Ruby membuat subsegmen untuk panggilan dan catatan informasi dari permintaan dan respons. Segmen harus tersedia untuk SDK untuk membuat subsegmen, baik dari SDK middleware atau panggilan ke `XRay.recorder.begin_segment`.
Untuk patch pustaka, tentukan di objek konfigurasi yang Anda lewati ke pencatat X-Ray.
**Example main.rb – Patch pustaka**
```
require 'aws-xray-sdk'
config = {
name: 'my app',
patch: %I[net_http aws_sdk]
}
XRay.recorder.configure(config)
```
# Menelusuri panggilan AWS SDK dengan X-Ray SDK for Ruby
**catatan**
Pemberitahuan SDK/Daemon Pemeliharaan X-Ray - Pada 25 Februari 2026, AWS SDKs/Daemon X-Ray akan memasuki mode pemeliharaan, di mana AWS akan membatasi rilis X-Ray SDK dan Daemon untuk mengatasi masalah keamanan saja. Untuk informasi selengkapnya tentang garis waktu dukungan, lihat[Garis waktu Dukungan X-Ray SDK dan Daemon](xray-sdk-daemon-timeline.md). Kami merekomendasikan untuk bermigrasi ke OpenTelemetry. Untuk informasi lebih lanjut tentang migrasi ke OpenTelemetry, lihat [Migrasi dari instrumentasi X-Ray ke instrumentasi](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
[Saat aplikasi Anda melakukan panggilan Layanan AWS untuk menyimpan data, menulis ke antrian, atau mengirim notifikasi, X-Ray SDK for Ruby melacak panggilan hilir di subsegmen.](xray-sdk-ruby-subsegments.md) Ditelusuri Layanan AWS dan sumber daya yang Anda akses dalam layanan tersebut (misalnya, bucket Amazon S3 atau antrean Amazon SQS), muncul sebagai node hilir pada peta jejak di konsol X-Ray.
X-Ray SDK for Ruby secara otomatis AWS menginstrumentasikan semua klien SDK [saat](xray-sdk-ruby-patching.md) Anda menambal pustaka. `aws-sdk` Anda tidak dapat instrumen klien individu.
Untuk semua layanan, Anda dapat melihat nama panggilan API di konsol X-Ray. Untuk subset layanan, X-Ray SDK menambahkan informasi ke segmen untuk memberikan lebih banyak perincian di peta layanan.
Sebagai contoh, ketika Anda melakukan panggilan dengan klien DynamoDB berinstrumen, SDK menambahkan nama tabel ke segmen untuk panggilan yang menargetkan tabel. Di konsol tersebut, setiap tabel muncul sebagai simpul terpisah di peta layanan, dengan simpul DynamoDB generik untuk panggilan yang tidak menargetkan tabel.
**Example Subsegmen untuk panggilan ke DynamoDB untuk menyimpan item**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Ketika Anda mengakses sumber daya bernama, panggilan ke layanan berikut membuat simpul tambahan di peta layanan. Panggilan yang tidak menargetkan sumber daya tertentu membuat simpul generik untuk layanan tersebut.
+ **Amazon DynamoDB** – Nama tabel
+ **Amazon Simple Storage Service** – Bucket dan nama kunci
+ **Amazon Simple Queue Service** – Nama antrean
# Menghasilkan subsegmen kustom dengan X-Ray SDK
**catatan**
Pemberitahuan SDK/Daemon Pemeliharaan X-Ray - Pada 25 Februari 2026, AWS SDKs/Daemon X-Ray akan memasuki mode pemeliharaan, di mana AWS akan membatasi rilis X-Ray SDK dan Daemon untuk mengatasi masalah keamanan saja. Untuk informasi selengkapnya tentang garis waktu dukungan, lihat[Garis waktu Dukungan X-Ray SDK dan Daemon](xray-sdk-daemon-timeline.md). Kami merekomendasikan untuk bermigrasi ke OpenTelemetry. Untuk informasi lebih lanjut tentang migrasi ke OpenTelemetry, lihat [Migrasi dari instrumentasi X-Ray ke instrumentasi](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Subsegmen memperluas [segmen](xray-concepts.md#xray-concepts-segments) pelacakan dengan detail tentang pekerjaan yang dilakukan untuk melayani permintaan. Setiap kali Anda melakukan panggilan dengan klien berinstrumen, X-Ray tersebut mencatat informasi yang dihasilkan dalam subsegmen. Anda dapat membuat subsegment tambahan untuk mengelompokkan subsegment lain, untuk mengukur performa bagian kode, atau untuk mencatat anotasi dan metadata.
Untuk mengelola subsegmen, gunakan metode `begin_subsegment` dan `end_subsegment`
```
subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote'
my_annotations = { id: 12345 }
subsegment.annotations.update my_annotations
XRay.recorder.end_subsegment
```
Untuk membuat subsegmen karena fungsi, membungkusnya dalam panggilan ke `XRay.recorder.capture`.
```
XRay.recorder.capture('name_for_subsegment') do |subsegment|
resp = myfunc() # myfunc is your function
subsegment.annotations.update k1: 'v1'
resp
end
```
Ketika Anda membuat subsegmen dalam segmen atau subsegmen lain, X-Ray SDK menghasilkan ID untuknya dan mencatat waktu mulai dan waktu akhir.
**Example Subsegmen dengan metadata**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
# Tambahkan anotasi dan metadata ke segmen dengan X-Ray SDK for Ruby
**catatan**
Pemberitahuan SDK/Daemon Pemeliharaan X-Ray - Pada 25 Februari 2026, AWS SDKs/Daemon X-Ray akan memasuki mode pemeliharaan, di mana AWS akan membatasi rilis X-Ray SDK dan Daemon untuk mengatasi masalah keamanan saja. Untuk informasi selengkapnya tentang garis waktu dukungan, lihat[Garis waktu Dukungan X-Ray SDK dan Daemon](xray-sdk-daemon-timeline.md). Kami merekomendasikan untuk bermigrasi ke OpenTelemetry. Untuk informasi lebih lanjut tentang migrasi ke OpenTelemetry, lihat [Migrasi dari instrumentasi X-Ray ke instrumentasi](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Anda dapat mencatat informasi tambahan tentang permintaan, lingkungan, atau aplikasi Anda dengan anotasi dan metadata. Anda dapat menambahkan anotasi dan metadata ke segmen yang dibuat oleh SDK X-Ray, atau subsegmen kustom yang Anda buat.
**Anotasi** adalah pasangan kunci-nilai dengan string, nomor, atau nilai-nilai Boolean. Anotasi diindekskan untuk digunakan dengan [Ekspresi filter](xray-console-filters.md). Gunakan anotasi untuk mencatat data yang ingin Anda gunakan untuk mengelompokkan pelacakan di konsol tersebut, atau saat memanggil API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
**Metadata** adalah pasangan kunci-nilai yang dapat memiliki nilai dari setiap tipe, termasuk objek dan daftar, tetapi tidak diindekskan untuk digunakan dengan ekspresi filter. Gunakan metadata untuk mencatat data tambahan yang ingin disimpan dalam pelacakan tetapi tidak perlu digunakan dengan pencarian.
Selain anotasi dan metadata, Anda juga dapat [mencatat string ID pengguna](#xray-sdk-ruby-segment-userid) pada segmen. Pengguna IDs direkam dalam bidang terpisah pada segmen dan diindeks untuk digunakan dengan pencarian.
**Topics**
+ [Mencatat pencatatan dengan X-Ray SDK for Ruby](#xray-sdk-ruby-segment-annotations)
+ [Mencatat metadata dengan X-Ray SDK for Ruby](#xray-sdk-ruby-segment-metadata)
+ [Merekam pengguna IDs dengan X-Ray SDK for Ruby](#xray-sdk-ruby-segment-userid)
## Mencatat pencatatan dengan X-Ray SDK for Ruby
Gunakan anotasi untuk mencatat informasi pada segmen atau subsegmen yang ingin diindeks untuk pencarian.
**Persyaratan Anotasi**
+ **Tombol** — Kunci untuk anotasi X-Ray dapat memiliki hingga 500 karakter alfanumerik. Anda tidak dapat menggunakan spasi atau simbol selain titik atau titik (.)
+ **Nilai** — Nilai untuk anotasi X-Ray dapat memiliki hingga 1.000 karakter Unicode.
+ Jumlah **Anotasi** — Anda dapat menggunakan hingga 50 anotasi per jejak.
**Untuk mencatat anotasi**
1. Dapatkan referensi ke segmen atau subsegmen saat ini dari `xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
atau
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_subsegment
```
1. Panggilan `update` dengan nilai hash.
```
my_annotations = { id: 12345 }
document.annotations.update my_annotations
```
Berikut ini adalah contoh yang menunjukkan cara memanggil `update` dengan kunci anotasi yang berisi titik.
```
my_annotations = { testkey.test: 12345 }
document.annotations.update my_annotations
```
SDK mencatat penjelasan sebagai pasangan nilai kunci dalam objek `annotations` di dokumen segmen. Memanggil `add_annotations` dua kali dengan tombol yang sama akan menimpa nilai yang tercatat sebelumnya pada segmen atau subsegmen yang sama.
Untuk menemukan penelusuran yang memiliki anotasi dengan nilai-nilai tertentu, gunakan kata kunci `annotation[key]` dalam [ekspresi filter](xray-console-filters.md).
## Mencatat metadata dengan X-Ray SDK for Ruby
Gunakan metadata untuk mencatat informasi pada segmen atau subsegmen yang tidak perlu diindeks untuk pencarian. Nilai metadata bisa string, angka, Boolean, atau objek yang dapat diserialkan ke dalam objek JSON atau array.
**Untuk mencatat metadata**
1. Dapatkan referensi ke segmen atau subsegmen saat ini dari `xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
atau
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_subsegment
```
1. Panggil `metadata` dengan kunci String, Boolean, Nomor, String, atau nilai Objek; dan namespace String.
```
my_metadata = {
my_namespace: {
key: 'value'
}
}
subsegment.metadata my_metadata
```
Memanggil `metadata` dua kali dengan tombol yang sama akan menimpa nilai yang tercatat sebelumnya pada segmen atau subsegmen yang sama.
## Merekam pengguna IDs dengan X-Ray SDK for Ruby
Rekam segmen pengguna IDs berdasarkan permintaan untuk mengidentifikasi pengguna yang mengirim permintaan.
**Untuk merekam pengguna IDs**
1. Dapatkan referensi ke segmen atau subsegmen saat ini dari `xray_recorder`.
```
require 'aws-xray-sdk'
...
document = XRay.recorder.current_segment
```
1. Mengatur bidang pengguna pada segmen untuk ID String dari pengguna yang mengirim permintaan.
```
segment.user = 'U12345'
```
Anda dapat menelepon di pengendali Anda untuk mencatat ID pengguna segera setelah aplikasi mulai memproses permintaan.
Untuk menemukan penelusuran pada ID pengguna, gunakan kata kunci `user` dalam [ekspresi filter](xray-console-filters.md).