Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Migrieren Sie zu .NET OpenTelemetry Wenn Sie X-Ray Tracing in Ihren .NET-Anwendungen verwenden, wird das X-Ray-.NET-SDK mit manuellem Aufwand für die Instrumentierung verwendet. Dieser Abschnitt enthält Codebeispiele im [Lösungen für die manuelle Instrumentierung mit dem SDK](#manual-instrumentation-dotnet) Abschnitt für die Migration von der manuellen X-Ray-Instrumentierungslösung zu OpenTelemetry manuellen Instrumentierungslösungen für.NET. Alternativ können Sie von manueller X-Ray-Instrumentierung zu OpenTelemetry automatischen Instrumentierungslösungen für Instrumenten-.NET-Anwendungen migrieren, ohne den Quellcode der Anwendung in [Automatische Instrumentierungslösungen ohne Code](#zero-code-instrumentation-dotnet) diesem Abschnitt ändern zu müssen. **Topics** + [Automatische Instrumentierungslösungen ohne Code](#zero-code-instrumentation-dotnet) + [Lösungen für die manuelle Instrumentierung mit dem SDK](#manual-instrumentation-dotnet) + [Manuelles Erstellen von Trace-Daten](#manual-trace-creation-dotnet) + [Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung)](#tracing-incoming-requests-dotnet) + [AWS SDK-Instrumentierung](#aws-sdk-instrumentation-dotnet) + [Instrumentieren von ausgehenden HTTP-Aufrufen](#http-instrumentation-dotnet) + [Instrumentierungsunterstützung für andere Bibliotheken](#other-libraries-dotnet) + [Lambda-Instrumentierung](#lambda-instrumentation) ## Automatische Instrumentierungslösungen ohne Code OpenTelemetry bietet automatische Instrumentierungslösungen ohne Code. Diese Lösungen verfolgen Anfragen, ohne dass Änderungen an Ihrem Anwendungscode erforderlich sind. **OpenTelemetrybasierte Optionen für automatische Instrumentierung** 1. Verwenden der AWS Distro for OpenTelemetry (ADOT) Auto-Instrumentation für .NET — Informationen zur automatischen Instrumentierung von.NET-Anwendungen finden Sie unter [Tracing and Metrics with the AWS Distro](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) for .NET Auto-Instrumentation. OpenTelemetry (Optional) Aktivieren Sie CloudWatch Application Signals, wenn Sie Ihre Anwendungen AWS mit der automatischen ADOT.NET-Instrumentierung automatisch instrumentieren, um: + Überwachen Sie den aktuellen Zustand der Anwendung + Verfolgen Sie die langfristige Anwendungsleistung anhand der Geschäftsziele + Verschaffen Sie sich einen einheitlichen, anwendungsorientierten Überblick über Ihre Anwendungen, Services und Abhängigkeiten + Überwachen und prüfen Sie den Zustand Ihrer Anwendungen Weitere Informationen finden Sie unter [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). 1. Verwenden der automatischen Null-Code-Instrumentierung OpenTelemetry von.Net — Informationen zur automatischen Instrumentierung OpenTelemetry mit.Net finden Sie unter [Tracing and Metrics with the AWS Distro](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) for .NET Auto-Instrumentation. OpenTelemetry ## Lösungen für die manuelle Instrumentierung mit dem SDK ------ #### [ Tracing configuration with X-Ray SDK ] Für .NET-Webanwendungen wird das X-Ray-SDK im Abschnitt AppSettings der `Web.config` Datei konfiguriert. Beispiel Web.config ``` ``` Für .NET Core wird eine Datei `appsettings.json` mit einem Schlüssel der obersten Ebene namens verwendet, und dann `XRay` wird ein Konfigurationsobjekt erstellt, um den X-Ray-Recorder zu initialisieren. Beispiel für.NET `appsettings.json` ``` { "XRay": { "AWSXRayPlugins": "EC2Plugin" } } ``` Beispiel für.NET Core Program.cs — Recorder-Konfiguration ``` using Amazon.XRay.Recorder.Core; ... AWSXRayRecorder.InitializeInstance(configuration); ``` ------ #### [ Tracing configuration with OpenTelemetry SDK ] **** Fügen Sie diese Abhängigkeiten hinzu: ``` 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 ``` Konfigurieren Sie das OpenTelemetry SDK für Ihre .NET-Anwendung, indem Sie Global einrichten TracerProvider. Die folgende Beispielkonfiguration ermöglicht auch die Instrumentierung für`ASP.NET Core`. Informationen zur `ASP.NET` Instrumentierung finden Sie unter[Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung)](#tracing-incoming-requests-dotnet). Informationen zur Verwendung OpenTelemetry mit anderen Frameworks finden Sie unter [Registry](https://opentelemetry.io/ecosystem/registry/) für weitere Bibliotheken für unterstützte Frameworks. Es wird empfohlen, die folgenden Komponenten zu konfigurieren: + `An OTLP Exporter`— Erforderlich für den Export von Traces zum CloudWatch Agent/Collector OpenTelemetry + Ein AWS X-Ray Propagator — Erforderlich für die Weitergabe des Trace-Kontextes an [AWS Dienste, die in X-Ray integriert sind](https://docs.aws.amazon.com/xray/latest/devguide/xray-services.html) + Ein AWS Röntgen-Remote-Sampler — Erforderlich, wenn Sie [Anfragen anhand von Röntgenprobenahmeregeln beproben](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) müssen + `Resource Detectors`(zum Beispiel Amazon EC2 Resource Detector) — Um Metadaten des Hosts zu erkennen, auf dem Ihre Anwendung ausgeführt wird ``` 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 ``` Um sie OpenTelemetry für eine Konsolen-App zu verwenden, fügen Sie beim Start Ihres Programms die folgende OpenTelemetry Konfiguration hinzu. ``` 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 ``` ------ ## Manuelles Erstellen von Trace-Daten ------ #### [ With X-Ray SDK ] Mit dem X-Ray-SDK waren die `BeginSubsegment` Methoden `BeginSegment` und erforderlich, um X-Ray-Segmente und -Untersegmente manuell zu erstellen. ``` 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 ] In.NET können Sie die Aktivitäts-API verwenden, um benutzerdefinierte Spans zu erstellen, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Subsegmente umgewandelt. Sie können so viele `ActivitySource` Instanzen wie nötig erstellen, es wird jedoch empfohlen, nur eine für eine gesamte Anwendung/einen Dienst zu verwenden. ``` 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 } } ``` **Hinzufügen von Anmerkungen und Metadaten zu Traces mit dem SDK OpenTelemetry ** Sie können Ihren Spans auch benutzerdefinierte Schlüssel-Wert-Paare als Attribute hinzufügen, indem Sie die `SetTag` Methode für eine Aktivität verwenden. Beachten Sie, dass standardmäßig alle Span-Attribute in X-Rohdaten in Metadaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, können Sie den Schlüssel dieses Attributs zur `aws.xray.annotations` Attributliste hinzufügen. ``` 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 } } ``` **Mit OpenTelemetry automatischer Instrumentierung** Wenn Sie eine OpenTelemetry automatische Instrumentierungslösung für .NET verwenden und in Ihrer Anwendung eine manuelle Instrumentierung durchführen müssen, um beispielsweise Code innerhalb der Anwendung selbst für Abschnitte zu instrumentieren, die von keiner Bibliothek für automatische Instrumentierung abgedeckt werden. Da es nur eine globale Instrumentierung geben kann`TracerProvider`, sollte die manuelle Instrumentierung nicht ihre eigene instanziieren, `TracerProvider` wenn sie zusammen mit der automatischen Instrumentierung verwendet wird. Wenn diese `TracerProvider` Option verwendet wird, funktioniert die benutzerdefinierte manuelle Ablaufverfolgung genauso, wenn automatische Instrumentierung oder manuelle Instrumentierung über das SDK verwendet wird. OpenTelemetry ------ ## Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung) ------ #### [ With X-Ray SDK ] Informationen zum Instrumentieren von Anfragen, die von der ASP.NET-Anwendung bedient werden, finden Sie unter[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), wie Sie die `Init` Methode Ihrer Datei aufrufen`RegisterXRay`. `global.asax` ``` AWSXRayASPNET.RegisterXRay(this, "MyApp"); ``` Um Anfragen zu instrumentieren, die von Ihrer ASP.NET-Kernanwendung bedient werden, wird die `UseXRay` Methode vor jeder anderen Middleware in der `Configure` Methode Ihrer Startup-Klasse aufgerufen. ``` app.UseXRay("MyApp"); ``` ------ #### [ With OpenTelemetry SDK ] OpenTelemetry stellt außerdem Instrumentierungsbibliotheken zur Erfassung von Traces für eingehende Webanfragen für ASP.NET und ASP.NET Core bereit. Im folgenden Abschnitt werden die Schritte aufgeführt, die erforderlich sind, um diese Bibliotheksinstrumentierungen für Ihre OpenTelemetry Konfiguration hinzuzufügen und zu aktivieren. Dazu gehört auch, wie Sie beim Erstellen des Tracer-Anbieters [ASP.NET](https://learn.microsoft.com/en-us/aspnet/overview) - oder [ASP.NET-Kerninstrumentierung](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-9.0) hinzufügen. Für Informationen zur Aktivierung von .Instrumentation. OpenTelemetry AspNet, siehe [Schritte zur Aktivierung von OpenTelemetry .Instrumentation. AspNet](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet#steps-to-enable-opentelemetryinstrumentationaspnet)und für Informationen zur Aktivierung von OpenTelemetry .Instrumentation. AspNetCore, siehe [Schritte zur Aktivierung von OpenTelemetry .Instrumentation. AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#steps-to-enable-opentelemetryinstrumentationaspnetcore). ------ ## AWS SDK-Instrumentierung ------ #### [ With X-Ray SDK ] Installieren Sie alle AWS SDK-Clients, indem Sie anrufen`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 ``` Verwenden Sie eine der folgenden Methoden für eine spezifische AWS Service-Client-Instrumentierung. ``` 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 ] Für das folgende Codebeispiel benötigen Sie die folgende Abhängigkeit: ``` dotnet add package OpenTelemetry.Instrumentation.AWS ``` Um das AWS SDK zu instrumentieren, aktualisieren Sie die OpenTelemetry SDK-Konfiguration, in der Global eingerichtet TracerProvider ist. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddAWSInstrumentation() ... ``` ------ ## Instrumentieren von ausgehenden HTTP-Aufrufen ------ #### [ With X-Ray SDK ] Das X-Ray.NET-SDK verfolgt ausgehende HTTP-Aufrufe über die Erweiterungsmethoden `GetResponseTraced()` oder `GetAsyncResponseTraced()` bei der Verwendung `System.Net.HttpWebRequest` oder mithilfe des `HttpClientXRayTracingHandler` Handlers bei der Verwendung`System.Net.Http.HttpClient`. ------ #### [ With OpenTelemetry SDK ] Für das folgende Codebeispiel benötigen Sie die folgende Abhängigkeit: ``` dotnet add package OpenTelemetry.Instrumentation.Http ``` Um die OpenTelemetry SDK-Konfiguration zu instrumentieren `System.Net.Http.HttpClient` und `System.Net.HttpWebRequest` zu aktualisieren, in der Global eingerichtet TracerProvider ist. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddHttpClientInstrumentation() ... ``` ------ ## Instrumentierungsunterstützung für andere Bibliotheken Sie können die OpenTelemetry Registry nach .NET-Instrumentierungsbibliotheken durchsuchen und filtern, um herauszufinden, ob OpenTelemetry die Instrumentierung für Ihre Bibliothek unterstützt wird. Suchen Sie in der [Registry](https://opentelemetry.io/ecosystem/registry/) nach, um mit der Suche zu beginnen. ## Lambda-Instrumentierung ------ #### [ With X-Ray SDK ] Das folgende Verfahren war erforderlich, um das X-Ray SDK mit Lambda zu verwenden: 1. Aktivieren Sie *Active Tracing für* Ihre Lambda-Funktion 1. Der Lambda-Dienst erstellt ein Segment, das den Aufruf Ihres Handlers darstellt. 1. Erstellen Sie Untersegmente oder Instrumentenbibliotheken mit dem X-Ray SDK ------ #### [ With OpenTelemetry-based solutions ] Sie können Ihr Lambda automatisch mit verkauften AWS Lambda-Layern instrumentieren. Es gibt zwei Lösungen: + (Empfohlen) [AWS Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) für OpenTelemetry + Um eine bessere Leistung zu erzielen, sollten Sie die Verwendung `OpenTelemetry Manual Instrumentation` zur Generierung von OpenTelemetry Traces für Ihre Lambda-Funktion in Betracht ziehen. ------ **OpenTelemetry manuelle Instrumentierung für AWS Lambda** Im Folgenden finden Sie ein Beispiel für einen Lambda-Funktionscode (ohne Instrumentierung). ``` 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); } } } ``` Gehen Sie wie folgt vor, um Ihren Lambda-Handler und den Amazon S3 S3-Client manuell zu instrumentieren. 1. Instanziieren Sie a TracerProvider — TracerProvider Es wird empfohlen, das mit einem`XrayUdpSpanExporter`, einem ParentBased Always On Sampler und a `Resource` zu konfigurieren, das auf den Namen der `service.name` Lambda-Funktion gesetzt ist. 1. Instrumentieren Sie den Amazon S3 S3-Client mit der OpenTemetry AWS SDK-Instrumentierung, indem Sie aufrufen`AddAWSInstrumentation()`, um die AWS SDK-Client-Instrumentierung hinzuzufügen `TracerProvider` 1. Erstellen Sie eine Wrapper-Funktion mit derselben Signatur wie die ursprüngliche Lambda-Funktion. Rufen Sie `AWSLambdaWrapper.Trace()` API auf und übergeben `TracerProvider` Sie die ursprüngliche Lambda-Funktion und ihre Eingaben als Parameter. Stellen Sie die Wrapper-Funktion als Lambda-Handler-Eingabe ein. Für das folgende Codebeispiel benötigen Sie die folgenden Abhängigkeiten: ``` 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 ``` Der folgende Code demonstriert die Lambda-Funktion nach den erforderlichen Änderungen. Sie können zusätzliche benutzerdefinierte Bereiche erstellen, um die automatisch bereitgestellten Bereiche zu ergänzen. ``` 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); } } } ``` Wenn Sie dieses Lambda aufrufen, sehen Sie den folgenden Trace in der Trace Map in der CloudWatch Konsole: ![\[Trace-Map in der CloudWatch Konsole für .Net\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/deprecation_dotnet.png)