Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Mengonfigurasi X-Ray SDK for Go **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 menentukan konfigurasi untuk X-Ray SDK for Go through 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) + [Logging](#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. ![\[Segment - Scorekeep details showing Elastic Beanstalk, EC2, and Xray configuration information.\]](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 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. 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}) ``` ## Logging **catatan** Bidang `xray.Config{}` `LogLevel` dan `LogFormat` tidak digunakan lagi mulai dari versi 1.0.0-rc.10. X-Ray menggunakan antarmuka berikut untuk pencatatan. 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 tulis 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 listener 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 dijalankan pada host yang berbeda. + `AWS_XRAY_CONTEXT_MISSING` – Atur nilai untuk menentukan cara SDK menangani kesalahan konteks yang hilang. Kesalahan yang terkait dengan segmen atau subsegmen yang hilang dapat terjadi saat Anda mencoba menggunakan klien yang diinstrumentasikan dalam kode startup saat tidak ada permintaan yang terbuka, atau dalam kode yang memunculkan utas baru. + `RUNTIME_ERROR` – Secara default, SDK diatur untuk mengeluarkan pengecualian waktu aktif. + `LOG_ERROR` – Atur untuk mencatat kesalahan dan melanjutkan. Variabel lingkungan mengganti nilai yang setara yang diatur dalam kode. ## Menggunakan konfigurasi Anda juga dapat mengonfigurasi X-Ray SDK for Go menggunakan metode `Configure`. `Configure` mengambil satu argumen, sebuah objek `Config`, dengan bidang opsional berikut. DaemonAddr String ini menentukan host dan port dari listener daemon X-Ray. Jika tidak ditentukan, X-Ray menggunakan nilai variabel lingkungan `AWS_XRAY_DAEMON_ADDRESS`. 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 menggunakan `LocalizedSamplingStrategy`, yang mengambil strategi seperti yang ditentukan dalam `xray/resources/DefaultSamplingRules.json`. StreamingStrategy `StreamingStrategy`Objek ini menentukan apakah untuk streaming segmen ketika **RequiresStreaming**mengembalikan **true**. Jika tidak ditentukan, X-Ray menggunakan `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 menggunakan `DefaultExceptionFormattingStrategy` dengan `XrayError` dari tipe `error`, pesan kesalahan, dan pelacakan tumpukan.