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](#manual-instrumentation-dotnet) 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. [Solusi instrumentasi otomatis kode nol](#zero-code-instrumentation-dotnet) **Topics** + [Solusi instrumentasi otomatis kode nol](#zero-code-instrumentation-dotnet) + [Solusi instrumentasi manual dengan SDK](#manual-instrumentation-dotnet) + [Membuat data jejak secara manual](#manual-trace-creation-dotnet) + [Menelusuri permintaan yang masuk (instrumentasi inti ASP.NET dan ASP.NET)](#tracing-incoming-requests-dotnet) + [AWS Instrumentasi SDK](#aws-sdk-instrumentation-dotnet) + [Instrumentasi panggilan HTTP keluar](#http-instrumentation-dotnet) + [Dukungan instrumentasi untuk perpustakaan lain](#other-libraries-dotnet) + [Instrumentasi Lambda](#lambda-instrumentation) ## 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](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). 1. Menggunakan instrumentasi OpenTelemetry otomatis.Net zero-code — Untuk instrumen otomatis dengan.Net secara otomatis, lihat [Tracing dan Metrik dengan](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) 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 ``` ``` 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 untuk`ASP.NET Core`. Untuk instrumen`ASP.NET`, lihat[Menelusuri permintaan yang masuk (instrumentasi inti ASP.NET dan ASP.NET)](#tracing-incoming-requests-dotnet). Untuk digunakan OpenTelemetry dengan kerangka kerja lain, lihat [Registry](https://opentelemetry.io/ecosystem/registry/) untuk lebih banyak pustaka untuk kerangka kerja yang didukung. Disarankan agar Anda mengkonfigurasi komponen-komponen berikut: + `An OTLP Exporter`- Diperlukan untuk mengekspor jejak ke CloudWatch OpenTelemetry Agen/Kolektor + Propagator AWS X-Ray — Diperlukan untuk menyebarkan Konteks Jejak ke [AWS Layanan yang terintegrasi dengan X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services.html) + Sampler Jarak Jauh AWS X-Ray - Diperlukan jika Anda perlu [mengambil sampel permintaan menggunakan aturan pengambilan sampel X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) + `Resource Detectors`(misalnya, Amazon EC2 Resource Detector) - Untuk mendeteksi metadata host yang menjalankan aplikasi Anda ``` 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 global`TracerProvider`, 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](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](https://learn.microsoft.com/en-us/aspnet/overview) atau [ASP.NET](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-9.0) saat membuat Penyedia Pelacak. Untuk informasi tentang cara mengaktifkan OpenTelemetry .Instrumentation. AspNet, lihat [Langkah-langkah untuk mengaktifkan OpenTelemetry .Instrumentation. AspNet](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet#steps-to-enable-opentelemetryinstrumentationaspnet)dan untuk informasi tentang cara mengaktifkan OpenTelemetry .Instrumentation. AspNetCore, lihat [Langkah-langkah untuk mengaktifkan OpenTelemetry .Instrumentation. AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#steps-to-enable-opentelemetryinstrumentationaspnetcore). ------ ## AWS Instrumentasi SDK ------ #### [ With X-Ray SDK ] Instal semua klien AWS SDK dengan menelepon`RegisterXRayForAllServices()`. ``` 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(); // 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 menggunakan`System.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` dan`System.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](https://opentelemetry.io/ecosystem/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 1. Layanan Lambda membuat segmen yang mewakili pemanggilan handler Anda 1. 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) Lapisan [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) untuk OpenTelemetry + 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 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 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 dengan`XrayUdpSpanExporter`, ParentBased Always On Sampler, dan `Resource` dengan `service.name` set ke nama fungsi Lambda. 1. Instrumentasi klien Amazon S3 dengan instrumentasi OpenTemetry AWS SDK dengan menelepon `AddAWSInstrumentation()` untuk menambahkan AWS instrumentasi klien SDK `TracerProvider` 1. Buat fungsi pembungkus dengan tanda tangan yang sama dengan fungsi Lambda asli. Panggil `AWSLambdaWrapper.Trace()` API dan lulus`TracerProvider`, 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 HandleRequest(object input, ILambdaContext context) => await AWSLambdaWrapper.Trace(tracerProvider, OriginalHandleRequest, input, context); public async Task 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 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\]](http://docs.aws.amazon.com/id_id/xray/latest/devguide/images/deprecation_dotnet.png)