Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Mengkonfigurasi X-Ray SDK for Ruby
**catatan**
X-Ray SDK/Daemon Pemberitahuan Pemeliharaan — Pada tanggal 25 Februari 2026, AWS X-Ray SDKs/Daemon 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 selengkapnya tentang migrasi ke OpenTelemetry, lihat [Migrasi dari X-Ray instrumentasi ke instrumentasi](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
X-Ray SDK for Ruby memiliki `XRay.recorder` kelas bernama yang menyediakan perekam global. Anda dapat mengonfigurasi pencatat global untuk menyesuaikan middleware 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.
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 tentukan di X-Ray konsol untuk menentukan permintaan mana yang akan direkam. Aturan default melacak permintaan pertama setiap detik, dan lima persen dari permintaan tambahan di semua layanan yang mengirim jejak ke X-Ray. [Buat aturan tambahan di X-Ray konsol](xray-console-sampling.md) untuk menyesuaikan jumlah data yang direkam 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 aturan pengambilan sampel, SDK akan kembali ke aturan lokal default dari permintaan pertama setiap detik, dan lima persen dari permintaan tambahan per host. Hal ini dapat terjadi jika host tidak memiliki izin untuk memanggil API sampling, atau tidak dapat terhubung ke X-Ray daemon, 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 untuk kasus di mana X-Ray pengambilan sampel tidak tersedia, 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 mendefinisikan aturan secara lokal adalah bahwa target tetap diterapkan oleh setiap instance perekam 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-aturan.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`— Atur host dan port pendengar X-Ray daemon.
+ `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`. X-Ray SDK 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\_xray.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 X-Ray daemon. 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.