Migrare a.NET OpenTelemetry - AWS X-Ray
Soluzioni di strumentazione automatica a codice zeroSoluzioni di strumentazione manuale con SDKCreazione manuale di dati di tracciaTracciamento delle richieste in arrivo (strumentazione di base ASP.NET e ASP.NET)AWS Strumentazione SDKAnalisi delle chiamate HTTP in uscitaSupporto alla strumentazione per altre librerieStrumentazione Lambda

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Migrare a.NET OpenTelemetry

Quando si utilizza X-Ray Tracing nelle applicazioni.NET, per la strumentazione viene utilizzato l'SDK X-Ray .NET con operazioni manuali.

Questa sezione fornisce esempi di codice nella Soluzioni di strumentazione manuale con SDK sezione per la migrazione dalla soluzione di strumentazione manuale X-Ray OpenTelemetry alle soluzioni di strumentazione manuale per.NET. In alternativa, è possibile migrare dalla strumentazione manuale X-Ray alle soluzioni di strumentazione automatica OpenTelemetry alle applicazioni.NET dello strumento senza dover modificare il codice sorgente dell'applicazione nella sezione. Soluzioni di strumentazione automatica a codice zero

Soluzioni di strumentazione automatica a codice zero

OpenTelemetry fornisce soluzioni di strumentazione automatica a codice zero. Queste soluzioni tracciano le richieste senza richiedere modifiche al codice dell'applicazione.

OpenTelemetryopzioni di strumentazione automatica basate su

  1. Utilizzo della strumentazione automatica AWS Distro for OpenTelemetry (ADOT) per .NET: per strumentare automaticamente le applicazioni.NET, vedere Tracciamento e metriche con la distribuzione per strumentazione automatica.NET. AWS OpenTelemetry

    (Facoltativo) Abilita i segnali CloudWatch applicativi durante la strumentazione automatica delle applicazioni AWS con la strumentazione automatica ADOT .NET per:

    • Monitora lo stato attuale delle applicazioni

    • Monitora le prestazioni delle applicazioni a lungo termine rispetto agli obiettivi aziendali

    • Ottieni una visione unificata e incentrata sulle applicazioni delle tue applicazioni, servizi e dipendenze

    • Monitora e valuta lo stato delle applicazioni

    Per ulteriori informazioni, consulta Application Signals.

  2. Utilizzo della strumentazione OpenTelemetry automatica.Net a codice zero: per la strumentazione automatica con OpenTelemetry .Net, consulta Tracciamento e metriche con la distribuzione per la strumentazione automatica.NET. AWS OpenTelemetry

Soluzioni di strumentazione manuale con SDK

Tracing configuration with X-Ray SDK

Per le applicazioni Web.NET, l'SDK X-Ray è configurato nella sezione AppSettings del file. Web.config

Esempio Web.config


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

Per .NET Core, viene utilizzato un file denominato appsettings.json con una chiave di primo livello denominataXRay, quindi viene creato un oggetto di configurazione per inizializzare il registratore X-Ray.

Esempio per.NET appsettings.json


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

Esempio di configurazione di.NET Core Program.cs — Recorder


using Amazon.XRay.Recorder.Core;
...
AWSXRayRecorder.InitializeInstance(configuration);
Tracing configuration with OpenTelemetry SDK

Aggiungi queste dipendenze:


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

Per la tua applicazione.NET, configura l' OpenTelemetry SDK configurando Global. TracerProvider La configurazione di esempio seguente abilita anche la strumentazione per. ASP.NET Core Per lo strumentoASP.NET, vedere. Tracciamento delle richieste in arrivo (strumentazione di base ASP.NET e ASP.NET) Per utilizzarlo OpenTelemetry con altri framework, consulta Registry per ulteriori librerie per i framework supportati.

Si consiglia di configurare i seguenti componenti:

  • An OTLP Exporter— Necessario per esportare le tracce nell' CloudWatch OpenTelemetry Agent/ Collector

  • Un propagatore AWS a raggi X: necessario per propagare il Trace Context ai AWS servizi integrati con X-Ray

  • Un campionatore remoto AWS a raggi X: necessario se è necessario campionare le richieste utilizzando le regole di campionamento a raggi X

  • Resource Detectors(ad esempio, Amazon EC2 Resource Detector): per rilevare i metadati dell'host che esegue l'applicazione


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

Da utilizzare OpenTelemetry per un'app per console, aggiungi la seguente OpenTelemetry configurazione all'avvio del programma.


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

Creazione manuale di dati di traccia

With X-Ray SDK

Con X-Ray SDK, erano necessari i BeginSubsegment metodi BeginSegment and per creare manualmente segmenti e sottosegmenti 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

In .NET, è possibile utilizzare l'API Activity per creare intervalli personalizzati per monitorare le prestazioni delle attività interne che non vengono acquisite dalle librerie di strumentazione. Nota che solo gli intervalli di tipo Server vengono convertiti in segmenti X-Ray, tutti gli altri intervalli vengono convertiti in sotto-segmenti X-Ray.

È possibile creare tutte ActivitySource le istanze necessarie, ma si consiglia di averne solo una per un'intera applicazione/servizio.


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

Aggiungere annotazioni e metadati alle tracce con SDK OpenTelemetry

Puoi anche aggiungere coppie chiave-valore personalizzate come attributi agli intervalli utilizzando il metodo su un'attività. SetTag Nota che per impostazione predefinita, tutti gli attributi span verranno convertiti in metadati nei dati grezzi di X-Ray. Per garantire che un attributo venga convertito in un'annotazione e non in metadati, puoi aggiungere la chiave di quell'attributo all'elenco degli attributi. 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 OpenTelemetry strumentazione automatica

Se si utilizza una soluzione di strumentazione OpenTelemetry automatica per.NET e se è necessario eseguire la strumentazione manuale nell'applicazione, ad esempio, per codificare lo strumento all'interno dell'applicazione stessa per sezioni che non sono coperte da alcuna libreria di strumentazione automatica.

Poiché può esserci solo una strumentazione globaleTracerProvider, la strumentazione manuale non dovrebbe istanziare la propria TracerProvider se utilizzata insieme alla strumentazione automatica. Quando TracerProvider viene utilizzato, il tracciamento manuale personalizzato funziona allo stesso modo quando si utilizza la strumentazione automatica o la strumentazione manuale tramite l'SDK. OpenTelemetry

Tracciamento delle richieste in arrivo (strumentazione di base ASP.NET e ASP.NET)

With X-Ray SDK

Per informazioni sulle richieste di strumenti servite dall'applicazione ASP.NET, consulta https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html per informazioni su come RegisterXRay richiamare il Init metodo del file. global.asax


AWSXRayASPNET.RegisterXRay(this, "MyApp");

Per le richieste di strumenti servite dall'applicazione principale ASP.NET, il UseXRay metodo viene chiamato prima di qualsiasi altro middleware nel Configure metodo della classe Startup.


app.UseXRay("MyApp");
With OpenTelemetry SDK

OpenTelemetry fornisce inoltre librerie di strumentazione per raccogliere tracce per le richieste Web in entrata per ASP.NET e ASP.NET core. La sezione seguente elenca i passaggi necessari per aggiungere e abilitare questi strumenti di libreria per la OpenTelemetry configurazione, incluso come aggiungere la strumentazione di base ASP.NET o ASP.NET durante la creazione del Tracer Provider.

Per informazioni su come abilitare .Instrumentation. OpenTelemetry AspNet, vedi Passaggi per abilitare .Instrumentation. OpenTelemetry AspNete per informazioni su come abilitare .Instrumentation. OpenTelemetry AspNetCore, vedi Passaggi per abilitare .Instrumentation. OpenTelemetry AspNetCore.

AWS Strumentazione SDK

With X-Ray SDK

Installa tutti i client AWS SDK chiamando. RegisterXRayForAllServices()


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

Utilizzate uno dei seguenti metodi per la strumentazione specifica del client AWS di servizio.


AWSSDKHandler.RegisterXRay<IAmazonDynamoDB>(); // 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

Per il seguente esempio di codice, è necessaria la seguente dipendenza:


dotnet add package OpenTelemetry.Instrumentation.AWS

Per strumentare l' AWS SDK, aggiorna la configurazione OpenTelemetry SDK in cui è configurato il Global TracerProvider .


builder.Services.AddOpenTelemetry()
    ...
    .WithTracing(tracing => tracing
        .AddAWSInstrumentation()
        ...

Analisi delle chiamate HTTP in uscita

With X-Ray SDK

X-Ray .NET SDK traccia le chiamate HTTP in uscita tramite i metodi di estensione GetResponseTraced() o GetAsyncResponseTraced() durante l'utilizzo o utilizzando System.Net.HttpWebRequest il gestore durante l'HttpClientXRayTracingHandlerutilizzo. System.Net.Http.HttpClient

With OpenTelemetry SDK

Per il seguente esempio di codice, è necessaria la seguente dipendenza:


dotnet add package OpenTelemetry.Instrumentation.Http

Per strumentare System.Net.Http.HttpClient eSystem.Net.HttpWebRequest, aggiorna la configurazione dell' OpenTelemetry SDK in cui TracerProvider è configurato il Global.


builder.Services.AddOpenTelemetry()
    ...
    .WithTracing(tracing => tracing
        .AddHttpClientInstrumentation()
        ...

Supporto alla strumentazione per altre librerie

Puoi cercare e filtrare OpenTelemetry nel Registro le librerie di strumentazione.NET per scoprire se OpenTelemetry supporta la strumentazione per la tua libreria. Consulta il Registro per iniziare la ricerca.

Strumentazione Lambda

With X-Ray SDK

Per utilizzare l'SDK X-Ray con Lambda era necessaria la seguente procedura:

  1. Abilita Active Tracing sulla tua funzione Lambda

  2. Il servizio Lambda crea un segmento che rappresenta la chiamata del gestore

  3. Crea sottosegmenti o librerie di strumenti utilizzando l'SDK X-Ray

With OpenTelemetry-based solutions

Puoi strumentare automaticamente la tua Lambda con livelli Lambda AWS venduti. Esistono due soluzioni:

  • (Consigliato) Strato lambda di CloudWatch Application Signals

  • Per prestazioni migliori, potresti prendere in considerazione l'idea di utilizzare per OpenTelemetry Manual Instrumentation generare OpenTelemetry tracce per la tua funzione Lambda.

OpenTelemetry strumentazione manuale per Lambda AWS

Di seguito è riportato l'esempio del codice della funzione Lambda (senza strumentazione).


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);
        }
    }
}

Per strumentare manualmente il tuo gestore Lambda e il client Amazon S3, procedi come segue.

  1. Istanzia a TracerProvider : si TracerProvider consiglia di configurarlo con un XrayUdpSpanExporter campionatore ParentBased Always On e un Resource valore impostato sul nome della funzione service.name Lambda.

  2. Strumenta il client Amazon S3 con la strumentazione OpenTemetry AWS SDK chiamando per aggiungere la strumentazione client SDK AddAWSInstrumentation() a AWS TracerProvider

  3. Crea una funzione wrapper con la stessa firma della funzione Lambda originale. Chiama AWSLambdaWrapper.Trace() l'API e passaTracerProvider, la funzione Lambda originale e i suoi input come parametri. Imposta la funzione wrapper come input del gestore Lambda.

Per il seguente esempio di codice, sono necessarie le seguenti dipendenze:


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

Il codice seguente illustra la funzione Lambda dopo le modifiche richieste. È possibile creare intervalli personalizzati aggiuntivi per completare gli intervalli forniti 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);
        }
    }
}

Quando richiami questa Lambda, vedrai la seguente traccia nella Trace Map della console: CloudWatch

Traccia la mappa nella CloudWatch console per.Net