EventSource の使用を開始する
この記事の対象: ✔️ .NET Core 3.1 以降のバージョン ✔️ .NET Framework 4.5 以降のバージョン
このチュートリアルでは、System.Diagnostics.Tracing.EventSource を使用して新しいイベントをログに記録する方法、トレース ファイルにイベントを収集する方法、トレースを表示する方法、EventSource の基本的な概念を理解する方法を示します。
Note
EventSource と統合される多くのテクノロジでは、"ログ記録" や "ログ" の代わりに "トレース" という用語が使用されています。 ここでの意味は同じです。
イベントをログに記録する
EventSource の目的は、.NET 開発者が、イベントをログに記録する次のようなコードを記述できるようにすることです。
DemoEventSource.Log.AppStarted("Hello World!", 12);
このコード行には、ログ オブジェクト (DemoEventSource.Log
)、ログに記録するイベントを表すメソッド (AppStarted
)、強力に型指定されたいくつかの省略可能なイベント パラメーター (HelloWorld!
と 12
) があります。 詳細レベル、イベント ID、メッセージ テンプレート、呼び出しサイトに存在する必要がないその他のものはありません。 イベントに関するその他の情報はすべて、System.Diagnostics.Tracing.EventSource から派生させる新しいクラスを定義することで記述されます。
完全な最小の例を次に示します。
using System.Diagnostics.Tracing;
namespace EventSourceDemo
{
public static class Program
{
public static void Main(string[] args)
{
DemoEventSource.Log.AppStarted("Hello World!", 12);
}
}
[EventSource(Name = "Demo")]
class DemoEventSource : EventSource
{
public static DemoEventSource Log { get; } = new DemoEventSource();
[Event(1)]
public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
}
}
DemoEventSource クラスでは、ログに記録するイベントの型ごとにメソッドを宣言しています。 この場合、"AppStarted" という 1 つのイベントが、AppStarted() メソッドによって定義されています。 イベントが有効になっている場合、コードで AppStarted メソッドが呼び出されるたびに、別の AppStarted イベントがトレースに記録されます。 以下に、各イベントでキャプチャできるデータの一部を示します。
- イベント名 - ログに記録されたイベントの種類を識別する名前。 イベント名は、この場合メソッド名の "AppStarted" と同じになります。
- イベント ID - ログに記録されたイベントの種類を識別する数値 ID。 これは名前と同様の役割を果たしますが、高速で自動化されたログ処理を助けることができます。 AppStarted イベントの ID は 1 で、これは EventAttribute で指定されています。
- ソース名 - イベントが格納されている EventSource の名前。 これは、イベントの名前空間として使用されます。 イベント名と ID は、それらのスコープ内でのみ一意である必要があります。 ここでは、ソースの名前は "Demo" で、クラス定義の EventSourceAttribute で指定されています。 ソース名は、プロバイダー名として参照されることもよくあります。
- 引数 - メソッドのすべての引数値がシリアル化されます。
- その他の情報 - イベントには、タイムスタンプ、スレッド ID、プロセッサ ID、アクティビティ ID、スタック トレース、およびメッセージ テンプレート、詳細レベル、キーワードなどのイベント メタデータも含まれる場合があります。
イベントの作成に関する詳細とベスト プラクティスについては、イベントを作成するためのコードのインストルメント化に関するページを参照してください。
トレース ファイルを収集して表示する
どのイベントを有効にする必要があるか、ログに記録されたデータをどこに送信する必要があるか、データはどの形式で格納する必要があるかを記述する必須の構成は、コード内にありません。 アプリを実行すると、既定では、どのようなトレース ファイルも生成されません。 EventSource では、発行-サブスクライブ パターンを使います。これは、サブスクライバーが、有効にする必要があるイベントを指定し、サブスクライブされているイベントのすべてのシリアル化を制御する必要があります。 EventSource は、Event Tracing for Windows (ETW) や EventPipe (.NET Core のみ) からサブスクライブするための統合を備えています。 カスタム サブスクライバーは、System.Diagnostics.Tracing.EventListener API を使用して作成することもできます。
このデモは、.NET Core アプリ用の EventPipe の例を示しています。 より多くのオプションについて確認するには、イベント トレースの収集と表示に関するページを参照してください。 EventPipe は、.NET 開発者にトレース収集ツールと移植可能で小型のトレース形式 (*.nettrace ファイル) を提供するために .NET Core ランタイムに組み込まれている、オープンでクロス プラットフォームのトレース テクノロジです。 dotnet-trace は、EventPipe トレースを収集するコマンド ライン ツールです。
- dotnet-trace をダウンロードしてインストールする
- 上記のコンソール アプリをビルドします。 このデモは、アプリの名前が EventSourceDemo.exe で、現在のディレクトリ内に置かれていると想定しています。 コマンド ラインで次を実行します。
>dotnet-trace collect --providers Demo -- EventSourceDemo.exe
次のような出力が表示されます。
Provider Name Keywords Level Enabled By
Demo 0xFFFFFFFFFFFFFFFF Verbose(5) --providers
Launching: EventSourceDemo.exe
Process : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
Output File : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220303_001619.nettrace
[00:00:00:00] Recording trace 0.00 (B)
Press <Enter> or <Ctrl+C> to exit...
Trace completed.
このコマンドでは、"Demo" EventSource のすべてのイベントを有効にして EventSourceDemo.exe を実行し、トレース ファイル EventSourceDemo.exe_20220303_001619.nettrace
を出力しました。
Visual Studio でファイルを開くと、ログに記録されたイベントが表示されます。
リスト ビューでは、最初のイベントが Demo/AppStarted イベントであることを確認できます。 テキスト列には保存された引数があります。タイムスタンプ列では、ログの開始から 27 ms 後にイベントが発生したことが示されていて、右側で呼び出し履歴を確認できます。 その他のイベントは、dotnet-trace によって収集されたすべてのトレースで自動的に有効になっていますが、煩わしい場合は、無視して UI のビューからフィルターで除外できます。 それらの追加のイベントには、プロセスと JIT コードに関するいくつかの情報がキャプチャされていて、Visual Studio でイベント スタック トレースを再構築できるようになっています。
EventSource の詳細情報
.NET