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

Migre a .NET OpenTelemetry

Al utilizar el trazado de rayos X en sus aplicaciones.NET, se utiliza el SDK X-Ray.NET 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 de código cero sección.

Secciones

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

Soluciones de instrumentación automática de código cero

OpenTelemetry proporciona soluciones de autoinstrumentación sin código. Estas soluciones rastrean las solicitudes sin necesidad de cambiar el código de la aplicación.

OpenTelemetrybasadas en opciones de instrumentación automática

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:
- Supervise el estado actual de las aplicaciones
- Realice un seguimiento del rendimiento de las aplicaciones a largo plazo en comparación con los
- Obtenga una visión unificada y centrada en las aplicaciones de sus aplicaciones, servicios y dependencias
- Supervise y clasifique el 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 OpenTelemetry .Net, consulte Tracing and Metrics with the Distro para ver la AWS instrumentación automática de .NET. 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 Web.config archivo.

Ejemplo: Web.config



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

En el caso de.NET Core, se utiliza un archivo denominado appsettings.json con una clave de nivel superior y, a continuación, XRay se crea un objeto de configuración para inicializar la grabadora de rayos X.

Ejemplo para .NET appsettings.json



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

Ejemplo de .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. El siguiente ejemplo de configuración también habilita la instrumentación paraASP.NET Core. Para instrumentarASP.NET, consulteRastreo de las solicitudes entrantes (instrumentación básica de ASP.NET y ASP.NET). Para usarlo OpenTelemetry con otros marcos, consulte el Registro para ver más bibliotecas de marcos compatibles.

Se recomienda configurar los siguientes componentes:

An OTLP Exporter— Necesario para exportar las trazas al CloudWatch OpenTelemetry agente/recopilador
Un propagador de AWS rayos X: necesario para propagar el contexto de rastreo a AWS los servicios 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 rastreo

With X-Ray SDK

Con el SDK de X-Ray, se necesitaban BeginSubsegment los métodos BeginSegment y métodos para crear manualmente segmentos y subsegmentos de rayos 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

En .NET, puede usar la API de actividades para crear intervalos personalizados con el fin de supervisar el rendimiento de las actividades internas que no se capturan en las bibliotecas de instrumentación. Tenga en cuenta que solo los tramos del tipo Server se convierten en segmentos de rayos X, todos los demás tramos se convierten en subsegmentos de rayos X.

Puede crear tantas ActivitySource instancias como necesite, pero se recomienda tener solo una para toda la aplicación/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 el SDK OpenTelemetry

También puedes añadir pares clave-valor personalizados como atributos a tus intervalos mediante el SetTag método de una actividad. Tenga en cuenta que, de forma predeterminada, todos los atributos del 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 añadir la clave de ese atributo a la lista de aws.xray.annotations atributos.



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 una globalTracerProvider, la instrumentación manual no debe crear una instancia propia 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 (instrumentación básica de ASP.NET y ASP.NET)

AWS Instrumentación del SDK

Instrumentación de llamadas a HTTP salientes

Soporte de instrumentación para otras bibliotecas

Puede buscar y filtrar el OpenTelemetry registro de bibliotecas de instrumentación.NET para averiguar si OpenTelemetry es compatible con la instrumentación de su biblioteca. Consulte el Registro para empezar a buscar.

Instrumentación Lambda

OpenTelemetry instrumentación manual para Lambda AWS

A continuación se muestra el ejemplo del código de una función 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 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 contenedora con la misma firma que la función Lambda original. Llame a AWSLambdaWrapper.Trace() API y paseTracerProvider, la función Lambda original y sus entradas como parámetros. Configure la función contenedora como entrada del controlador Lambda.

Para el siguiente ejemplo de código, 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 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