Mengonfigurasi X-Ray SDK for Go

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.

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.

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.

contoh 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 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 sampling, SDK akan kembali ke aturan lokal default dari permintaan pertama yang diterima pada awal setiap detik, dan lima persen dari permintaan tambahan per host. Hal ini dapat terjadi jika host tidak memiliki izin untuk memanggil API pengambilan sampel, atau tidak dapat terhubung ke daemon X-Ray, yang bertindak sebagai proksi TCP untuk panggilan API yang dibuat 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.

contoh 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.

Pada AWS Lambda, 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.

contoh 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.

contoh 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 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
)

contoh 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 untukmendengarkan pada port yang berbeda 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. 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

StreamingStrategyObjek ini menentukan apakah untuk streaming segmen ketika RequiresStreamingmengembalikan 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.