Automatische Instrumentierungslösungen ohne Code Lösungen für die manuelle Instrumentierung mit dem SDK Manuelles Erstellen von Trace-Daten Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung)AWS SDK-Instrumentierung Instrumentieren von ausgehenden HTTP-Aufrufen Instrumentierungsunterstützung für andere Bibliotheken Lambda-Instrumentierung

Migrieren Sie zu .NET OpenTelemetry

Wenn Sie X-Ray Tracing in Ihren .NET-Anwendungen verwenden, wird das X-Ray-.NET-SDK mit manuellem Aufwand für die Instrumentierung verwendet.

Dieser Abschnitt enthält Codebeispiele im Lösungen für die manuelle Instrumentierung mit dem SDK Abschnitt für die Migration von der manuellen X-Ray-Instrumentierungslösung zu OpenTelemetry manuellen Instrumentierungslösungen für.NET. Alternativ können Sie von manueller X-Ray-Instrumentierung zu OpenTelemetry automatischen Instrumentierungslösungen für Instrumenten-.NET-Anwendungen migrieren, ohne den Quellcode der Anwendung in Automatische Instrumentierungslösungen ohne Code diesem Abschnitt ändern zu müssen.

Sections

Automatische Instrumentierungslösungen ohne Code
Lösungen für die manuelle Instrumentierung mit dem SDK
Manuelles Erstellen von Trace-Daten
Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung)
AWS SDK-Instrumentierung
Instrumentieren von ausgehenden HTTP-Aufrufen
Instrumentierungsunterstützung für andere Bibliotheken
Lambda-Instrumentierung

Automatische Instrumentierungslösungen ohne Code

OpenTelemetry bietet automatische Instrumentierungslösungen ohne Code. Diese Lösungen verfolgen Anfragen, ohne dass Änderungen an Ihrem Anwendungscode erforderlich sind.

OpenTelemetrybasierte Optionen für automatische Instrumentierung

Verwenden der AWS Distro for OpenTelemetry (ADOT) Auto-Instrumentation für .NET — Informationen zur automatischen Instrumentierung von.NET-Anwendungen finden Sie unter Tracing and Metrics with the AWS Distro for .NET Auto-Instrumentation. OpenTelemetry

(Optional) Aktivieren Sie CloudWatch Application Signals, wenn Sie Ihre Anwendungen AWS mit der automatischen ADOT.NET-Instrumentierung automatisch instrumentieren, um:
- Überwachen Sie den aktuellen Zustand der Anwendung
- Verfolgen Sie die langfristige Anwendungsleistung anhand der Geschäftsziele
- Verschaffen Sie sich einen einheitlichen, anwendungsorientierten Überblick über Ihre Anwendungen, Services und Abhängigkeiten
- Überwachen und prüfen Sie den Zustand Ihrer Anwendungen
Weitere Informationen finden Sie unter Application Signals.
Verwenden der automatischen Null-Code-Instrumentierung OpenTelemetry von.Net — Informationen zur automatischen Instrumentierung OpenTelemetry mit.Net finden Sie unter Tracing and Metrics with the AWS Distro for .NET Auto-Instrumentation. OpenTelemetry

Lösungen für die manuelle Instrumentierung mit dem SDK

Tracing configuration with X-Ray SDK

Für .NET-Webanwendungen wird das X-Ray-SDK im Abschnitt AppSettings der Web.config Datei konfiguriert.

Beispiel Web.config



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

Für .NET Core wird eine Datei appsettings.json mit einem Schlüssel der obersten Ebene namens verwendet, und dann XRay wird ein Konfigurationsobjekt erstellt, um den X-Ray-Recorder zu initialisieren.

Beispiel für.NET appsettings.json



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

Beispiel für.NET Core Program.cs — Recorder-Konfiguration



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

Tracing configuration with OpenTelemetry SDK

Fügen Sie diese Abhängigkeiten hinzu:



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

Konfigurieren Sie das OpenTelemetry SDK für Ihre .NET-Anwendung, indem Sie Global einrichten TracerProvider. Die folgende Beispielkonfiguration ermöglicht auch die Instrumentierung fürASP.NET Core. Informationen zur ASP.NET Instrumentierung finden Sie unterNachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung). Informationen zur Verwendung OpenTelemetry mit anderen Frameworks finden Sie unter Registry für weitere Bibliotheken für unterstützte Frameworks.

Es wird empfohlen, die folgenden Komponenten zu konfigurieren:

An OTLP Exporter— Erforderlich für den Export von Traces zum CloudWatch Agent/Collector OpenTelemetry
Ein AWS X-Ray Propagator — Erforderlich für die Weitergabe des Trace-Kontextes an AWS Dienste, die in X-Ray integriert sind
Ein AWS Röntgen-Remote-Sampler — Erforderlich, wenn Sie Anfragen anhand von Röntgenprobenahmeregeln beproben müssen
Resource Detectors(zum Beispiel Amazon EC2 Resource Detector) — Um Metadaten des Hosts zu erkennen, auf dem Ihre Anwendung ausgeführt wird



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

Um sie OpenTelemetry für eine Konsolen-App zu verwenden, fügen Sie beim Start Ihres Programms die folgende OpenTelemetry Konfiguration hinzu.



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

Manuelles Erstellen von Trace-Daten

With X-Ray SDK

Mit dem X-Ray-SDK waren die BeginSubsegment Methoden BeginSegment und erforderlich, um X-Ray-Segmente und -Untersegmente manuell zu erstellen.



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 können Sie die Aktivitäts-API verwenden, um benutzerdefinierte Bereiche zu erstellen, um die Leistung interner Aktivitäten zu überwachen, die nicht von Instrumentenbibliotheken erfasst werden. Beachten Sie, dass nur Bereiche der Art Server in X-Ray-Segmente umgewandelt werden, alle anderen Bereiche werden in X-Ray-Subsegmente umgewandelt.

Sie können so viele ActivitySource Instanzen wie nötig erstellen, es wird jedoch empfohlen, nur eine für eine gesamte Anwendung/einen Dienst zu verwenden.



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

Hinzufügen von Anmerkungen und Metadaten zu Traces mit dem SDK OpenTelemetry

Sie können Ihren Spans auch benutzerdefinierte Schlüssel-Wert-Paare als Attribute hinzufügen, indem Sie die SetTag Methode für eine Aktivität verwenden. Beachten Sie, dass standardmäßig alle Span-Attribute in X-Rohdaten in Metadaten umgewandelt werden. Um sicherzustellen, dass ein Attribut in eine Anmerkung und nicht in Metadaten umgewandelt wird, können Sie den Schlüssel dieses Attributs zur aws.xray.annotations Attributliste hinzufügen.



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

Mit OpenTelemetry automatischer Instrumentierung

Wenn Sie eine OpenTelemetry automatische Instrumentierungslösung für .NET verwenden und in Ihrer Anwendung manuelle Instrumentierung durchführen müssen, um beispielsweise Code innerhalb der Anwendung selbst für Abschnitte zu instrumentieren, die nicht von einer Bibliothek für automatische Instrumentierung abgedeckt werden.

Da es nur eine globale Instrumentierung geben kannTracerProvider, sollte die manuelle Instrumentierung nicht ihre eigene instanziieren, TracerProvider wenn sie zusammen mit der automatischen Instrumentierung verwendet wird. Wenn diese TracerProvider Option verwendet wird, funktioniert die benutzerdefinierte manuelle Ablaufverfolgung genauso, wenn automatische Instrumentierung oder manuelle Instrumentierung über das SDK verwendet wird. OpenTelemetry

Nachverfolgung eingehender Anfragen (ASP.NET und ASP.NET-Kerninstrumentierung)

AWS SDK-Instrumentierung

Instrumentieren von ausgehenden HTTP-Aufrufen

Instrumentierungsunterstützung für andere Bibliotheken

Sie können die OpenTelemetry Registry nach .NET-Instrumentierungsbibliotheken durchsuchen und filtern, um herauszufinden, ob OpenTelemetry die Instrumentierung für Ihre Bibliothek unterstützt wird. Suchen Sie in der Registry nach, um mit der Suche zu beginnen.

Lambda-Instrumentierung

OpenTelemetry manuelle Instrumentierung für AWS Lambda

Im Folgenden finden Sie ein Beispiel für einen Lambda-Funktionscode (ohne Instrumentierung).



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

Gehen Sie wie folgt vor, um Ihren Lambda-Handler und den Amazon S3 S3-Client manuell zu instrumentieren.

Instanziieren Sie a TracerProvider — TracerProvider Es wird empfohlen, das mit einemXrayUdpSpanExporter, einem ParentBased Always On Sampler und a Resource zu konfigurieren, das auf den Namen der service.name Lambda-Funktion gesetzt ist.
Instrumentieren Sie den Amazon S3 S3-Client mit der OpenTemetry AWS SDK-Instrumentierung, indem Sie aufrufenAddAWSInstrumentation(), um die AWS SDK-Client-Instrumentierung hinzuzufügen TracerProvider
Erstellen Sie eine Wrapper-Funktion mit derselben Signatur wie die ursprüngliche Lambda-Funktion. Rufen Sie AWSLambdaWrapper.Trace() API auf und übergeben TracerProvider Sie die ursprüngliche Lambda-Funktion und ihre Eingaben als Parameter. Stellen Sie die Wrapper-Funktion als Lambda-Handler-Eingabe ein.

Für das folgende Codebeispiel benötigen Sie die folgenden Abhängigkeiten:



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

Der folgende Code demonstriert die Lambda-Funktion nach den erforderlichen Änderungen. Sie können zusätzliche benutzerdefinierte Bereiche erstellen, um die automatisch bereitgestellten Bereiche zu ergänzen.



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

Wenn Sie dieses Lambda aufrufen, sehen Sie den folgenden Trace in der Trace Map in der CloudWatch Konsole:

Trace-Map in der CloudWatch Konsole für .Net

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Migrieren Sie zu Node.js OpenTelemetry

Zu OpenTelemetry Python migrieren