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 .NET
<a name="xray-sdk-dotnet-configuration"></a>

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

**Example Web.config**  

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

**Example .NET appsettings.json**  

```
{
  "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](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs).

**Example .NET Core Program.cs – Konfigurasi pencatat**  

```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder.InitializeInstance(configuration);
```

Jika Anda menginstrumentasikan aplikasi web .NET Core, Anda juga dapat meneruskan objek konfigurasi ke metode `UseXRay` saat Anda [mengonfigurasi pengendali pesan](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs). 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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration) di docs.microsoft.com.

**Topics**
+ [Plugin](#xray-sdk-dotnet-configuration-plugins)
+ [Aturan pengambilan sampel](#xray-sdk-dotnet-configuration-sampling)
+ [Pencatatan (NET)](#xray-sdk-dotnet-configuration-logging)
+ [Pencatatan (.NET Core)](#xray-sdk-dotnet-configuration-corelogging)
+ [Variabel-variabel lingkungan](#xray-sdk-dotnet-configuration-envvars)

## Plugin
<a name="xray-sdk-dotnet-configuration-plugins"></a>

Gunakan plugin untuk menambahkan data tentang layanan yang menjadi 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, 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.

**Example Web.config - plugin**  

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

**Example .NET Core appsettings.json – Plugin**  

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

## Aturan pengambilan sampel
<a name="xray-sdk-dotnet-configuration-sampling"></a>

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

**Example .NET Web.config - aturan pengambilan sampel**  

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

**Example .NET Core appsettings.json – Aturan Pengambilan Sampel**  

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

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

**Example .NET global.asax – Aturan pengambilan sampel lokal**  

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

**Example .NET Core Program.cs – Aturan pengambilan sampel lokal**  

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

## Pencatatan (NET)
<a name="xray-sdk-dotnet-configuration-logging"></a>

X-Ray SDK for .NET menggunakan mekanisme pencatatan yang sama dengan [AWS SDK untuk .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging). Jika Anda sudah mengonfigurasi aplikasi untuk mencatat AWS SDK untuk .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`.

**Example Web.config - pencatatan**  

```
...
<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 untuk .NET Anda](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html) dalam *Panduan Developer AWS SDK untuk .NET *.

## Pencatatan (.NET Core)
<a name="xray-sdk-dotnet-configuration-corelogging"></a>

X-Ray SDK for .NET menggunakan opsi pencatatan yang sama dengan [AWS SDK untuk .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging). 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.

**Example .NET Core log4net.config**  

```
<?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.

**Example .NET Core Program.cs – Pencatatan**  

```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);

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](https://logging.apache.org/log4net/release/manual/configuration.html) di logging.apache.org.

## Variabel-variabel lingkungan
<a name="xray-sdk-dotnet-configuration-envvars"></a>

Anda dapat menggunakan variabel lingkungan untuk mengonfigurasi X-Ray SDK for .NET. SDK mendukung variabel berikut.
+ `AWS_XRAY_TRACING_NAME` – Menetapkan nama layanan yang digunakan SDK untuk segmen. Menimpa nama layanan yang Anda tetapkan pada [strategi penamaan segmen](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming) filter servlet.
+ `AWS_XRAY_DAEMON_ADDRESS` – Mengatur host dan port listener daemon X-Ray. Secara default, SDK menggunakan `127.0.0.1:2000` untuk data pelacakan (UDP) dan pengambilan sampel (TCP). Gunakan variabel ini jika Anda telah mengonfigurasi daemon untuk [mendengarkan di port berbeda](xray-daemon-configuration.md) atau jika berjalan pada host yang berbeda.

**Format**
  + **Port yang sama** – `{{address}}:{{port}}`
  + **Port yang berbeda** – `tcp:{{address}}:{{port}} udp:{{address}}:{{port}}`
+ `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 terkait dengan segmen atau subsegmen yang hilang dapat terjadi saat Anda mencoba menggunakan klien yang diinstrumentasikan dalam kode startup yang berjalan saat tidak ada permintaan yang dibuka, atau dalam kode yang memunculkan utas baru.