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

Migrar para o.NET OpenTelemetry

Ao usar o X-Ray Tracing em seus aplicativos.NET, o X-Ray .NET SDK 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
Criação manual de dados de rastreamento
Rastreando solicitações recebidas (instrumentação principal do ASP.NET e do ASP.NET)
AWS Instrumentação do SDK
Instrumentar chamadas HTTP de saída
Suporte de instrumentação para outras bibliotecas
Instrumentação 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 do aplicativo.

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:
- Monitore a integridade atual do aplicativo
- Acompanhe o desempenho de longo prazo dos aplicativos em relação aos objetivos de negócios
- Obtenha uma visão unificada e centrada no aplicativo de seus aplicativos, serviços e dependências
- Monitore e faça a triagem da integridade do aplicativo
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 X-Ray SDK é configurado na seção AppSettings do Web.config arquivo.

Exemplo Web.config



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

Para o.NET Core, um arquivo nomeado 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 X-Ray.

Exemplo para o.NET appsettings.json



{
  "XRay": {
    "AWSXRayPlugins": "EC2Plugin"
  }
}

Exemplo do.NET Core Program.cs — Configuração do gravador



using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder.InitializeInstance(configuration);

Tracing configuration with OpenTelemetry SDK

Adicione essas 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 para. ASP.NET Core Para instrumentarASP.NET, consulteRastreando solicitações recebidas (instrumentação principal do ASP.NET e do ASP.NET). Para usar OpenTelemetry com outras estruturas, consulte Registro para obter mais bibliotecas de estruturas compatíveis.

É recomendável que você configure 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

Criação manual de dados de rastreamento

With X-Ray SDK

Com o X-Ray SDK, os BeginSubsegment métodos BeginSegment e foram necessários para criar manualmente segmentos e subsegmentos de raio-X.



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

No.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. Observe que somente extensões do tipo Servidor são convertidas em segmentos de X-Ray, todas as outras extensões são convertidas em subsegmentos de X-Ray.

Você pode criar quantas ActivitySource instâncias forem necessárias, mas é recomendável ter apenas uma para um aplicativo/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 valores-chave personalizados como atributos aos seus intervalos usando o SetTag método em uma atividade. Observe que, por padrão, todos os atributos de amplitude 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, você pode adicionar a chave desse atributo à lista de atributos. 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 uma instrumentação globalTracerProvider, a instrumentação manual não deve ser instanciada 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

Rastreando solicitações recebidas (instrumentação principal do ASP.NET e do ASP.NET)

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

Instrumentação Lambda

OpenTelemetry instrumentação manual para Lambda AWS

Veja a seguir o exemplo do código da função 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 Lambda e o cliente 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 de wrapper com a mesma assinatura da função Lambda original. Chame a AWSLambdaWrapper.Trace() API e passeTracerProvider, a função Lambda original e suas entradas como parâmetros. Defina a função wrapper como a entrada do manipulador 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 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 o Node.js OpenTelemetry

Migrar para Python OpenTelemetry