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 Go **catatan** X-Ray SDK/Daemon Pemberitahuan Pemeliharaan — Pada 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 Anda dapat menentukan konfigurasi untuk X-Ray SDK for Go melalui variabel lingkungan, dengan `Configure` memanggil dengan objek, atau `Config` dengan mengasumsikan nilai default. Variabel lingkungan lebih diutamakan dibandingkan nilai `Config`, yang lebih diutamakan dibandingkan nilai default apa pun. **Topics** + [Plugin layanan](#xray-sdk-go-configuration-plugins) + [Aturan pengambilan sampel](#xray-sdk-go-configuration-sampling) + [Pencatatan log](#xray-sdk-go-configuration-logging) + [Variabel-variabel lingkungan](#xray-sdk-go-configuration-envvars) + [Menggunakan konfigurasi](#xray-sdk-go-configuration-configure) ## Plugin layanan Gunakan `plugins` untuk mencatat informasi tentang layanan yang meng-hosting aplikasi Anda. **Plugin** + Amazon EC2 — `EC2Plugin` menambahkan ID instans, Availability Zone, dan Grup CloudWatch Log. + Elastic Beanstalk – `ElasticBeanstalkPlugin` menambahkan nama lingkungan, label versi, dan ID deployment. + Amazon ECS – `ECSPlugin` menambahkan ID kontainer. ![Segmentasikan data sumber daya dengan Amazon EC2 dan plugin Elastic Beanstalk.](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-go.png) Untuk menggunakan plugin, impor salah satu paket berikut. ``` "github.com/aws/aws-xray-sdk-go/awsplugins/ec2" "github.com/aws/aws-xray-sdk-go/awsplugins/ecs" "github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk" ``` Setiap plugin memiliki panggilan fungsi `Init()` eksplisit yang memuat plugin. **Example ec2.Init()** ``` import ( "os" "github.com/aws/aws-xray-sdk-go/awsplugins/ec2" "github.com/aws/aws-xray-sdk-go/xray" ) func init() { // conditionally load plugin if os.Getenv("ENVIRONMENT") == "production" { ec2.Init() } xray.Configure(xray.Config{ ServiceVersion: "1.2.3", }) } ``` SDK juga menggunakan pengaturan plugin untuk mengatur bidang `origin` di 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. AWS Lambda Aktif, Anda tidak dapat mengubah laju pengambilan sampel. Jika fungsi Anda dipanggil oleh layanan yang diinstrumentasikan, panggilan yang menghasilkan permintaan yang sampelnya diambil oleh layanan yang akan dicatat oleh Lambda. Jika pelacakan aktif diaktifkan dan tidak ada header pelacakan, Lambda membuat keputusan pengambilan sampel. Untuk memberikan aturan pencadangan, arahkan ke file JSON pengambilan sampel lokal dengan menggunakan `NewCentralizedStrategyWithFilePath`. **Example main.go - Aturan pengambilan sampel lokal** ``` s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json xray.Configure(xray.Config{SamplingStrategy: s}) ``` Untuk hanya menggunakan aturan lokal, arahkan ke file JSON pengambilan sampel lokal dengan menggunakan `NewLocalizedStrategyFromFilePath`. **Example main.go – Nonaktifkan pengambilan sampel** ``` s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling json xray.Configure(xray.Config{SamplingStrategy: s}) ``` ## Pencatatan log **catatan** Bidang `xray.Config{}` `LogLevel` dan `LogFormat` tidak digunakan lagi mulai dari versi 1.0.0-rc.10. X-Ray menggunakan antarmuka berikut untuk logging. Pencatat default menulis ke `stdout` di `LogLevelInfo` dan di atasnya. ``` type Logger interface { Log(level LogLevel, msg fmt.Stringer) } const ( LogLevelDebug LogLevel = iota + 1 LogLevelInfo LogLevelWarn LogLevelError ) ``` **Example menulis ke `io.Writer`** ``` xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError)) ``` ## Variabel-variabel lingkungan Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for Go. SDK mendukung variabel berikut. + `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. + `AWS_XRAY_TRACING_NAME` – Tetapkan nama layanan yang digunakan SDK untuk segmen. + `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. Variabel lingkungan mengganti nilai yang setara yang diatur dalam kode. ## Menggunakan konfigurasi Anda juga dapat mengonfigurasi X-Ray SDK for Go menggunakan metode `Configure` ini. `Configure`mengambil satu argumen, sebuah `Config` objek, dengan bidang opsional berikut. DaemonAddr String ini menentukan host dan port pendengar X-Ray daemon. Jika tidak ditentukan, X-Ray menggunakan nilai variabel `AWS_XRAY_DAEMON_ADDRESS` lingkungan. Jika nilai tersebut tidak diatur, X-Ray menggunakan "127.0.0.1:2000". ServiceVersion String ini menentukan versi layanan. Jika tidak ditentukan, X-Ray menggunakan string kosong (“”). SamplingStrategy Objek `SamplingStrategy` ini menentukan panggilan aplikasi Anda yang dilacak. Jika tidak ditentukan, X-Ray gunakan a`LocalizedSamplingStrategy`, yang mengambil strategi seperti yang didefinisikan dalam`xray/resources/DefaultSamplingRules.json`. StreamingStrategy `StreamingStrategy`Objek ini menentukan apakah untuk streaming segmen ketika **RequiresStreaming**mengembalikan **true**. Jika tidak ditentukan, X-Ray gunakan a `DefaultStreamingStrategy` yang mengalirkan segmen sampel jika jumlah subsegmen lebih besar dari 20. ExceptionFormattingStrategy Objek `ExceptionFormattingStrategy` ini menentukan cara yang Anda inginkan dalam menangani berbagai pengecualian. Jika tidak ditentukan, X-Ray gunakan `DefaultExceptionFormattingStrategy` dengan tipe `XrayError` of`error`, pesan kesalahan, dan jejak tumpukan.