Migrasi ke OpenTelemetry .NET - AWS X-Ray
Solusi instrumentasi otomatis kode nolSolusi instrumentasi manual dengan SDKMembuat data jejak secara manualMenelusuri permintaan yang masuk (instrumentasi inti ASP.NET dan ASP.NET)AWS Instrumentasi SDKInstrumentasi panggilan HTTP keluarDukungan instrumentasi untuk perpustakaan lainInstrumentasi Lambda

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Migrasi ke OpenTelemetry .NET

Saat menggunakan X-Ray Tracing di aplikasi.NET Anda, X-Ray .NET SDK dengan upaya manual digunakan untuk instrumentasi.

Bagian ini memberikan contoh kode di Solusi instrumentasi manual dengan SDK bagian untuk bermigrasi dari solusi instrumentasi manual X-Ray ke solusi Instrumentasi OpenTelemetry manual untuk.NET. Atau, Anda dapat bermigrasi dari instrumentasi manual X-Ray ke solusi instrumentasi OpenTelemetry otomatis ke instrumen aplikasi.NET tanpa harus memodifikasi kode sumber aplikasi di bagian ini. Solusi instrumentasi otomatis kode nol

Solusi instrumentasi otomatis kode nol

OpenTelemetry menyediakan solusi instrumentasi otomatis kode nol. Solusi ini melacak permintaan tanpa memerlukan perubahan pada kode aplikasi Anda.

OpenTelemetryopsi instrumentasi otomatis berbasis

  1. Menggunakan AWS Distro for OpenTelemetry (ADOT) Auto-instrumentasi untuk.NET — Untuk secara otomatis menginstrumentasikan aplikasi.NET, lihat Tracing and Metrics with the Distro for .NET Auto-Instrumentation. AWS OpenTelemetry

    (Opsional) Aktifkan Sinyal CloudWatch Aplikasi saat secara otomatis menginstrumentasi aplikasi Anda AWS dengan instrumentasi otomatis ADOT.NET ke:

    • Pantau kesehatan aplikasi saat ini

    • Melacak kinerja aplikasi jangka panjang terhadap tujuan bisnis

    • Dapatkan tampilan terpadu, aplikasi-sentris dari aplikasi, layanan, dan dependensi Anda

    • Monitor dan triase aplikasi kesehatan

    Untuk informasi selengkapnya, silakan lihat Sinyal Aplikasi.

  2. Menggunakan instrumentasi OpenTelemetry otomatis.Net zero-code — Untuk instrumen otomatis dengan.Net secara otomatis, lihat Tracing dan Metrik dengan Distro for OpenTelemetry .NET Auto-Instrumentation. AWS OpenTelemetry

Solusi instrumentasi manual dengan SDK

Tracing configuration with X-Ray SDK

Untuk aplikasi web.NET, X-Ray SDK dikonfigurasi di bagian AppSettings file. Web.config

Contoh Web.config


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

Untuk .NET Core, file bernama appsettings.json dengan kunci tingkat atas bernama XRay digunakan, dan kemudian objek konfigurasi dibangun untuk menginisialisasi perekam X-Ray.

Contoh untuk .NET appsettings.json


{
  "XRay": {
    "AWSXRayPlugins": "EC2Plugin"
  }
}

Contoh untuk.NET Core Program.cs - Konfigurasi perekam


using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder.InitializeInstance(configuration);
Tracing configuration with OpenTelemetry SDK

Tambahkan dependensi ini:


dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Contrib.Extensions.AWSXRay
dotnet add package OpenTelemetry.Sampler.AWS --prerelease
dotnet add package OpenTelemetry.Resources.AWS
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore

Untuk aplikasi.NET Anda, konfigurasikan OpenTelemetry SDK dengan menyiapkan Global TracerProvider. Contoh konfigurasi berikut juga memungkinkan instrumentasi untukASP.NET Core. Untuk instrumenASP.NET, lihatMenelusuri permintaan yang masuk (instrumentasi inti ASP.NET dan ASP.NET). Untuk digunakan OpenTelemetry dengan kerangka kerja lain, lihat Registry untuk lebih banyak pustaka untuk kerangka kerja yang didukung.

Disarankan agar Anda mengkonfigurasi komponen-komponen berikut:


using OpenTelemetry;
using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace;
using OpenTelemetry.Sampler.AWS;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;

var builder = WebApplication.CreateBuilder(args);

var serviceName = "MyServiceName";
var serviceVersion = "1.0.0";

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(serviceName: serviceName)
    .AddAWSEC2Detector();

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource
        .AddAWSEC2Detector()
        .AddService(
            serviceName: serviceName,
            serviceVersion: serviceVersion))
    .WithTracing(tracing => tracing
        .AddSource(serviceName)
        .AddAspNetCoreInstrumentation()
        .AddOtlpExporter()
        .SetSampler(AWSXRayRemoteSampler.Builder(resourceBuilder.Build())
            .SetEndpoint("http://localhost:2000")
            .Build()));

Sdk.SetDefaultTextMapPropagator(new AWSXRayPropagator()); // configure  X-Ray propagator

Untuk digunakan OpenTelemetry untuk aplikasi konsol, tambahkan OpenTelemetry konfigurasi berikut saat memulai program Anda.


using OpenTelemetry;
using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;

var serviceName = "MyServiceName";

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(serviceName: serviceName)
    .AddAWSEC2Detector();

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(serviceName)
    .ConfigureResource(resource =>
        resource
            .AddAWSEC2Detector()
            .AddService(
                serviceName: serviceName,
                serviceVersion: serviceVersion
            )
        )
    .AddOtlpExporter() // default address localhost:4317
    .SetSampler(new TraceIdRatioBasedSampler(1.00))
    .Build();

Sdk.SetDefaultTextMapPropagator(new AWSXRayPropagator()); // configure  X-Ray propagator

Membuat data jejak secara manual

With X-Ray SDK

Dengan X-Ray SDK, BeginSubsegment metode BeginSegment dan diperlukan untuk membuat segmen dan sub-segmen X-Ray secara manual.


using Amazon.XRay.Recorder.Core;

AWSXRayRecorder.Instance.BeginSegment("segment name"); // generates `TraceId` for you
try
{
    // Do something here
    // can create custom subsegments
    AWSXRayRecorder.Instance.BeginSubsegment("subsegment name");
    try
    {
        DoSometing();
    }
    catch (Exception e)
    {
        AWSXRayRecorder.Instance.AddException(e);
    }
    finally
    {
        AWSXRayRecorder.Instance.EndSubsegment();
    }
}
catch (Exception e)
{
    AWSXRayRecorder.Instance.AddException(e);
}
finally
{
    AWSXRayRecorder.Instance.EndSegment();
}
With OpenTelemetry SDK

Di .NET, Anda dapat menggunakan API aktivitas untuk membuat rentang kustom guna memantau kinerja aktivitas internal yang tidak ditangkap oleh pustaka instrumentasi. Perhatikan bahwa hanya rentang jenis Server yang diubah menjadi segmen X-Ray, semua rentang lainnya diubah menjadi sub-egment X-Ray.

Anda dapat membuat ActivitySource instance sebanyak yang diperlukan, tetapi disarankan untuk hanya memiliki satu untuk seluruh aplikasi/layanan.


using System.Diagnostics;

ActivitySource activitySource = new ActivitySource("ActivitySourceName", "ActivitySourceVersion");


...


using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server)) // this will be translated to a X-Ray Segment
{
    // Do something here

    using (var internalActivity = activitySource.StartActivity("ActivityName", ActivityKind.Internal)) // this will be translated to an X-Ray Subsegment
    {
        // Do something here
    }
}

Menambahkan anotasi dan metadata ke jejak dengan SDK OpenTelemetry

Anda juga dapat menambahkan pasangan nilai kunci kustom sebagai atribut ke rentang Anda dengan menggunakan SetTag metode pada aktivitas. Perhatikan bahwa secara default, semua atribut rentang akan diubah menjadi metadata dalam data mentah X-Ray. Untuk memastikan bahwa atribut diubah menjadi anotasi dan bukan metadata, Anda dapat menambahkan kunci atribut tersebut ke daftar atribut. aws.xray.annotations 


using (var activity = activitySource.StartActivity("ActivityName", ActivityKind.Server)) // this will be translated to a X-Ray Segment
{
    activity.SetTag("metadataKey", "metadataValue");
    activity.SetTag("annotationKey", "annotationValue");
    string[] annotationKeys = {"annotationKey"};
    activity.SetTag("aws.xray.annotations", annotationKeys);

    // Do something here

    using (var internalActivity = activitySource.StartActivity("ActivityName", ActivityKind.Internal)) // this will be translated to an X-Ray Subsegment
    {
        // Do something here
    }
}

Dengan instrumentasi OpenTelemetry otomatis

Jika Anda menggunakan solusi instrumentasi OpenTelemetry otomatis untuk .NET, dan jika Anda perlu melakukan instrumentasi manual dalam aplikasi Anda, misalnya, ke kode instrumen dalam aplikasi itu sendiri untuk bagian yang tidak tercakup oleh pustaka instrumentasi otomatis apa pun.

Karena hanya ada satu globalTracerProvider, instrumentasi manual tidak boleh membuat instance sendiri TracerProvider jika digunakan bersama bersama dengan instrumentasi otomatis. Saat TracerProvider digunakan, penelusuran manual khusus bekerja dengan cara yang sama saat menggunakan instrumentasi otomatis atau instrumentasi manual melalui SDK. OpenTelemetry

Menelusuri permintaan yang masuk (instrumentasi inti ASP.NET dan ASP.NET)

With X-Ray SDK

Untuk permintaan instrumen yang disajikan oleh aplikasi ASP.NET, lihat https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html informasi tentang cara menelepon RegisterXRay dalam Init metode global.asax file Anda.


AWSXRayASPNET.RegisterXRay(this, "MyApp");

Untuk permintaan instrumen yang disajikan oleh aplikasi inti ASP.NET Anda, UseXRay metode ini dipanggil sebelum middleware lain dalam Configure metode kelas Startup Anda.


app.UseXRay("MyApp");
With OpenTelemetry SDK

OpenTelemetry juga menyediakan pustaka instrumentasi untuk mengumpulkan jejak permintaan web yang masuk untuk ASP.NET dan ASP.NET core. Bagian berikut mencantumkan langkah-langkah yang diperlukan untuk menambahkan dan mengaktifkan instrumentasi pustaka ini untuk OpenTelemetry konfigurasi Anda, termasuk cara menambahkan instrumentasi inti ASP.NET atau ASP.NET saat membuat Penyedia Pelacak.

Untuk informasi tentang cara mengaktifkan OpenTelemetry .Instrumentation. AspNet, lihat Langkah-langkah untuk mengaktifkan OpenTelemetry .Instrumentation. AspNetdan untuk informasi tentang cara mengaktifkan OpenTelemetry .Instrumentation. AspNetCore, lihat Langkah-langkah untuk mengaktifkan OpenTelemetry .Instrumentation. AspNetCore.

AWS Instrumentasi SDK

With X-Ray SDK

Instal semua klien AWS SDK dengan meneleponRegisterXRayForAllServices().


using Amazon.XRay.Recorder.Handlers.AwsSdk;
AWSSDKHandler.RegisterXRayForAllServices(); //place this before any instantiation of AmazonServiceClient
AmazonDynamoDBClient client = new AmazonDynamoDBClient(RegionEndpoint.USWest2); // AmazonDynamoDBClient is automatically registered with X-Ray

Gunakan salah satu metode berikut untuk instrumentasi klien AWS layanan tertentu.


AWSSDKHandler.RegisterXRay<IAmazonDynamoDB>(); // Registers specific type of AmazonServiceClient : All instances of IAmazonDynamoDB created after this line are registered
AWSSDKHandler.RegisterXRayManifest(String path); // To configure custom AWS Service Manifest file. This is optional, if you have followed "Configuration" section
With OpenTelemetry SDK

Untuk contoh kode berikut, Anda memerlukan ketergantungan berikut:


dotnet add package OpenTelemetry.Instrumentation.AWS

Untuk AWS menginstrumentasikan SDK, perbarui konfigurasi OpenTelemetry SDK tempat Global TracerProvider disiapkan.


builder.Services.AddOpenTelemetry()
    ...
    .WithTracing(tracing => tracing
        .AddAWSInstrumentation()
        ...

Instrumentasi panggilan HTTP keluar

With X-Ray SDK

X-Ray .NET SDK melacak panggilan HTTP keluar melalui metode ekstensi GetResponseTraced() atau GetAsyncResponseTraced() saat menggunakanSystem.Net.HttpWebRequest, atau dengan menggunakan HttpClientXRayTracingHandler handler saat menggunakan. System.Net.Http.HttpClient

With OpenTelemetry SDK

Untuk contoh kode berikut, Anda memerlukan ketergantungan berikut:


dotnet add package OpenTelemetry.Instrumentation.Http

Untuk instrumen System.Net.Http.HttpClient danSystem.Net.HttpWebRequest, perbarui konfigurasi OpenTelemetry SDK tempat Global TracerProvider diatur.


builder.Services.AddOpenTelemetry()
    ...
    .WithTracing(tracing => tracing
        .AddHttpClientInstrumentation()
        ...

Dukungan instrumentasi untuk perpustakaan lain

Anda dapat mencari dan memfilter OpenTelemetry Registry untuk .NET Instrumentation Libraries untuk mengetahui apakah OpenTelemetry mendukung instrumentasi untuk Library Anda. Lihat Registry untuk mulai mencari.

Instrumentasi Lambda

With X-Ray SDK

Prosedur berikut diperlukan untuk menggunakan X-Ray SDK dengan Lambda:

  1. Aktifkan Penelusuran Aktif pada fungsi Lambda Anda

  2. Layanan Lambda membuat segmen yang mewakili pemanggilan handler Anda

  3. Membuat sub-segmen atau pustaka instrumen menggunakan X-Ray SDK

With OpenTelemetry-based solutions

Anda dapat secara otomatis menginstruksikan Lambda Anda dengan lapisan Lambda AWS yang dijual. Ada dua solusi:

  • (Disarankan) Sinyal CloudWatch Aplikasi lapisan lambda

  • Untuk kinerja yang lebih baik, Anda mungkin ingin mempertimbangkan untuk menggunakan OpenTelemetry Manual Instrumentation untuk menghasilkan OpenTelemetry jejak untuk fungsi Lambda Anda.

OpenTelemetry instrumentasi manual untuk AWS Lambda

Berikut ini adalah contoh kode fungsi Lambda (tanpa instrumentasi).


using System;
using System.Text;
using System.Threading.Tasks;
using Amazon.Lambda.Core;
using Amazon.S3;
using Amazon.S3.Model;

// Assembly attribute to enable Lambda function logging
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace ExampleLambda;

public class ListBucketsHandler
{
    private static readonly AmazonS3Client s3Client = new();

    // new Lambda function handler passed in
    public async Task<string> HandleRequest(object input, ILambdaContext context)
    {
        try
        {
            var DoListBucketsAsyncResponse = await DoListBucketsAsync();
            context.Logger.LogInformation($"Results: {DoListBucketsAsyncResponse.Buckets}");

            context.Logger.LogInformation($"Successfully called ListBucketsAsync");
            return "Success!";
        }
        catch (Exception ex)
        {
            context.Logger.LogError($"Failed to call ListBucketsAsync: {ex.Message}");
            throw;
        }
    }

    private async Task<ListBucketsResponse> DoListBucketsAsync()
    {
        try
        {
            var putRequest = new ListBucketsRequest
            {
            };

            var response = await s3Client.ListBucketsAsync(putRequest);
            return response;
        }
        catch (AmazonS3Exception ex)
        {
            throw new Exception($"Failed to call ListBucketsAsync: {ex.Message}", ex);
        }
    }
}

Untuk menginstruksikan handler Lambda Anda dan klien Amazon S3 secara manual, lakukan hal berikut.

  1. Instantiate a TracerProvider - TracerProvider Disarankan untuk dikonfigurasi denganXrayUdpSpanExporter, ParentBased Always On Sampler, dan Resource dengan service.name set ke nama fungsi Lambda.

  2. Instrumentasi klien Amazon S3 dengan instrumentasi OpenTemetry AWS SDK dengan menelepon AddAWSInstrumentation() untuk menambahkan AWS instrumentasi klien SDK TracerProvider

  3. Buat fungsi pembungkus dengan tanda tangan yang sama dengan fungsi Lambda asli. Panggil AWSLambdaWrapper.Trace() API dan lulusTracerProvider, fungsi Lambda asli, dan inputnya sebagai parameter. Atur fungsi pembungkus sebagai input handler Lambda.

Untuk contoh kode berikut, Anda memerlukan dependensi berikut:


dotnet add package OpenTelemetry.Instrumentation.AWSLambda
dotnet add package OpenTelemetry.Instrumentation.AWS
dotnet add package OpenTelemetry.Resources.AWS
dotnet add package AWS.Distro.OpenTelemetry.Exporter.Xray.Udp

Kode berikut menunjukkan fungsi Lambda setelah perubahan yang diperlukan. Anda dapat membuat rentang kustom tambahan untuk melengkapi rentang yang disediakan secara otomatis.


using Amazon.Lambda.Core;
using Amazon.S3;
using Amazon.S3.Model;
using OpenTelemetry;
using OpenTelemetry.Instrumentation.AWSLambda;
using OpenTelemetry.Trace;
using AWS.Distro.OpenTelemetry.Exporter.Xray.Udp;
using OpenTelemetry.Resources;

// Assembly attribute to enable Lambda function logging
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]

namespace ExampleLambda;

public class ListBucketsHandler
{
    private static readonly AmazonS3Client s3Client = new();

    TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddAWSLambdaConfigurations()
        .AddProcessor(
            new SimpleActivityExportProcessor(
                // AWS_LAMBDA_FUNCTION_NAME Environment Variable will be defined in AWS Lambda Environment
                new XrayUdpExporter(ResourceBuilder.CreateDefault().AddService(Environment.GetEnvironmentVariable("AWS_LAMBDA_FUNCTION_NAME")).Build())
            )
        )
        .AddAWSInstrumentation()
        .SetSampler(new ParentBasedSampler(new AlwaysOnSampler()))
        .Build();

    // new Lambda function handler passed in
    public async Task<string> HandleRequest(object input, ILambdaContext context)
    => await AWSLambdaWrapper.Trace(tracerProvider, OriginalHandleRequest, input, context);

    public async Task<string> OriginalHandleRequest(object input, ILambdaContext context)
    {
        try
        {
            var DoListBucketsAsyncResponse = await DoListBucketsAsync();
            context.Logger.LogInformation($"Results: {DoListBucketsAsyncResponse.Buckets}");

            context.Logger.LogInformation($"Successfully called ListBucketsAsync");
            return "Success!";
        }
        catch (Exception ex)
        {
            context.Logger.LogError($"Failed to call ListBucketsAsync: {ex.Message}");
            throw;
        }
    }

    private async Task<ListBucketsResponse> DoListBucketsAsync()
    {
        try
        {
            var putRequest = new ListBucketsRequest
            {
            };

            var response = await s3Client.ListBucketsAsync(putRequest);
            return response;
        }
        catch (AmazonS3Exception ex)
        {
            throw new Exception($"Failed to call ListBucketsAsync: {ex.Message}", ex);
        }
    }
}

Saat menjalankan Lambda ini, Anda akan melihat jejak berikut di Peta Jejak di CloudWatch konsol:

Lacak peta di CloudWatch konsol untuk.Net