OpenTelemetry を使用した .NET の監視
アプリケーションを実行するときは、アプリのパフォーマンスを把握し、潜在的な問題を大きくなる前に検出する必要があります。 これを行うには、アプリからログやメトリックなどのテレメトリ データを出力し、そのデータを監視して分析します。
可観測性とは
分散システムのコンテキストでの監視とは、各コンポーネントの状態に関するテレメトリを監視および分析し、パフォーマンスの変化を監視し、それらの変化が発生した理由を診断する機能のことです。 侵入性があり、アプリケーションの動作に影響を与える可能性があるデバッグとは異なり、監視はプライマリ操作に対して透過的であり、パフォーマンスへの影響が継続的に使用できる程度に十分小さくなるように意図したものです。
監視は、一般的に次の組み合わせを使用して行われます。
- ログ:受信要求、特定のコンポーネントでのエラー、注文などの個々の操作を記録します。
- メトリック:完了した要求の数、アクティブな要求、販売されたウィジェット、要求の待機時間のヒストグラムなどのカウンターとゲージを測定します。
- 分散トレース:分散システム内のコンポーネント間の要求とアクティビティを追跡して、時間が費やされた場所を確認し、特定の障害を追跡できるようにします。
一緒に、ログ、メトリック、分散トレースは、監視の 3番目の柱として知られています。
各柱には、次に示すものからのテレメトリ データが含まれている可能性があります。
- ガベージ コレクターや JIT コンパイラなどの .NET ランタイム。
- Kestrel (ASP.NET Web サーバー) や
HttpClientなどのライブラリ。 - 自分のコードによって出力されるアプリケーション固有のテレメトリ。
.NET における監視方法
.NET アプリケーションで監視を実現するには、次のようないくつかの異なる方法があります。
- OpenTelemetry などのライブラリを参照して使用する明示的なコード。 ソース コードにアクセスでき、アプリを再ビルドできる場合は、これが最も強力で構成しやすいメカニズムです。
- EventPipe を使用したアウトプロセス。 dotnet-monitor などのツールは、ログとメトリックをリッスンした後に、どんなコードにも影響を与えずにそれらを処理できます。
- スタートアップ フックを使用すると、アセンブリをプロセスに挿入でき、それによってインストルメンテーションを収集できます。 この方法の例が OpenTelemetry .NET 自動インストルメンテーションです。
OpenTelemetry とは何ですか?
OpenTelemetry (OTel) は、テレメトリ データの収集と出力のためのクロスプラットフォームのオープンソース標準です。 OpenTelemetry には次のものが含まれます。
- コードの実行中にテレメトリ データを記録するために使用するライブラリの API。
- アプリ開発者が記録されたデータのどの部分をネットワーク経由で送信するか、それをどこに送信するか、およびそれをどのようにフィルター処理、バッファリング、エンリッチ、変換するかを構成するために使用できる API。
- セマンティック規則は、テレメトリ データの名前付けとコンテンツに関するガイダンスを提供します。 テレメトリ データを生成するアプリと、データを受け取るツールが、ツールが効果的な分析を提供できるように、さまざまな種類のデータの意味と役立つデータの種類について合意することが重要です。
- エクスポーターのインターフェイス。 エクスポーターは、テレメトリ データを特定の形式でさまざまなテレメトリ バックエンドに送信できるようにするプラグインです。
- OTLP ワイヤ プロトコルは、テレメトリ データ送信用のベンダーに依存しないネットワーク プロトコル オプションです。 一部のツールとベンダーは、既存の専用プロトコルに加えて、このプロトコルをサポートしています。
OTel を使用すると、Prometheus や Grafana などのオープンソース システム、Azure Monitor (Microsoft の Azure における APM 製品)、あるいは OpenTelemetry と提携する多くの APM ベンダーの製品など、さまざまな APM システムを使用できます。
.NET を含むほとんどの言語とプラットフォームには、OpenTelemetry の実装があります。
OpenTelemetry の .NET 実装
.NET はフレームワーク内でログ、メトリック、アクティビティ API を提供するため、.NET の OpenTelemetry 実装は他のプラットフォームとは少し異なります。 これは OTel はライブラリ作成者が使用する API を提供する必要がないことを意味します。 .NET の OTel 実装は、インストルメンテーションのために次のプラットフォーム API を使用します。
- ログ記録用の Microsoft.Extensions.Logging.ILogger<TCategoryName>
- メトリック用の System.Diagnostics.Metrics.Meter
- 分散トレース用の System.Diagnostics.ActivitySource と System.Diagnostics.Activity
OTel の働きは、それらの API やその他のソースから (インストルメンテーション ライブラリを介して) テレメトリを収集し、保存と分析のためにアプリケーション パフォーマンス監視 (APM) システムにエクスポートすることです。 OTel が業界標準としてもたらす利点は、収集のための一般的なメカニズム、テレメトリ データのための一般的なスキーマとセマンティクス、および APM がどのように OTel と統合できるかを決める API です。 OTel を使用すると、アプリケーションは APM 固有の API やデータ構造を使用する必要がなく、OTel 標準に基づいて動作します。 APM は、APM 固有のエクスポーター コンポーネントを実装することも、APM システムにテレメトリ データをエクスポートするための新しいワイヤ標準である OTLP を使用することもできます。
OpenTelemetry パッケージ
.NET の OpenTelemetry は、次に示すいくつかのカテゴリを形成する一連の NuGet パッケージとして実装されています。
- Core API
- インストルメンテーション - これらのパッケージは、ランタイムおよび共通ライブラリからインストルメンテーションを収集します。
- エクスポーター - これらは、Prometheus、Jaeger、OTLP などの APM システムとインターフェイス接続します。
次の表は、主要なパッケージを示します。
| パッケージ名 | 説明 |
|---|---|
| OpenTelemetry | コア OTEL 機能を提供するメイン ライブラリ |
| OpenTelemetry.Instrumentation.AspNetCore | ASP.NET Core と Kestrel のインストルメンテーション |
| OpenTelemetry.Instrumentation.GrpcNetClient | 送信 gRPC 呼び出しを追跡するための gRPC クライアントのインストルメンテーション |
| OpenTelemetry.Instrumentation.Http | 送信 HTTP 呼び出しを追跡するための HttpClient および HttpWebRequest のインストルメンテーション |
| OpenTelemetry.Instrumentation.SqlClient | データベース操作をトレースするために使用される SqlClient のインストルメンテーション |
| OpenTelemetry.Exporter.Console | コンソールのエクスポーターで、一般的にどのテレメトリがエクスポートされているかを診断するために使用されます |
| OpenTelemetry.Exporter.OpenTelemetryProtocol | OTLP プロトコルを使用したエクスポーター |
| OpenTelemetry.Exporter.Prometheus.AspNetCore | ASP.NET Core エンドポイントを使用して実装された Prometheus のエクスポーター |
| OpenTelemetry.Exporter.Zipkin | Zipkin トレースのエクスポーター |
例
このトピックは、.NET で OpenTelemetry を使用するためのいくつかのチュートリアル例で続きます。
- 例: OTLP とスタンドアロンのアスパイア ダッシュボードを使用する
- 例: Azure Monitor と Application Insights で OpenTelemetry を使用する
- 例: Prometheus、Grafana、Jaeger で OpenTelemetry を使用する
.NET アスパイアの OpenTelemetry
.NET Aspire は、分散アプリケーションを簡単に作成して操作できるようにするための .NET の拡張機能のセットです。 .NET Aspire を使用する利点の 1 つは、.NET 用の OpenTelemetry ライブラリを使用してテレメトリが組み込まれている点です。 .NET Aspire の既定のプロジェクト テンプレートには ServiceDefaults プロジェクトが含まれており、その一部は OTel のセットアップと構成です。 Service Defaults プロジェクトは、.NET Aspire ソリューション内の各サービスによって参照および初期化されます。
Service Defaults プロジェクト テンプレートには、OTel SDK、ASP.NET、HttpClient、ランタイム インストルメンテーション パッケージが含まれており、これらは Extensions.cs ファイルで構成されます。 テレメトリをエクスポートする場合、.NET Aspire には既定で OTLP エクスポーターが含まれているため、アスパイア ダッシュボードを使用してテレメトリの視覚化を提供できます。
アスパイア ダッシュボードは、テレメトリの監視をローカル デバッグ サイクルに取り込むよう設計されています。これにより、開発者は、アプリケーションがテレメトリを生成していることを確認できるだけでなく、そのテレメトリを使用してそれらのアプリケーションをローカルで診断することもできます。 サービス間の呼び出しを観察できることは、運用環境と同じようにデバッグ時に役立つことを証明しています。 Visual Studio から AppHost プロジェクトを F5 にするか、AppHost プロジェクトをdotnet runすると、.NET アスパイア ダッシュボードが自動的に起動します。
.NET のアスパイアの詳細については、次を参照してください。
.NET のアスパイア オーケストレーションを使用せずにサービスの既定のプロジェクトを再利用する
ASP.NET プロジェクトに対して OTel を構成する最も簡単な方法は、オーケストレーションに AppHost などの .NET Aspire の残りの部分を使用しない場合でも、サービスの既定値を使用することです。 Service Defaults プロジェクトは、Visual Studio または dotnet new を使用してプロジェクト テンプレートとして使用できます。 OTel を構成し、OTLP エクスポーターを設定します。 その後、 OTel 環境変数を使用して テレメトリを送信するように OTLP エンドポイントを構成し、アプリケーションのリソース プロパティを指定できます。
.NET Aspire の外部で ServiceDefaults を使用する手順は次のとおりです。
- Visual Studio で [新しいプロジェクトの追加] を使用して ServiceDefaults プロジェクトをソリューションに追加するか、
dotnet new aspire-servicedefaults --output ServiceDefaults - ASP.NET アプリケーションから ServiceDefaults プロジェクトを参照します。 Visual Studio で "-> プロジェクト参照の追加" を使用し、 ServiceDefaults プロジェクトを選択します。
- アプリケーション ビルダーの初期化の一部として、OpenTelemetry セットアップ関数を呼び出します。
var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
サービスの既定値では、 AddServiceDefaults() または特定の機能を使用して必要に応じて、次の追加機能を設定できます。
/healthエンドポイントと/aliveエンドポイントを使用した正常性チェック- .NET の残りの部分が不要なサービス検出
- エラーが発生した場合に要求を再試行する HttpClient の回復性の構成
.NET