OpenTelemetry .NET への移行

.NET ウェブアプリケーションの場合、X-Ray SDK はWeb.configファイルの appSettings セクションで設定されます。

Web.config の例

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

.NET Core では、 という名前の最上位キーappsettings.jsonを持つ という名前XRayのファイルが使用され、X-Ray レコーダーを初期化するために設定オブジェクトが構築されます。

.NET の例 appsettings.json

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

.NET Core Program.cs の例 – レコーダー設定

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

これらの依存関係を追加します。

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
        

.NET アプリケーションの場合は、Global TracerProvider を設定して OpenTelemetry SDK を設定します。次の設定例では、 の計測も有効にしますASP.NET Core。を計測するにはASP.NET、「」を参照してください受信リクエストのトレース (ASP.NET および ASP.NET コア計測）。他のフレームワークで OpenTelemetry を使用するには、サポートされているフレームワークのその他のライブラリについては「レジストリ」を参照してください。

次のコンポーネントを設定することをお勧めします。

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 を使用するには、プログラムの起動時に次の OpenTelemetry 設定を追加します。

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
        

X-Ray SDK では、X-Ray セグメントBeginSegmentとサブセグメントを手動で作成するには、 メソッドと BeginSubsegmentメソッドが必要でした。

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

.NET では、アクティビティ API を使用してカスタムスパンを作成し、計測ライブラリでキャプチャされない内部アクティビティのパフォーマンスをモニタリングできます。この種のスパン Server のみが X-Ray セグメントに変換され、他のすべてのスパンは X-Ray サブセグメントに変換されることに注意してください。

必要に応じてインスタンスをいくつでも作成できますがActivitySource、アプリケーション/サービス全体でインスタンスを 1 つだけ作成することをお勧めします。

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

OpenTelemetry SDK を使用してトレースに注釈とメタデータを追加する

アクティビティで SetTagメソッドを使用して、カスタムキーと値のペアを属性としてスパンに追加することもできます。デフォルトでは、すべてのスパン属性は X-Ray raw データ内のメタデータに変換されることに注意してください。属性がメタデータではなく注釈に変換されるようにするには、その属性のキーを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
    }
}
      

OpenTelemetry 自動計測を使用する

.NET 用の OpenTelemetry 自動計測ソリューションを使用している場合、アプリケーションで手動計測を実行する必要がある場合。たとえば、自動計測ライブラリでカバーされていないセクションのコードをアプリケーション自体で計測する場合などです。

グローバル は 1 つしかできないためTracerProvider、自動計測と一緒に使用するTracerProviderと、手動計測は独自の をインスタンス化しないでください。を使用する場合、カスタム手動トレースTracerProviderは、OpenTelemetry SDK で自動計測または手動計測を使用する場合と同じように機能します。

ASP.NET アプリケーションによって処理されるリクエストを計測するには、 global.asax ファイルの InitメソッドRegisterXRayで https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-dotnet-messagehandler.html を呼び出す方法の詳細については、「」を参照してください。

AWSXRayASPNET.RegisterXRay(this, "MyApp");
        

ASP.NET コアアプリケーションによって処理されるリクエストを計測するには、Startup クラスの UseXRayメソッドの他のミドルウェアの前に Configureメソッドが呼び出されます。

app.UseXRay("MyApp");
        

OpenTelemetry には、ASP.NET および ASP.NET Core の受信ウェブリクエストのトレースを収集するための計測ライブラリも用意されています。次のセクションでは、トレースプロバイダーの作成時に ASP.NET または ASP.NET コアインストルメンテーションを追加する方法など、OpenTelemetry 設定でこれらのライブラリインストルメンテーションを追加および有効にするために必要な手順を示します。

OpenTelemetry.Instrumentation.AspNet,OpenTelemetry.Instrumentation.AspNet を有効にするステップ」を参照してください。また、OpenTelemetry.Instrumentation.AspNetCore,OpenTelemetry.Instrumentation.AspNetCore を有効にするステップ」を参照してください。

を呼び出して、すべての AWS SDK クライアントをインストールします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
        

特定の AWS サービスクライアント計測には、次のいずれかの方法を使用します。

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
        

次のコード例では、次の依存関係が必要です。

dotnet add package OpenTelemetry.Instrumentation.AWS
        

AWS SDK を計測するには、Global TracerProvider がセットアップされている OpenTelemetry SDK 設定を更新します。

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

X-Ray .NET SDK は、拡張機能メソッド、 GetResponseTraced() の使用GetAsyncResponseTraced()時System.Net.HttpWebRequest、または の使用時にHttpClientXRayTracingHandlerハンドラを使用して、送信 HTTP 呼び出しをトレースしますSystem.Net.Http.HttpClient。

次のコード例では、次の依存関係が必要です。

dotnet add package OpenTelemetry.Instrumentation.Http
        

System.Net.Http.HttpClient と を計測するにはSystem.Net.HttpWebRequest、Global TracerProvider がセットアップされている OpenTelemetry SDK 設定を更新します。

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

Lambda で X-Ray SDK を使用するには、次の手順が必要です。

AWS 販売された Lambda レイヤーを使用して Lambda を自動的に計測できます。解決策は 2 つあります。