Mengonfigurasi X-Ray SDK for .NET

Anda dapat mengonfigurasi X-Ray SDK for .NET dengan plugin untuk menyertakan informasi tentang layanan tempat aplikasi Anda berjalan, mengubah perilaku pengambilan sampel default, atau menambahkan aturan pengambilan sampel yang berlaku untuk permintaan ke jalur tertentu.

Untuk aplikasi web .NET, tambahkan kunci ke bagian appSettings file Web.config Anda.

<configuration>
  <appSettings>
    <add key="AWSXRayPlugins" value="EC2Plugin"/>
    <add key="SamplingRuleManifest" value="sampling-rules.json"/>
  </appSettings>
</configuration>

Untuk .NET Core, buat file bernama appsettings.json dengan kunci tingkat atas bernama XRay.

{
  "XRay": {
    "AWSXRayPlugins": "EC2Plugin",
    "SamplingRuleManifest": "sampling-rules.json"
  }
}

Lalu, dalam kode aplikasi Anda, bangun objek konfigurasi dan gunakan untuk menginisialisasi pencatat X-Ray. Lakukan ini sebelum Anda menginisialisasi pencatat.

using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder.InitializeInstance(configuration);

Jika Anda menginstrumentasikan aplikasi web .NET Core, Anda juga dapat meneruskan objek konfigurasi ke metode UseXRay saat Anda mengonfigurasi pengendali pesan. Untuk fungsi Lambda, gunakan metode InitializeInstance seperti yang ditunjukkan di atas.

Untuk informasi selengkapnya tentang API konfigurasi .NET Core, lihat Konfigurasikan aplikasi ASP.NET Core di docs.microsoft.com.

Plugin

Gunakan plugin untuk menambahkan data tentang layanan yang menjadi meng-hosting aplikasi Anda.

Untuk menggunakan plugin, konfigurasikan klien X-Ray SDK for .NET dengan menambahkan pengaturan AWSXRayPlugins. Jika beberapa plugin berlaku untuk aplikasi Anda, tentukan semuanya dalam pengaturan yang sama, dipisahkan dengan koma.

<configuration>
  <appSettings>
    <add key="AWSXRayPlugins" value="EC2Plugin,ElasticBeanstalkPlugin"/>
  </appSettings>
</configuration>

{
  "XRay": {
    "AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin"
  }
}

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.

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.

{
  "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 mengonfigurasi aturan pencadangan, beri tahu X-Ray SDK for .NET agar memuat aturan pengambilan sampel dari file dengan pengaturan SamplingRuleManifest tersebut.

<configuration>
  <appSettings>
    <add key="SamplingRuleManifest" value="sampling-rules.json"/>
  </appSettings>
</configuration>

{
  "XRay": {
    "SamplingRuleManifest": "sampling-rules.json"
  }
}

Untuk hanya menggunakan aturan lokal, buat pencatat dengan LocalizedSamplingStrategy. Jika Anda memiliki aturan pencadangan yang dikonfigurasi, hapus konfigurasi tersebut.

var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("samplingrules.json")).Build();
AWSXRayRecorder.InitializeInstance(recorder: recorder);

var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("sampling-rules.json")).Build();
AWSXRayRecorder.InitializeInstance(configuration,recorder);

Pencatatan (NET)

X-Ray SDK for .NET menggunakan mekanisme pencatatan yang sama dengan AWS SDK for .NET. Jika Anda sudah mengonfigurasi aplikasi untuk mencatat AWS SDK for .NET output, konfigurasi yang sama berlaku untuk output dari X-Ray SDK for .NET.

Untuk mengonfigurasi pencatatan, tambahkan bagian konfigurasi bernama aws ke file App.config Anda atau file Web.config.

...
<configuration>
  <configSections>
    <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/>
  </configSections>
  <aws>
    <logging logTo="Log4Net"/>
  </aws>
</configuration>

Untuk informasi selengkapnya, lihat Mengonfigurasi Aplikasi AWS SDK for .NET Anda dalam Panduan Developer AWS SDK for .NET .

Pencatatan (.NET Core)

X-Ray SDK for .NET menggunakan opsi pencatatan yang sama dengan AWS SDK for .NET. Untuk mengonfigurasi pencatatan untuk aplikasi .NET Core, teruskan opsi pencatatan ke metode AWSXRayRecorder.RegisterLogger.

Misalnya, untuk menggunakan log4net, buat file konfigurasi yang menentukan logger, format output, dan lokasi file.

<?xml version="1.0" encoding="utf-8" ?>
<log4net>
  <appender name="FileAppender" type="log4net.Appender.FileAppender,log4net">
    <file value="c:\logs\sdk-log.txt" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %level %logger - %message%newline" />
    </layout>
  </appender>
  <logger name="Amazon">
    <level value="DEBUG" />
    <appender-ref ref="FileAppender" />
  </logger>
</log4net>

Lalu, buat logger dan terapkan konfigurasi di kode program Anda.

using log4net;
using Amazon.XRay.Recorder.Core;

class Program
{
  private static ILog log;
  static Program()
  {
    var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly());
    XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config"));
    log = LogManager.GetLogger(typeof(Program));
    AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net);
  }
  static void Main(string[] args)
  {
  ...
  }
}

Untuk informasi selengkapnya tentang mengonfigurasi log4net, lihat Konfigurasi di logging.apache.org.

Variabel-variabel lingkungan

Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for .NET. SDK mendukung variabel berikut.