例: OTLP とスタンドアロン Aspire Dashboard を OpenTelemetry と併用する

[アーティクル]
10/15/2024

これは、OpenTelemetry による .NET の監視を示す一連の例の 1 つです。

.NET Aspire の標準的な部分であるだけでなく、Aspire Dashboard はスタンドアロン Docker コンテナーとして利用できます。これにより、OTLP エンドポイントテレメトリを送信でき、ログ、メトリック、トレースを視覚化します。この方法でダッシュボードを使用すると、.NET Aspire に依存せずに済み、OTLP 経由でテレメトリを送信するすべてのアプリケーションからのテレメトリが視覚化されます。 Java、GoLang、Python などで記述されたアプリケーションでも同様に機能します。テレメトリを OTLP エンドポイントに送信できる場合に限ります。

Aspire Dashboard を使用すると、Prometheus、Grafana、Jaeger などのオープンソースソリューションを使用する場合よりも構成とセットアップの手順が少なくなります。ただし、これらのツールとは異なり、Aspire Dashboard は開発者向けの視覚化ツールであり、運用環境の監視用ではありません。

1.プロジェクトを作成する

Visual Studio の ASP.NET Core Empty テンプレートまたは次の .NET CLI コマンドを使用して、単純な Web API プロジェクトを作成します。

dotnet new web

2. メトリックおよびアクティビティ定義を追加する

次のコードは、API が呼び出された回数の新しいメトリック (greetings.count) と、新しいアクティビティソース (Otel.Example) を定義します。

// Custom metrics for the application
var greeterMeter = new Meter("OTel.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OTel.Example");

3. API エンドポイントを作成する

builder.Build(); と app.Run() の間に以下を挿入する

app.MapGet("/", SendGreeting);

ファイルの一番下に次の関数を挿入:

async Task<String> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

Note

エンドポイント定義では、OpenTelemetry に固有のものは一切使用されません。監視のために .NET API を使用します。

4. OpenTelemetry パッケージを参照する

NuGet パッケージマネージャーまたはコマンドラインを使用して、次の NuGet パッケージを追加します。

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
  </ItemGroup>

注意

OTel API は絶えず進化し続けるので、最新バージョンを使用してください。

5. OpenTelemetry と適切なプロバイダーを構成する

builder.Build(); の前に次のコードを挿入:

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

var otel = builder.Services.AddOpenTelemetry();

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();
    //Our custom metrics
    metrics.AddMeter(greeterMeter.Name);
    // Metrics provides by ASP.NET Core in .NET 8
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
});

// Export OpenTelemetry data via OTLP, using env vars for the configuration
var OtlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
if (OtlpEndpoint != null)
{
    otel.UseOtlpExporter();
}

このコードでは、さまざまなテレメトリソースを使用して OpenTelemetry を設定します。

ILogger に OTel プロバイダーを追加してログレコードを収集します。
メトリックを設定し、ASP.NET 用のインストルメンテーションプロバイダーとメーター、およびカスタムメーターを登録します。
トレースを設定し、インストルメンテーションプロバイダーとカスタム ActivitySource を登録します。

その後、構成に env vars を使用して OTLP エクスポーターを登録します。

6. OTLP 環境変数を構成する

OTLP エクスポーターはコード内の API を介して構成できますが、環境変数を介して構成する方が一般的です。次を AppSettings.Development.json に追加

"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "OTLP-Example"

.NET OTLP エクスポーターまたは一般的な OTel 変数 (OTEL_RESOURCE_ATTRIBUTES など) の環境変数を追加して、リソース属性を定義できます。

Note

よくある問題として、AppSettings.json と AppSettings.Development.json を混同することがあります。後者が存在する場合は、Visual Studio から F5 キーを使用するときに使用され、AppSettings.json の設定はすべて無視されます。

7. Aspire Dashboard コンテナーを起動する

Docker を使用して、ダッシュボードコンテナーをダウンロードして実行します。

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

ダッシュボードに表示されるデータは機密性の高いものである場合があります。既定では、ログインにトークンを必要とする認証でダッシュボードが保護されています。コンテナーの実行時に、最終的な出力にトークンが表示されます。

[ Aspire Dashboard ]

表示されている URL をコピーし、0.0.0.0 を localhost に置き換えて (例: http://localhost:18888/login?t=123456780abcdef123456780) ブラウザーで開きます。ログインダイアログが表示されたときに /login?t= の後にキーを貼り付けることもできます。トークンはコンテナーを起動するたびに変化します。

6. プロジェクトを実行する

プロジェクトを実行し、ブラウザーまたは curl を使用して API にアクセスします。

curl -k http://localhost:7275

ページが要求されるたびに、行われたグリーティングの数のためのカウントをインクリメントします。

8.1 ログ出力

コードのログステートメントは、ILogger を使用して出力されます。既定では、出力がコンソールに送信されるようにコンソールプロバイダーが有効になっています。

.NET からログを出力できる方法には、次のようないくつかのオプションがあります。

stdout および stderr 出力は、Kubernetes などのコンテナーシステムによってログファイルにリダイレクトされます。
ILogger と統合されるログライブラリの使用。これには Serilog や NLog が含まれます。
OTLP などの OTel 用ログプロバイダーの使用。ステップ 5 のコードのログセクションでは、OTel プロバイダーが追加されます。

ログは、構造化されたログとしてダッシュボードに表示されます。ログメッセージで設定したプロパティは、ログレコードのフィールドとして抽出されます。

8.2 メトリックの表示

Aspire Dashboard にはリソースごとにメトリックが表示されます (リソースは、プロセスなどのテレメトリのソースについて OTel で話す方法です)。リソースが選択されると、ダッシュボードは、リソースによって OTLP エンドポイントに送信された各メトリックを列挙します。メトリックのリストは状況に応じて変化し、新しいメトリックを受信するたびに更新されます。

メトリックのビューは、使用されているメトリックの種類によって異なります。

カウンターは直接表示されます。
要求ごとに送信された期間やバイト数など、要求ごとの値を追跡するヒストグラムは、一連のバケットにまとめられます。ダッシュボードでは、P50、P90、P99 の各パーセンタイルがグラフ化されます。ヒストグラムの結果には、その要求の trace/spanId と共に、個々のデータポイントである例示を含めることができます。これらはグラフ上にドットとして表示されます。 1 つを選択すると、対応するトレースに移動し、その値になった理由を確認できます。これは外れ値の診断に役立ちます。
メトリックには、個々の値に関連付けられたキーと値のペアであるディメンションを含めることができます。値はディメンションごとに集計されます。ビューのドロップダウンを使用すると、結果をフィルター処理して、 GET 要求のみ、または ASP.NET 内の特定の URL ルートの要求など、特定のディメンションを確認できます。

8.3 トレースの表示

トレースビューにはトレースの一覧が表示されます。各トレースは、同じ traceId を共有するアクティビティのセットです。作業は、作業単位を表すスパンで追跡されます。 ASP.NET 要求を処理すると、スパンが作成されます。 HttpClient 要求の実行はスパンになります。スパンの親を追跡することで、スパンの階層を視覚化できます。各リソース (プロセス) からスパンを収集することで、一連のサービスで発生する作業を追跡します。 Http 要求には、traceId と親 spanId を次のサービスに渡すために使用されるヘッダーがあります。各リソースでテレメトリを収集し、同じコレクターに送信する必要があります。その後、スパンの階層が集計されて表示されます。

ダッシュボードには、概要情報を含むトレースのリストが表示されます。新しい traceId を持つスパンが表示されるたびに、テーブル内の行が割り当てられます。ビューをクリックすると、トレース内のすべてのスパンが表示されます。

スパンを選択すると、ステップ 3 で設定した greeting タグなど、スパン上のプロパティを含む詳細が表示されます。

次の方法で共有