Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Migrer vers OpenTelemetry .NET Lorsque vous utilisez X-Ray Tracing dans vos applications .NET, le SDK X-Ray .NET associé à des efforts manuels est utilisé pour l'instrumentation. Cette section fournit des exemples de code dans la [Solutions d'instrumentation manuelle avec le SDK](#manual-instrumentation-dotnet) section relative à la migration de la solution d'instrumentation manuelle X-Ray vers des solutions OpenTelemetry d'instrumentation manuelle pour .NET. Vous pouvez également passer de l'instrumentation manuelle X-Ray aux solutions d'instrumentation OpenTelemetry automatique pour les applications .NET d'instrumentation sans avoir à modifier le code source de l'application dans la [Solutions d'instrumentation automatique à code zéro](#zero-code-instrumentation-dotnet) section. **Topics** + [Solutions d'instrumentation automatique à code zéro](#zero-code-instrumentation-dotnet) + [Solutions d'instrumentation manuelle avec le SDK](#manual-instrumentation-dotnet) + [Création manuelle de données de trace](#manual-trace-creation-dotnet) + [Suivi des demandes entrantes (ASP.NET et instrumentation de base ASP.NET)](#tracing-incoming-requests-dotnet) + [AWS Instrumentation du SDK](#aws-sdk-instrumentation-dotnet) + [Instrumentation des appels HTTP sortants](#http-instrumentation-dotnet) + [Support d'instrumentation pour d'autres bibliothèques](#other-libraries-dotnet) + [Instrumentation Lambda](#lambda-instrumentation) ## Solutions d'instrumentation automatique à code zéro OpenTelemetry fournit des solutions d'instrumentation automatique à code zéro. Ces solutions suivent les demandes sans qu'il soit nécessaire de modifier le code de votre application. **OpenTelemetryoptions d'instrumentation automatique basées sur des options** 1. Utilisation de la AWS distribution pour l'instrumentation automatique OpenTelemetry (ADOT) pour .NET — Pour instrumenter automatiquement les applications .NET, reportez-vous à la section [Suivi et mesures avec la AWS distribution pour l'](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr)instrumentation automatique .NET. OpenTelemetry (Facultatif) Activez les signaux d' CloudWatch application lorsque vous instrumentez automatiquement vos applications AWS avec l'instrumentation automatique ADOT .NET pour : + Surveiller l'état actuel des applications + Suivez les performances des applications à long terme par rapport aux objectifs commerciaux + Bénéficiez d'une vue unifiée et centrée sur les applications de vos applications, services et dépendances + Surveillez et triez l'état de santé des applications Pour plus d’informations, veuillez consulter la rubrique [Applications Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). 1. Utilisation de l'instrumentation automatique sans code OpenTelemetry .Net — Pour instrumenter automatiquement avec OpenTelemetry .Net, voir [Tracing and Metrics with the AWS Distro pour OpenTelemetry .NET](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) Auto-Instrumentation. ## Solutions d'instrumentation manuelle avec le SDK ------ #### [ Tracing configuration with X-Ray SDK ] Pour les applications Web .NET, le SDK X-Ray est configuré dans la section AppSettings du `Web.config` fichier. Exemple Web.config ``` ``` Pour .NET Core, un fichier nommé `appsettings.json` avec une clé de niveau supérieur `XRay` est utilisé, puis un objet de configuration est créé pour initialiser l'enregistreur X-Ray. Exemple pour .NET `appsettings.json` ``` { "XRay": { "AWSXRayPlugins": "EC2Plugin" } } ``` Exemple pour .NET Core Program.cs — Configuration de l'enregistreur ``` using Amazon.XRay.Recorder.Core; ... AWSXRayRecorder.InitializeInstance(configuration); ``` ------ #### [ Tracing configuration with OpenTelemetry SDK ] **** Ajoutez les dépendances suivantes : ``` 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 ``` Pour votre application .NET, configurez le OpenTelemetry SDK en configurant le Global TracerProvider. L'exemple de configuration suivant active également l'instrumentation pour`ASP.NET Core`. Pour instrumenter`ASP.NET`, voir[Suivi des demandes entrantes (ASP.NET et instrumentation de base ASP.NET)](#tracing-incoming-requests-dotnet). Pour OpenTelemetry une utilisation avec d'autres frameworks, voir [Registry](https://opentelemetry.io/ecosystem/registry/) pour plus de bibliothèques pour les frameworks pris en charge. Il est recommandé de configurer les composants suivants : + `An OTLP Exporter`— Nécessaire pour exporter les traces vers l' CloudWatch OpenTelemetry agent/le collecteur + Un propagateur de AWS rayons X : nécessaire pour propager le contexte de trace aux [AWS services intégrés à](https://docs.aws.amazon.com/xray/latest/devguide/xray-services.html) X-Ray + Un échantillonneur à distance AWS X-Ray : obligatoire si vous devez prélever des [échantillons à l'aide des règles d'échantillonnage X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) + `Resource Detectors`(par exemple, Amazon EC2 Resource Detector) : pour détecter les métadonnées de l'hôte exécutant votre application ``` 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 ``` OpenTelemetry Pour l'utiliser pour une application console, ajoutez la OpenTelemetry configuration suivante au démarrage de votre programme. ``` 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 ``` ------ ## Création manuelle de données de trace ------ #### [ With X-Ray SDK ] Avec le SDK X-Ray, les `BeginSubsegment` méthodes `BeginSegment` et étaient nécessaires pour créer manuellement des segments et des sous-segments X-Ray. ``` 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 ] Dans .NET, vous pouvez utiliser l'API d'activité pour créer des intervalles personnalisés afin de surveiller les performances des activités internes qui ne sont pas capturées par les bibliothèques d'instrumentation. Notez que seules les plages de type Server sont converties en segments X-Ray, toutes les autres plages sont converties en sous-segments de X-Ray. Vous pouvez créer autant d'`ActivitySource`instances que nécessaire, mais il est recommandé de n'en avoir qu'une pour l'ensemble d'une application/d' un service. ``` 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 } } ``` **Ajouter des annotations et des métadonnées aux traces avec OpenTelemetry le SDK** Vous pouvez également ajouter des paires clé-valeur personnalisées en tant qu'attributs à vos spans en utilisant la `SetTag` méthode appliquée à une activité. Notez que par défaut, tous les attributs de span seront convertis en métadonnées dans les données brutes de X-Ray. Pour garantir qu'un attribut est converti en annotation et non en métadonnées, vous pouvez ajouter la clé de cet attribut à la liste des `aws.xray.annotations` attributs. ``` 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 } } ``` **Avec instrumentation OpenTelemetry automatique** Si vous utilisez une solution d'instrumentation OpenTelemetry automatique pour .NET et si vous devez effectuer une instrumentation manuelle dans votre application, par exemple, pour coder des instruments dans l'application elle-même pour les sections qui ne sont couvertes par aucune bibliothèque d'instrumentation automatique. Comme il ne peut y avoir qu'une seule instrumentation globale`TracerProvider`, l'instrumentation manuelle ne doit pas instancier la sienne `TracerProvider` si elle est utilisée conjointement avec l'instrumentation automatique. Lorsqu'il `TracerProvider` est utilisé, le traçage manuel personnalisé fonctionne de la même manière lors de l'utilisation d'une instrumentation automatique ou manuelle via le OpenTelemetry SDK. ------ ## Suivi des demandes entrantes (ASP.NET et instrumentation de base ASP.NET) ------ #### [ With X-Ray SDK ] Pour instrumenter les requêtes traitées par l'application ASP.NET, reportez-vous à la section [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) pour savoir comment appeler `RegisterXRay` la `Init` méthode de votre `global.asax` fichier. ``` AWSXRayASPNET.RegisterXRay(this, "MyApp"); ``` Pour instrumenter les requêtes traitées par votre application principale ASP.NET, la `UseXRay` méthode est appelée avant tout autre intergiciel dans la `Configure` méthode de votre classe Startup. ``` app.UseXRay("MyApp"); ``` ------ #### [ With OpenTelemetry SDK ] OpenTelemetry fournit également des bibliothèques d'instrumentation pour collecter des traces pour les requêtes Web entrantes pour ASP.NET et ASP.NET core. [La section suivante répertorie les étapes nécessaires pour ajouter et activer ces instrumentations de bibliothèque pour votre OpenTelemetry configuration, notamment comment ajouter une instrumentation principale [ASP.NET ou ASP.NET](https://learn.microsoft.com/en-us/aspnet/overview) lors de la création du fournisseur de traceurs.](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-9.0) Pour plus d'informations sur la façon d'activer OpenTelemetry .Instrumentation. AspNet, voir [Étapes pour activer OpenTelemetry .Instrumentation. AspNet](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet#steps-to-enable-opentelemetryinstrumentationaspnet)et pour obtenir des informations sur la façon d'activer OpenTelemetry .Instrumentation. AspNetCore, voir [Étapes pour activer OpenTelemetry .Instrumentation. AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#steps-to-enable-opentelemetryinstrumentationaspnetcore). ------ ## AWS Instrumentation du SDK ------ #### [ With X-Ray SDK ] Installez tous les clients du AWS SDK en appelant`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 ``` Utilisez l'une des méthodes suivantes pour l'instrumentation spécifique du client de AWS service. ``` 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 ] Pour l'exemple de code suivant, vous aurez besoin de la dépendance suivante : ``` dotnet add package OpenTelemetry.Instrumentation.AWS ``` Pour instrumenter le AWS SDK, mettez à jour la configuration du OpenTelemetry SDK dans laquelle le Global TracerProvider est configuré. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddAWSInstrumentation() ... ``` ------ ## Instrumentation des appels HTTP sortants ------ #### [ With X-Ray SDK ] Le SDK .NET X-Ray trace les appels HTTP sortants via les méthodes d'extension `GetResponseTraced()` ou `GetAsyncResponseTraced()` lors de l'utilisation`System.Net.HttpWebRequest`, ou en utilisant le `HttpClientXRayTracingHandler` gestionnaire lors de l'utilisation. `System.Net.Http.HttpClient` ------ #### [ With OpenTelemetry SDK ] Pour l'exemple de code suivant, vous aurez besoin de la dépendance suivante : ``` dotnet add package OpenTelemetry.Instrumentation.Http ``` Pour instrumenter `System.Net.Http.HttpClient` et `System.Net.HttpWebRequest` mettre à jour la configuration du OpenTelemetry SDK où le Global TracerProvider est configuré. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddHttpClientInstrumentation() ... ``` ------ ## Support d'instrumentation pour d'autres bibliothèques Vous pouvez rechercher et filtrer les bibliothèques d'instrumentation .NET OpenTelemetry dans le registre afin de déterminer si votre bibliothèque OpenTelemetry prend en charge l'instrumentation. Consultez le [registre](https://opentelemetry.io/ecosystem/registry/) pour commencer la recherche. ## Instrumentation Lambda ------ #### [ With X-Ray SDK ] La procédure suivante était requise pour utiliser le SDK X-Ray avec Lambda : 1. Activez le *suivi actif* sur votre fonction Lambda 1. Le service Lambda crée un segment qui représente l'invocation de votre gestionnaire 1. Créez des sous-segments ou des bibliothèques d'instruments à l'aide du SDK X-Ray ------ #### [ With OpenTelemetry-based solutions ] Vous pouvez automatiquement instrumenter votre Lambda avec des couches AWS Lambda vendues. Il existe deux solutions : + Couche [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) (recommandée) pour OpenTelemetry + Pour de meilleures performances, vous pouvez envisager de générer des OpenTelemetry traces pour votre fonction Lambda. `OpenTelemetry Manual Instrumentation` ------ **OpenTelemetry instrumentation manuelle pour AWS Lambda** Voici un exemple de code de fonction Lambda (sans instrumentation). ``` 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); } } } ``` Pour instrumenter manuellement votre gestionnaire Lambda et le client Amazon S3, procédez comme suit. 1. Instancier a TracerProvider — Il TracerProvider est recommandé de le configurer avec un`XrayUdpSpanExporter`, un échantillonneur ParentBased Always On et un `Resource` with `service.name` définis sur le nom de la fonction Lambda. 1. Instrumenter le client Amazon S3 avec l'instrumentation du OpenTemetry AWS SDK en appelant `AddAWSInstrumentation()` pour ajouter l'instrumentation du client du AWS SDK à `TracerProvider` 1. Créez une fonction wrapper avec la même signature que la fonction Lambda d'origine. Appelez `AWSLambdaWrapper.Trace()` l'API et transmettez `TracerProvider` la fonction Lambda d'origine et ses entrées en tant que paramètres. Définissez la fonction wrapper comme entrée du gestionnaire Lambda. Pour l'exemple de code suivant, vous aurez besoin des dépendances suivantes : ``` 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 ``` Le code suivant illustre la fonction Lambda après les modifications requises. Vous pouvez créer des travées personnalisées supplémentaires pour compléter les travées fournies automatiquement. ``` 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); } } } ``` Lorsque vous invoquez cette Lambda, vous verrez la trace suivante dans la carte de suivi de la console : CloudWatch ![\[Tracer la carte dans CloudWatch la console pour .Net\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/deprecation_dotnet.png)