Solutions d'instrumentation automatique à code zéro Solutions d'instrumentation manuelle avec le SDK Création manuelle de données de trace Suivi des demandes entrantes (ASP.NET et instrumentation de base ASP.NET)AWS Instrumentation du SDK Instrumentation des appels HTTP sortants Support d'instrumentation pour d'autres bibliothèques Instrumentation Lambda

Migrer vers OpenTelemetry .NET

Lorsque vous utilisez X-Ray Tracing dans vos applications .NET, le SDK X-Ray .NET associé à des efforts manuels est utilisé pour l'instrumentation.

Cette section fournit des exemples de code dans la Solutions d'instrumentation manuelle avec le SDK section relative à la migration de la solution d'instrumentation manuelle X-Ray vers des solutions OpenTelemetry d'instrumentation manuelle pour .NET. Vous pouvez également passer de l'instrumentation manuelle X-Ray aux solutions d'instrumentation OpenTelemetry automatique pour les applications .NET d'instrumentation sans avoir à modifier le code source de l'application dans la Solutions d'instrumentation automatique à code zéro section.

Sections

Solutions d'instrumentation automatique à code zéro
Solutions d'instrumentation manuelle avec le SDK
Création manuelle de données de trace
Suivi des demandes entrantes (ASP.NET et instrumentation de base ASP.NET)
AWS Instrumentation du SDK
Instrumentation des appels HTTP sortants
Support d'instrumentation pour d'autres bibliothèques
Instrumentation Lambda

Solutions d'instrumentation automatique à code zéro

OpenTelemetry fournit des solutions d'instrumentation automatique sans code. Ces solutions permettent de suivre les demandes sans qu'il soit nécessaire de modifier le code de votre application.

OpenTelemetryoptions d'instrumentation automatique basées sur des options

Utilisation de la AWS distribution pour l'instrumentation automatique OpenTelemetry (ADOT) pour .NET — Pour instrumenter automatiquement les applications .NET, reportez-vous à la section Suivi et mesures avec la AWS distribution pour l'instrumentation automatique .NET. OpenTelemetry

(Facultatif) Activez les signaux d' CloudWatch application lorsque vous instrumentez automatiquement vos applications AWS avec l'instrumentation automatique ADOT .NET pour :
- Surveiller l'état actuel des applications
- Suivez les performances des applications à long terme par rapport aux objectifs commerciaux
- Bénéficiez d'une vue unifiée et centrée sur les applications de vos applications, services et dépendances
- Surveillez et triez l'état de santé des applications
Pour plus d’informations, veuillez consulter la rubrique Applications Signals.
Utilisation de l'instrumentation automatique sans code OpenTelemetry .Net : pour instrumenter automatiquement avec OpenTelemetry .Net, voir Tracing and Metrics with the AWS Distro pour OpenTelemetry .NET Auto-Instrumentation.

Solutions d'instrumentation manuelle avec le SDK

Tracing configuration with X-Ray SDK

Pour les applications Web .NET, le SDK X-Ray est configuré dans la section AppSettings du Web.config fichier.

Exemple Web.config



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

Pour .NET Core, un fichier nommé appsettings.json avec une clé de niveau supérieur XRay est utilisé, puis un objet de configuration est créé pour initialiser l'enregistreur X-Ray.

Exemple pour .NET appsettings.json



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

Exemple pour .NET Core Program.cs — Configuration de l'enregistreur



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

Tracing configuration with OpenTelemetry SDK

Ajoutez les dépendances suivantes :



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

Pour votre application .NET, configurez le OpenTelemetry SDK en configurant le Global TracerProvider. L'exemple de configuration suivant active également l'instrumentation pourASP.NET Core. Pour instrumenterASP.NET, voirSuivi des demandes entrantes (ASP.NET et instrumentation de base ASP.NET). Pour OpenTelemetry une utilisation avec d'autres frameworks, voir Registry pour plus de bibliothèques pour les frameworks pris en charge.

Il est recommandé de configurer les composants suivants :

An OTLP Exporter— Nécessaire pour exporter les traces vers l' CloudWatch OpenTelemetry agent/le collecteur
Un propagateur de AWS rayons X : nécessaire pour propager le contexte de trace aux AWS services intégrés à X-Ray
Un échantillonneur à distance AWS X-Ray : obligatoire si vous devez prélever des échantillons à l'aide des règles d'échantillonnage X-Ray
Resource Detectors(par exemple, Amazon EC2 Resource Detector) : pour détecter les métadonnées de l'hôte exécutant votre application



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 Pour l'utiliser pour une application console, ajoutez la OpenTelemetry configuration suivante au démarrage de votre programme.



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

Création manuelle de données de trace

With X-Ray SDK

Avec le SDK X-Ray, les BeginSubsegment méthodes BeginSegment et étaient nécessaires pour créer manuellement des segments et des sous-segments 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

Dans .NET, vous pouvez utiliser l'API d'activité pour créer des intervalles personnalisés afin de surveiller les performances des activités internes qui ne sont pas capturées par les bibliothèques d'instrumentation. Notez que seules les plages de type Server sont converties en segments X-Ray, toutes les autres plages sont converties en sous-segments de X-Ray.

Vous pouvez créer autant d'ActivitySourceinstances que nécessaire, mais il est recommandé de n'en avoir qu'une pour l'ensemble d'une application/d' un service.



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

Ajouter des annotations et des métadonnées aux traces avec OpenTelemetry le SDK

Vous pouvez également ajouter des paires clé-valeur personnalisées en tant qu'attributs à vos spans en utilisant la SetTag méthode appliquée à une activité. Notez que par défaut, tous les attributs de span seront convertis en métadonnées dans les données brutes de X-Ray. Pour garantir qu'un attribut est converti en annotation et non en métadonnées, vous pouvez ajouter la clé de cet attribut à la liste des aws.xray.annotations attributs.



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

Avec instrumentation OpenTelemetry automatique

Si vous utilisez une solution d'instrumentation OpenTelemetry automatique pour .NET et si vous devez effectuer une instrumentation manuelle dans votre application, par exemple, pour coder des instruments dans l'application elle-même pour les sections qui ne sont couvertes par aucune bibliothèque d'instrumentation automatique.

Comme il ne peut y avoir qu'une seule instrumentation globaleTracerProvider, l'instrumentation manuelle ne doit pas instancier la sienne TracerProvider si elle est utilisée conjointement avec l'instrumentation automatique. Lorsqu'il TracerProvider est utilisé, le traçage manuel personnalisé fonctionne de la même manière lors de l'utilisation d'une instrumentation automatique ou manuelle via le OpenTelemetry SDK.

Suivi des demandes entrantes (ASP.NET et instrumentation de base ASP.NET)

AWS Instrumentation du SDK

Instrumentation des appels HTTP sortants

Support d'instrumentation pour d'autres bibliothèques

Vous pouvez rechercher et filtrer les bibliothèques d'instrumentation .NET OpenTelemetry dans le registre afin de déterminer si votre bibliothèque OpenTelemetry prend en charge l'instrumentation. Consultez le registre pour commencer la recherche.

Instrumentation Lambda

OpenTelemetry instrumentation manuelle pour AWS Lambda

Voici un exemple de code de fonction Lambda (sans instrumentation).



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

Pour instrumenter manuellement votre gestionnaire Lambda et le client Amazon S3, procédez comme suit.

Instancier a TracerProvider — Il TracerProvider est recommandé de le configurer avec unXrayUdpSpanExporter, un échantillonneur ParentBased Always On et un Resource with service.name définis sur le nom de la fonction Lambda.
Instrumenter le client Amazon S3 avec l'instrumentation du OpenTemetry AWS SDK en appelant AddAWSInstrumentation() pour ajouter l'instrumentation du client du AWS SDK à TracerProvider
Créez une fonction wrapper avec la même signature que la fonction Lambda d'origine. Appelez AWSLambdaWrapper.Trace() l'API et transmettez TracerProvider la fonction Lambda d'origine et ses entrées en tant que paramètres. Définissez la fonction wrapper comme entrée du gestionnaire Lambda.

Pour l'exemple de code suivant, vous aurez besoin des dépendances suivantes :



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

Le code suivant illustre la fonction Lambda après les modifications requises. Vous pouvez créer des travées personnalisées supplémentaires pour compléter les travées fournies automatiquement.



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

Lorsque vous invoquez cette Lambda, vous verrez la trace suivante dans la carte de suivi de la console : CloudWatch

Tracer la carte dans CloudWatch la console pour .Net

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Migrer vers OpenTelemetry Node.js

Migrer vers OpenTelemetry Python