OpenTelemetry .NET への移行

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

Web.config の例

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

.NET Core では、XRay という名前の最上位キーを持つ appsettings.json という名前のファイルが使用され、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 アプリケーションの場合は、グローバルな TracerProvider をセットアップして OpenTelemetry SDK を設定します。次の設定例では、ASP.NET Core の計装も有効にします。ASP.NET を計装するには、「受信リクエストのトレース (ASP.NET および ASP.NET Core 計装)」を参照してください。他のフレームワークで OpenTelemetry を使用する場合、サポートされているフレームワークのその他のライブラリについては、「Registry」を参照してください。

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

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 の未加工データのメタデータに変換されることに注意してください。属性がメタデータではなく注釈に変換されるようにするには、その属性のキーを 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 自動計装ソリューションを使用している場合、アプリケーションで手動計装を実行する必要がある場合があります。例えば、自動計装ライブラリでカバーされていないセクションのコードをアプリケーション自体で計装する場合などです。

グローバルな TracerProvider は 1 つしか存在できないため、自動計装と一緒に使用する場合、手動計装は独自の 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 Core アプリケーションによって処理されるリクエストを計装する場合は、Startup クラスの Configure メソッドの他のミドルウェアの前に UseXRay メソッドが呼び出されます。

app.UseXRay("MyApp");
        

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

OpenTelemetry.Instrumentation.AspNet を有効にする方法については、「Steps to enable OpenTelemetry.Instrumentation.AspNet」を参照してください。また、OpenTelemetry.Instrumentation.AspNetCore を有効にする方法については、「Steps to enable 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 は、System.Net.HttpWebRequest を使用する場合は拡張機能メソッド GetResponseTraced() または GetAsyncResponseTraced() を使用して、または System.Net.Http.HttpClient を使用する場合は HttpClientXRayTracingHandler ハンドラーを使用して、送信 HTTP 呼び出しをトレースします。

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

dotnet add package OpenTelemetry.Instrumentation.Http
        

System.Net.Http.HttpClient と System.Net.HttpWebRequest を計装するには、グローバルな TracerProvider がセットアップされている OpenTelemetry SDK 設定を更新します。

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

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

AWS 販売された Lambda レイヤーを使用して Lambda を自動的に計測できます。以下の 2 つのソリューションがあります。