Soluções de instrumentação automática de código zero Soluções de instrumentação manual com o SDK Criar dados de rastreamento manualmente Rastrear solicitações recebidas (instrumentação do ASP.NET e do ASP.NET Core)AWS Instrumentação do SDK Instrumentar chamadas HTTP de saída Suporte de instrumentação para outras bibliotecas Instrumentação do Lambda

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 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

Seções

Soluções de instrumentação automática de código zero
Soluções de instrumentação manual com o SDK
Criar dados de rastreamento manualmente
Rastrear solicitações recebidas (instrumentação do ASP.NET e do ASP.NET Core)
AWS Instrumentação do SDK
Instrumentar chamadas HTTP de saída
Suporte de instrumentação para outras bibliotecas
Instrumentação do Lambda

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

Usando a AWS distro para instrumentação automática OpenTelemetry (ADOT) para.NET — Para instrumentar automaticamente aplicativos.NET, consulte Rastreamento e métricas com a distribuição para instrumentação automática.NET. AWS OpenTelemetry

(Opcional) Ative os sinais de CloudWatch aplicativos 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.
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 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



<configuration>
  <appSettings>
    <add key="AWSXRayPlugins" value="EC2Plugin"/>
  </appSettings>
</configuration>

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). Para usar OpenTelemetry com outras estruturas, consulte Registro 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 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
Resource Detectors(por exemplo, Amazon EC2 Resource Detector) - Para detectar metadados do host que executa seu aplicativo



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, você pode usar 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.

Você pode 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

Você também pode 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 só pode haver 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)

AWS Instrumentação do SDK

Instrumentar chamadas HTTP de saída

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 para começar a pesquisar.

Instrumentação do 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<string> 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<ListBucketsResponse> 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:

Instanciar um TracerProvider — Recomenda-se que TracerProvider seja configurado com umXrayUdpSpanExporter, um ParentBased Always On Sampler e um Resource com service.name definido como o nome da função Lambda.
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
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. Você pode 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<string> HandleRequest(object input, ILambdaContext context)
    => await AWSLambdaWrapper.Trace(tracerProvider, OriginalHandleRequest, input, context);

    public async Task<string> 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<ListBucketsResponse> 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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Migrar para Node.js OpenTelemetry

Migrar para Python OpenTelemetry