Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Migre a.NET OpenTelemetry Al utilizar el rastreo de X-Ray en las aplicaciones .NET, se utiliza X-Ray .NET SDK con esfuerzos manuales para la instrumentación. Esta sección proporciona ejemplos de código en la [Soluciones de instrumentación manual con el SDK](#manual-instrumentation-dotnet) sección para migrar de la solución de instrumentación manual de X-Ray a las soluciones de instrumentación OpenTelemetry manual para.NET. Como alternativa, puede migrar de la instrumentación manual de X-Ray a las soluciones de instrumentación OpenTelemetry automática y a las aplicaciones .NET de los instrumentos sin tener que modificar el código fuente de la aplicación en la [Soluciones de instrumentación automática sin código](#zero-code-instrumentation-dotnet) sección. **Topics** + [Soluciones de instrumentación automática sin código](#zero-code-instrumentation-dotnet) + [Soluciones de instrumentación manual con el SDK](#manual-instrumentation-dotnet) + [Creación manual de datos de rastros](#manual-trace-creation-dotnet) + [Rastreo de las solicitudes entrantes (ASP.NET e instrumentación básica de ASP.NET)](#tracing-incoming-requests-dotnet) + [AWS Instrumentación del SDK](#aws-sdk-instrumentation-dotnet) + [Instrumentación de llamadas a HTTP salientes](#http-instrumentation-dotnet) + [Compatibilidad de instrumentación para otras bibliotecas](#other-libraries-dotnet) + [Instrumentación de Lambda](#lambda-instrumentation) ## Soluciones de instrumentación automática sin código OpenTelemetry proporciona soluciones de autoinstrumentación sin código. Estas soluciones rastrean las solicitudes sin requerir cambios en el código de la aplicación. **OpenTelemetryopciones de instrumentación automática basadas en** 1. Uso de la AWS distribución para la instrumentación automática OpenTelemetry (ADOT) para .NET: para instrumentar automáticamente las aplicaciones.NET, consulte [Seguimiento y métricas con la distribución para la AWS instrumentación automática de.NET](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr). OpenTelemetry (Opcional) Habilite las señales de CloudWatch aplicación al instrumentar automáticamente sus aplicaciones AWS con la instrumentación automática de ADOT.NET para: + Supervisión del estado actual de la aplicación + Realización de un seguimiento del rendimiento de las aplicaciones a largo plazo en comparación con los objetivos empresariales + Obtención de una visión unificada y centrada en las aplicaciones de las aplicaciones, servicios y dependencias + Supervisión y clasificación del estado de las aplicaciones Para obtener más información, consulte [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). 1. Uso de la instrumentación automática de código cero de OpenTelemetry .Net: para instrumentar automáticamente con .Net, consulte [Tracing and Metrics with the Distro para ver la instrumentación automática de OpenTelemetry ](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) .NET. AWS OpenTelemetry ## Soluciones de instrumentación manual con el SDK ------ #### [ Tracing configuration with X-Ray SDK ] Para las aplicaciones web .NET, el SDK de X-Ray se configura en la sección appSettings del archivo `Web.config`. Web.config de ejemplo ``` ``` En el caso de .NET Core, se utiliza un archivo llamado `appsettings.json` con una clave de nivel superior llamada `XRay` y, a continuación, se crea un objeto de configuración o se inicializa la grabadora de X-Ray. Ejemplo para .NET `appsettings.json` ``` { "XRay": { "AWSXRayPlugins": "EC2Plugin" } } ``` Ejemplo para .NET Core Program.cs: configuración de grabadora ``` using Amazon.XRay.Recorder.Core; ... AWSXRayRecorder.InitializeInstance(configuration); ``` ------ #### [ Tracing configuration with OpenTelemetry SDK ] **** Agregue estas dependencias: ``` 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 ``` Para su aplicación.NET, configure el OpenTelemetry SDK configurando el Global TracerProvider. La configuración de ejemplo siguiente también habilita la instrumentación para `ASP.NET Core`. Para instrumentar `ASP.NET`, consulte [Rastreo de las solicitudes entrantes (ASP.NET e instrumentación básica de ASP.NET)](#tracing-incoming-requests-dotnet). Para usarlo OpenTelemetry con otros marcos, consulte [el Registro](https://opentelemetry.io/ecosystem/registry/) para ver más bibliotecas de marcos compatibles. Se recomienda que configure los siguientes componentes: + `An OTLP Exporter`— Necesario para exportar trazas al CloudWatch OpenTelemetry agente/recopilador + Un propagador de AWS rayos X: necesario para propagar el contexto de rastreo a [AWS los servicios integrados](https://docs.aws.amazon.com/xray/latest/devguide/xray-services.html) con X-Ray + Un muestreador remoto de AWS rayos X: necesario si necesita muestrear [solicitudes utilizando las reglas de muestreo de rayos X](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) + `Resource Detectors` (por ejemplo, detector de recursos de Amazon EC2): para detectar los metadatos del host que ejecuta la aplicación ``` 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 Para utilizarla como aplicación de consola, añada la siguiente OpenTelemetry configuración al iniciar el programa. ``` 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 ``` ------ ## Creación manual de datos de rastros ------ #### [ With X-Ray SDK ] Con el SDK de X-Ray, se necesitaban los métodos `BeginSegment` y `BeginSubsegment` para crear manualmente segmentos y subsegmentos de 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 ] En .NET, puede usar la API de actividad para crear intervalos personalizados para supervisar el rendimiento de las actividades internas que no se recopilan en las bibliotecas de instrumentación. Tenga en cuenta que solo los intervalos de tipo servidor se convierten en segmentos de X-Ray, todos los demás intervalos se convierten en subsegmentos de X-Ray. Puede crear tantas instancias de `ActivitySource` como necesite, pero es habitual tener un solo rastreador para toda la aplicación o servicio. ``` 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 } } ``` **Añadir anotaciones y metadatos a los seguimientos con OpenTelemetry el SDK** También puede agregar pares clave-valor personalizados como atributos en los intervalos con el método `SetTag` en una actividad. Tenga en cuenta que de forma predeterminada, todos los atributos de intervalo se convertirán en metadatos en los datos sin procesar de X-Ray. Para garantizar que un atributo se convierta en una anotación y no en metadatos, puede agregar esa clave del atributo a la lista del atributo `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 } } ``` **Con instrumentación OpenTelemetry automática** Si utiliza una solución de instrumentación OpenTelemetry automática para.NET y necesita realizar instrumentación manual en su aplicación, por ejemplo, instrumentar código dentro de la propia aplicación para secciones que no están incluidas en ninguna biblioteca de autoinstrumentación. Como solo puede haber un `TracerProvider` global, la instrumentación manual no debe crear una instancia propia de `TracerProvider` si se usa junto con la instrumentación automática. Cuando `TracerProvider` se usa, el rastreo manual personalizado funciona de la misma manera cuando se usa instrumentación automática o instrumentación manual a través del SDK. OpenTelemetry ------ ## Rastreo de las solicitudes entrantes (ASP.NET e instrumentación básica de ASP.NET) ------ #### [ With X-Ray SDK ] Para instrumentar las solicitudes atendidas por la aplicación de ASP.NET, consulte [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) para obtener información sobre cómo llamar a `RegisterXRay` en el método `Init` del archivo `global.asax`. ``` AWSXRayASPNET.RegisterXRay(this, "MyApp"); ``` Para instrumentar las solicitudes atendidas por la aplicación principal de ASP.NET, se llama al método `UseXRay` antes que a cualquier otro middleware del método `Configure` de la clase Startup. ``` app.UseXRay("MyApp"); ``` ------ #### [ With OpenTelemetry SDK ] OpenTelemetry también proporciona bibliotecas de instrumentación para recopilar los seguimientos de las solicitudes web entrantes de ASP.NET y ASP.NET core. En la siguiente sección se enumeran los pasos necesarios para agregar y habilitar estas instrumentaciones de biblioteca para su OpenTelemetry configuración, incluida la forma de agregar la instrumentación principal de [ASP.NET o ASP.NET](https://learn.microsoft.com/en-us/aspnet/overview) al crear el [proveedor Tracer](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-9.0). Para obtener información sobre cómo habilitar .Instrumentation. OpenTelemetry AspNet, consulte [Pasos para habilitar OpenTelemetry .Instrumentation. AspNet](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet#steps-to-enable-opentelemetryinstrumentationaspnet)y para obtener información sobre cómo habilitar OpenTelemetry .Instrumentation. AspNetCore, consulte los [pasos para habilitar OpenTelemetry .Instrumentation. AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#steps-to-enable-opentelemetryinstrumentationaspnetcore). ------ ## AWS Instrumentación del SDK ------ #### [ With X-Ray SDK ] Instala todos los clientes del AWS SDK llamando`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 ``` Utilice uno de los siguientes métodos para la instrumentación específica AWS del cliente de servicio. ``` 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 ] Para el ejemplo de código siguiente, necesitará la siguiente dependencia: ``` dotnet add package OpenTelemetry.Instrumentation.AWS ``` Para instrumentar el AWS SDK, actualice la configuración del OpenTelemetry SDK donde TracerProvider está configurado el Global. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddAWSInstrumentation() ... ``` ------ ## Instrumentación de llamadas a HTTP salientes ------ #### [ With X-Ray SDK ] El X-Ray .NET SDK rastrea las llamadas HTTP salientes a través de los métodos de extensión `GetResponseTraced()` o `GetAsyncResponseTraced()` cuando se usa `System.Net.HttpWebRequest`, o mediante el controlador `HttpClientXRayTracingHandler` cuando se usa `System.Net.Http.HttpClient`. ------ #### [ With OpenTelemetry SDK ] Para el ejemplo de código siguiente, necesitará la siguiente dependencia: ``` dotnet add package OpenTelemetry.Instrumentation.Http ``` Para `System.Net.Http.HttpClient` instrumentar y `System.Net.HttpWebRequest` actualizar la configuración del OpenTelemetry SDK donde TracerProvider está configurado el Global. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddHttpClientInstrumentation() ... ``` ------ ## Compatibilidad de instrumentación para otras bibliotecas Puede buscar y filtrar en el OpenTelemetry Registro las bibliotecas de instrumentación.NET para averiguar si son OpenTelemetry compatibles con la instrumentación de su biblioteca. Consulte [Registro](https://opentelemetry.io/ecosystem/registry/) para empezar a buscar. ## Instrumentación de Lambda ------ #### [ With X-Ray SDK ] Para utilizar SDK de X-Ray con Lambda se requirió el siguiente procedimiento: 1. Habilitación del *seguimiento activo* en la función de Lambda 1. El servicio de Lambda crea un segmento que representa la invocación del controlador 1. Creación de subsegmentos o bibliotecas de instrumentos con el SDK de X-Ray ------ #### [ With OpenTelemetry-based solutions ] Puede instrumentar automáticamente su Lambda con capas Lambda AWS vendidas. Hay dos soluciones: + Capa [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) (recomendada) para OpenTelemetry + Para obtener un mejor rendimiento, puede considerar utilizarla `OpenTelemetry Manual Instrumentation` para generar OpenTelemetry trazas para la función Lambda. ------ **OpenTelemetry instrumentación manual para Lambda AWS ** A continuación, se muestra el ejemplo del código de la función de Lambda (sin instrumentación). ``` 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); } } } ``` Para instrumentar manualmente el controlador de Lambda y el cliente de Amazon S3, haga lo siguiente. 1. Instanciar a TracerProvider : TracerProvider se recomienda configurar con un`XrayUdpSpanExporter`, un muestreador ParentBased Always On y un `Resource` con `service.name` establecido en el nombre de la función Lambda. 1. Instrumente el cliente Amazon S3 con la instrumentación del OpenTemetry AWS SDK llamando `AddAWSInstrumentation()` para añadir la instrumentación AWS del cliente del SDK a `TracerProvider` 1. Cree una función envolvente con la misma firma que la función de Lambda original. Llame a la API de `AWSLambdaWrapper.Trace()` y pase `TracerProvider`, la función de Lambda original y sus entradas como parámetros. Configure la función envolvente como entrada del controlador de Lambda. Para el ejemplo de código siguiente, necesitará las siguientes dependencias: ``` 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 ``` El código siguiente muestra la función de Lambda después de los cambios necesarios. Puede crear intervalos personalizados adicionales para complementar los intervalos que se proporcionan automáticamente. ``` 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); } } } ``` Al invocar esta Lambda, verá la siguiente traza en el mapa de trazas de la consola: CloudWatch ![\[Trace el mapa en la CloudWatch consola para .Net\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/deprecation_dotnet.png)