計装ライブラリの使用

アプリを開発する際、作業を加速するためにサードパーティのライブラリやフレームワークを使用することがあるでしょう。 OpenTelemetryを使用してアプリを計装する場合、使用するサードパーティのライブラリやフレームワークにトレース、ログ、メトリクスを手動で追加するために時間を費やすことを避けたいことがあります。

多くのライブラリやフレームワークはすでにOpenTelemetryをサポートしているか、OpenTelemetryの計装を介してサポートされているため、テレメトリーを生成してオブザーバビリティバックエンドにエクスポートできます。

サードパーティのライブラリやフレームワークを使用しているアプリやサービスを計装する場合は、このページの手順に従って、ネイティブに計装されたライブラリと依存関係の計装ライブラリの使用方法を学んでください。

ネイティブに計装されたライブラリを使用する

デフォルトでOpenTelemetryサポートが付属しているライブラリの場合、アプリにOpenTelemetry SDKを追加して設定することで、そのライブラリから発行されるトレース、メトリクス、ログを取得できます。

ライブラリによっては、計装のために追加の構成が必要な場合があります。 詳細はライブラリごとのドキュメントをご覧ください。

• ASP.NET Core
• Azure SDK Instrumentation
• FusionCache .NET caching library
• .NET HttpClient
• MassTransit .NET client
• nservicebus OpenTelemetry Integration
• ThrottlingTroll

計装ライブラリの使用

ライブラリに OpenTelemetry が最初から付属していない場合は、計装ライブラリを使用して、ライブラリまたはフレームワークのテレメトリーデータを生成できます。

たとえば、ASP.NET Core の計装ライブラリは、受信した HTTP リクエストに基づいてスパンとメトリクスを自動的に作成します。

セットアップ

各計装ライブラリは NuGet パッケージであり、通常は以下のようにインストールします。

dotnet add package OpenTelemetry.Instrumentation.{library-name-or-type}

通常、トレーサープロバイダーを作成する際などのアプリケーション起動時に登録します。

バージョニングに関する注意事項

属性名のセマンティック規約（標準）は現在安定しておらず、そのため計装ライブラリも正式リリースの状態ではありません。 これは機能自体が安定していないということではなく、一部の属性名が将来変更される可能性があり、追加や削除が行われる場合があるということです。 つまり、--prerelease フラグを使用するか、パッケージの特定のバージョンをインストールする必要があります。

ASP.NET Core と HttpClient の例

例として、ASP.NET Core アプリから受信リクエストと送信リクエストを計装する方法を示します。

まず、OpenTelemetry Core の適切なパッケージを取得します。

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.Console

次に計装ライブラリをインストールします。

dotnet add package OpenTelemetry.Instrumentation.AspNetCore --prerelease
dotnet add package OpenTelemetry.Instrumentation.Http --prerelease

その後、起動時に各計装ライブラリを設定して使用します。

using OpenTelemetry.Resources;
using OpenTelemetry.Trace;


var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
  .WithTracing(b =>
  {
      b
      .AddHttpClientInstrumentation()
      .AddAspNetCoreInstrumentation();
  });

var app = builder.Build();

var httpClient = new HttpClient();

app.MapGet("/hello", async () =>
{
    var html = await httpClient.GetStringAsync("https://example.com/");
    if (string.IsNullOrWhiteSpace(html))
    {
        return "Hello, World!";
    }
    else
    {
        return "Hello, World!";
    }
});

app.Run();

このコードを実行して /hello エンドポイントにアクセスすると、計装ライブラリは以下を行います。

• 新しいトレースを開始する
• エンドポイントへのリクエストを表すスパンを生成する
• https://example.com/ への HTTP GET を表す子スパンを生成する

さらに計装ライブラリを追加すると、それぞれに対応するスパンが追加されます。

利用可能な計装ライブラリ

OpenTelemetry が提供する計装ライブラリの完全なリストは opentelemetry-dotnet リポジトリから入手できます。

レジストリでも、さらに多くの計装を見つけることができます。

次のステップ

計装ライブラリのセットアップが完了したら、カスタムテレメトリーデータを収集するためにコードに独自の計装を追加することを検討してください。

モダンな .NET ではなく .NET Framework 4.x を使用している場合は、.NET Framework のドキュメントを参照して、.NET Framework 上で OpenTelemetry と計装ライブラリを設定してください。

テレメトリーデータを1つ以上のテレメトリーバックエンドにエクスポートするための適切なエクスポーターも設定する必要があります。

現在ベータ版の .NET の自動計装も確認できます。