Soluciones de instrumentación automática sin código Soluciones de instrumentación manual con el SDK Creación manual de datos de rastros Rastreo de las solicitudes entrantes (ASP.NET e instrumentación básica de ASP.NET)AWS Instrumentación del SDK Instrumentación de llamadas a HTTP salientes Compatibilidad de instrumentación para otras bibliotecas Instrumentación de Lambda

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 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 sección.

Secciones

Soluciones de instrumentación automática sin código
Soluciones de instrumentación manual con el SDK
Creación manual de datos de rastros
Rastreo de las solicitudes entrantes (ASP.NET e instrumentación básica de ASP.NET)
AWS Instrumentación del SDK
Instrumentación de llamadas a HTTP salientes
Compatibilidad de instrumentación para otras bibliotecas
Instrumentación de Lambda

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

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. 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.
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 .NET. AWS OpenTelemetry

Soluciones de instrumentación manual con el SDK

Tracing configuration with X-Ray SDK

Para las aplicaciones web .NET, el X-Ray SDK se configura en la sección appSettings del archivo Web.config.

Web.config de ejemplo



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

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). Para usarlo OpenTelemetry con otros marcos, consulte el Registro 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 que están integrados con X-Ray
Un muestreador remoto de AWS rayos X: necesario si necesita muestrear solicitudes utilizando las reglas de muestreo de rayos X
Resource Detectors(por ejemplo, Amazon EC2 Resource Detector): 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 en una 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 X-Ray SDK, 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)

AWS Instrumentación del SDK

Instrumentación de llamadas a HTTP salientes

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 para empezar a buscar.

Instrumentación de 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<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 el controlador de Lambda y el cliente de Amazon S3, haga lo siguiente.

Instanciar a TracerProvider : TracerProvider se recomienda configurar con unXrayUdpSpanExporter, un muestreador ParentBased Always On y un Resource con service.name establecido en el nombre de la función Lambda.
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
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<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);
        }
    }
}

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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Migre a Node.js OpenTelemetry

Migrar a OpenTelemetry Python