As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Migrar para o.NET OpenTelemetry Ao usar o rastreamento do X-Ray nas suas aplicações .NET, o SDK .NET do X-Ray com esforços manuais é usado para instrumentação. Esta seção fornece exemplos de código na [Soluções de instrumentação manual com o SDK](#manual-instrumentation-dotnet) seção para migrar da solução de instrumentação manual X-Ray para soluções de instrumentação OpenTelemetry manual para.NET. Como alternativa, você pode migrar da instrumentação manual X-Ray para soluções de instrumentação OpenTelemetry automática para instrumentar aplicativos.NET sem precisar modificar o código-fonte do aplicativo na seção. [Soluções de instrumentação automática de código zero](#zero-code-instrumentation-dotnet) **Topics** + [Soluções de instrumentação automática de código zero](#zero-code-instrumentation-dotnet) + [Soluções de instrumentação manual com o SDK](#manual-instrumentation-dotnet) + [Criar dados de rastreamento manualmente](#manual-trace-creation-dotnet) + [Rastrear solicitações recebidas (instrumentação do ASP.NET e do ASP.NET Core)](#tracing-incoming-requests-dotnet) + [AWS Instrumentação do SDK](#aws-sdk-instrumentation-dotnet) + [Instrumentar chamadas HTTP de saída](#http-instrumentation-dotnet) + [Suporte de instrumentação para outras bibliotecas](#other-libraries-dotnet) + [Instrumentação do Lambda](#lambda-instrumentation) ## Soluções de instrumentação automática de código zero OpenTelemetry fornece soluções de instrumentação automática de código zero. Essas soluções rastreiam solicitações sem exigir alterações no código da aplicação. **OpenTelemetryopções de instrumentação automática baseadas em** 1. Usando a AWS distro para instrumentação automática OpenTelemetry (ADOT) para.NET — Para instrumentar automaticamente aplicativos.NET, consulte [Rastreamento e métricas com](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) a distribuição para instrumentação automática.NET. AWS OpenTelemetry (Opcional) Ative o CloudWatch Application Signals ao instrumentar automaticamente seus aplicativos AWS com a instrumentação automática ADOT.NET para: + Monitorar a integridade atual da aplicação + Acompanhar o desempenho a longo prazo da aplicação em relação aos objetivos de negócios + Obter uma visualização unificada e centrada em aplicações das suas aplicações, serviços e dependências + Monitorar e fazer a triagem da integridade da aplicação Para obter mais informações, consulte [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). 1. Usando a instrumentação automática de código zero OpenTelemetry do.NET — Para instrumentar automaticamente com OpenTelemetry o.NET, consulte [Rastreamento e métricas com](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr) a distribuição para instrumentação automática do.NET. AWS OpenTelemetry ## Soluções de instrumentação manual com o SDK ------ #### [ Tracing configuration with X-Ray SDK ] Para aplicativos web .NET, o SDK do X-Ray é configurado na seção appSettings do arquivo `Web.config`. Exemplo de Web.config ``` ``` Para o .NET Core, um arquivo chamado `appsettings.json` com uma chave de nível superior chamada `XRay` é usado e, em seguida, um objeto de configuração é criado para inicializar o gravador do X-Ray. Exemplo de .NET `appsettings.json` ``` { "XRay": { "AWSXRayPlugins": "EC2Plugin" } } ``` Exemplo de .NET Core Program.cs: configuração do gravador ``` using Amazon.XRay.Recorder.Core; ... AWSXRayRecorder.InitializeInstance(configuration); ``` ------ #### [ Tracing configuration with OpenTelemetry SDK ] **** Adicione estas dependências: ``` 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 seu aplicativo.NET, configure o OpenTelemetry SDK configurando o Global TracerProvider. O exemplo de configuração a seguir também permite a instrumentação de `ASP.NET Core`. Para instrumentar `ASP.NET`, consulte [Rastrear solicitações recebidas (instrumentação do ASP.NET e do ASP.NET Core)](#tracing-incoming-requests-dotnet). Para usar OpenTelemetry com outras estruturas, consulte [Registro](https://opentelemetry.io/ecosystem/registry/) para obter mais bibliotecas de estruturas compatíveis. É recomendável configurar os seguintes componentes: + `An OTLP Exporter`— Necessário para exportar traços para o CloudWatch OpenTelemetry Agente/Coletor + Um propagador de AWS raio-X — necessário para propagar o contexto de rastreamento para [AWS serviços integrados](https://docs.aws.amazon.com/xray/latest/devguide/xray-services.html) ao X-Ray + Um amostrador remoto de AWS raio-X — necessário se você precisar coletar amostras de [solicitações usando as regras de amostragem de raio-X](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) + `Resource Detectors` (por exemplo, detector de recursos do Amazon EC2): para detectar metadados do host que executa sua aplicação ``` 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 usar em um aplicativo de console, adicione a seguinte OpenTelemetry configuração na inicialização do seu 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 ``` ------ ## Criar dados de rastreamento manualmente ------ #### [ With X-Ray SDK ] Com o SDK do X-Ray, os métodos `BeginSegment` e `BeginSubsegment` eram necessários para criar manualmente segmentos e subsegmentos do 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 ] Em .NET, use a API de atividades para criar extensões personalizadas para monitorar o desempenho de atividades internas que não são capturadas pelas bibliotecas de instrumentação. Somente extensões do tipo servidor são convertidas em segmentos do X-Ray. Todas as outras extensões são convertidas em subsegmentos do X-Ray. É possível criar quantas instâncias `ActivitySource` forem necessárias, mas é recomendável ter apenas uma para uma aplicação/serviço inteiro. ``` 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 } } ``` **Adicionar anotações e metadados aos rastreamentos com o SDK OpenTelemetry ** Também é possível adicionar pares de valor-chave personalizados como atributos às extensões usando o método `SetTag` em uma atividade. Por padrão, todos os atributos de extensão serão convertidos em metadados nos dados brutos do X-Ray. Para garantir que um atributo seja convertido em uma anotação, e não em metadados, adicione a chave desses atributos à lista do 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 } } ``` **Com instrumentação OpenTelemetry automática** Se você estiver usando uma solução de instrumentação OpenTelemetry automática para.NET e precisar executar instrumentação manual em seu aplicativo, por exemplo, para instrumentar o código dentro do próprio aplicativo para seções que não são cobertas por nenhuma biblioteca de instrumentação automática. Como pode haver somente um `TracerProvider` global, a instrumentação manual não deve instanciar seu próprio `TracerProvider` se usada em conjunto com a instrumentação automática. Quando `TracerProvider` usado, o rastreamento manual personalizado funciona da mesma forma ao usar instrumentação automática ou instrumentação manual por meio do SDK. OpenTelemetry ------ ## Rastrear solicitações recebidas (instrumentação do ASP.NET e do ASP.NET Core) ------ #### [ With X-Ray SDK ] Para instrumentar solicitações atendidas pela aplicação 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 obter informações sobre como chamar o `RegisterXRay` no método `Init` do seu arquivo `global.asax`. ``` AWSXRayASPNET.RegisterXRay(this, "MyApp"); ``` Para instrumentar as solicitações atendidas pela sua aplicação do ASP.NET Core, o método `UseXRay` é chamado antes de qualquer outro middleware no método `Configure` da sua classe de inicialização. ``` app.UseXRay("MyApp"); ``` ------ #### [ With OpenTelemetry SDK ] OpenTelemetry também fornece bibliotecas de instrumentação para coletar rastreamentos para solicitações da Web recebidas para ASP.NET e ASP.NET core. A seção a seguir lista as etapas necessárias para adicionar e habilitar essas instrumentações de biblioteca para sua OpenTelemetry configuração, incluindo como adicionar instrumentação [ASP.NET ou [ASP.NET](https://learn.microsoft.com/en-us/aspnet/core/?view=aspnetcore-9.0)](https://learn.microsoft.com/en-us/aspnet/overview) core ao criar o Tracer Provider. Para obter informações sobre como habilitar OpenTelemetry .Instrumentation. AspNet, consulte [Etapas para habilitar OpenTelemetry .Instrumentation. AspNet](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNet#steps-to-enable-opentelemetryinstrumentationaspnet)e para obter informações sobre como habilitar OpenTelemetry .Instrumentation. AspNetCore, consulte [Etapas para habilitar OpenTelemetry .Instrumentation. AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.AspNetCore#steps-to-enable-opentelemetryinstrumentationaspnetcore). ------ ## AWS Instrumentação do SDK ------ #### [ With X-Ray SDK ] Instale todos os clientes do AWS SDK `RegisterXRayForAllServices()` ligando. ``` 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 ``` Use um dos métodos a seguir para instrumentação específica do cliente de AWS serviço. ``` 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 o exemplo de código a seguir, você precisará da seguinte dependência: ``` dotnet add package OpenTelemetry.Instrumentation.AWS ``` Para instrumentar o AWS SDK, atualize a configuração do OpenTelemetry SDK onde o Global TracerProvider está configurado. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddAWSInstrumentation() ... ``` ------ ## Instrumentar chamadas HTTP de saída ------ #### [ With X-Ray SDK ] O SDK .NET do X-Ray rastreia as chamadas HTTP de saída por meio dos métodos de extensão `GetResponseTraced()` ou `GetAsyncResponseTraced()` durante o uso de `System.Net.HttpWebRequest` ou usando o manipulador `HttpClientXRayTracingHandler` durante o uso de `System.Net.Http.HttpClient`. ------ #### [ With OpenTelemetry SDK ] Para o exemplo de código a seguir, você precisará da seguinte dependência: ``` dotnet add package OpenTelemetry.Instrumentation.Http ``` Para instrumentar `System.Net.Http.HttpClient` e`System.Net.HttpWebRequest`, atualize a configuração do OpenTelemetry SDK onde o Global TracerProvider está configurado. ``` builder.Services.AddOpenTelemetry() ... .WithTracing(tracing => tracing .AddHttpClientInstrumentation() ... ``` ------ ## Suporte de instrumentação para outras bibliotecas Você pode pesquisar e filtrar o OpenTelemetry Registro para bibliotecas de instrumentação.NET para descobrir se OpenTelemetry oferece suporte à instrumentação para sua biblioteca. Consulte o [Registry](https://opentelemetry.io/ecosystem/registry/) para começar a pesquisar. ## Instrumentação do Lambda ------ #### [ With X-Ray SDK ] O procedimento a seguir foi necessário para usar o SDK do X-Ray com o Lambda: 1. Habilitar o *Rastreamento ativo* na sua função do Lambda 1. O serviço Lambda cria um segmento que representa a invocação do seu manipulador 1. Criar subsegmentos ou bibliotecas de instrumentos usando o SDK do X-Ray ------ #### [ With OpenTelemetry-based solutions ] Você pode instrumentar automaticamente seu Lambda com camadas personalizadas do AWS Lambda. Existem duas soluções: + (Recomendado) [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-application-signals.html) Layer para OpenTelemetry + Para um melhor desempenho, talvez você queira considerar o uso `OpenTelemetry Manual Instrumentation` para gerar OpenTelemetry rastreamentos para sua função Lambda. ------ **OpenTelemetry instrumentação manual para Lambda AWS ** Veja a seguir um exemplo do código da função do Lambda (sem instrumentação). ``` 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 seu manipulador do Lambda e o cliente do Amazon S3, faça o seguinte: 1. Instanciar um TracerProvider — Recomenda-se que TracerProvider seja configurado com um`XrayUdpSpanExporter`, um ParentBased Always On Sampler e um `Resource` com `service.name` definido como o nome da função Lambda. 1. Instrumente o cliente Amazon S3 com a instrumentação do OpenTemetry AWS SDK ligando para adicionar a instrumentação do cliente do SDK `AddAWSInstrumentation()` ao AWS `TracerProvider` 1. Crie uma função wrapper com a mesma assinatura da função do Lambda original. Chame a API `AWSLambdaWrapper.Trace()` e passe `TracerProvider`, a função do Lambda original, e suas entradas como parâmetros. Defina a função wrapper como a entrada do manipulador do Lambda. Para o exemplo de código a seguir, você precisará das seguintes dependências: ``` 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 ``` O código a seguir demonstra a função do Lambda após as alterações necessárias. É possível criar extensões personalizadas adicionais para complementar as extensões fornecidas automaticamente. ``` 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); } } } ``` Ao invocar esse Lambda, você verá o seguinte rastreamento no Trace Map no console: CloudWatch ![\[Mapa de rastreamento no CloudWatch console para.Net\]](http://docs.aws.amazon.com/pt_br/xray/latest/devguide/images/deprecation_dotnet.png)