EventSource トレースの収集と表示
この記事の対象: ✔️ .NET Core 3.1 以降のバージョン ✔️ .NET Framework 4.5 以降のバージョン
概要ガイドでは、最小限の EventSource を作成し、トレース ファイルでイベントを収集する方法を示しました。 このチュートリアルでは、トレースで収集されるイベントをさまざまなツールで構成し、トレースを表示する方法について説明します。
サンプル アプリ
このチュートリアル用のイベントを生成する次のサンプル アプリを使用します。 次のコードを含む .NET コンソール アプリケーションをコンパイルします。
using System.Diagnostics.Tracing;
namespace EventSourceDemo
{
public static class Program
{
public static void Main(string[] args)
{
DemoEventSource.Log.AppStarted("Hello World!", 12);
DemoEventSource.Log.DebugMessage("Got here");
DemoEventSource.Log.DebugMessage("finishing startup");
DemoEventSource.Log.RequestStart(3);
DemoEventSource.Log.RequestStop(3);
}
}
[EventSource(Name = "Demo")]
class DemoEventSource : EventSource
{
public static DemoEventSource Log { get; } = new DemoEventSource();
[Event(1, Keywords = Keywords.Startup)]
public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
[Event(2, Keywords = Keywords.Requests)]
public void RequestStart(int requestId) => WriteEvent(2, requestId);
[Event(3, Keywords = Keywords.Requests)]
public void RequestStop(int requestId) => WriteEvent(3, requestId);
[Event(4, Keywords = Keywords.Startup, Level = EventLevel.Verbose)]
public void DebugMessage(string message) => WriteEvent(4, message);
public class Keywords
{
public const EventKeywords Startup = (EventKeywords)0x0001;
public const EventKeywords Requests = (EventKeywords)0x0002;
}
}
}
収集するイベントを構成する
ほとんどのイベント収集ツールでは、次の構成オプションを使用して、トレースに含めるイベントを決定します。
- プロバイダー名 - 1 つ以上の EventSource 名のリストです。 このリストの EventSource で定義されているイベントのみを含めることができます。 前のサンプル アプリの DemoEventSource クラスからイベントを収集するには、プロバイダー名のリストに EventSource 名 "Demo" を含める必要があります。
- イベント詳細レベル - プロバイダーごとに詳細レベルを定義でき、そのレベルより詳細度が高いイベントはトレースから除外されます。 前のサンプル アプリの "Demo" プロバイダーは Informational 詳細レベルで収集する必要があることを指定した場合、DebugMessage イベントはレベルが高いため除外されます。 EventLevel LogAlways(0) を指定することは、どの詳細レベルのイベントも含める必要があるということを示す特殊なケースです。
- イベント キーワード - プロバイダーごとにキーワードのセットを定義でき、少なくとも 1 つのキーワードでタグ付けされたイベントのみが含められます。 上記のサンプル アプリでは、Startup キーワードを指定した場合は、AppStarted イベントと DebugMessage イベントのみが含められます。 キーワードを指定しない場合、これは特殊なケースであり、キーワードが何であってもイベントを含める必要があることを意味します。
プロバイダー構成を記述するための規則
トレース構成を設定するためのユーザー インターフェイスはツールごとに異なりますが、構成をテキスト文字列として指定するときに多くのツールで使用される一般的な規則があります。 プロバイダーのリストはセミコロンで区切ったリストとして指定し、リスト内の各プロバイダー要素は、名前、キーワード、レベルをコロンで区切った構成にします。 たとえば、"Demo:3:5" は、キーワード ビットマスクが 3 (Startup ビットと Requests ビット)、Verbose が EventLevel 5 で、"Demo" という名前の EventSource を示します。 多くのツールでは、レベルやキーワードのフィルター処理が必要なければ、レベルやキーワードを省略することもできます。 たとえば、"Demo::5" の場合はレベルベースのフィルター処理のみが行われ、"Demo:3" の場合はキーワードベースのフィルター処理のみが行われ、"Demo" の場合はキーワードまたはレベルのフィルター処理は行われません。
Visual Studio
Visual Studio プロファイラーは、トレースの収集と表示の両方をサポートしています。 dotnet-trace などの他のツールによって事前に収集されたトレースを表示することもできます。
トレースを収集する
Visual Studio のプロファイリング ツールのほとんどは、CPU 使用率や割り当ての分析など、特定の目的にかなう定義済みのイベント セットを使用します。 カスタマイズされたイベントを含むトレースを収集するには、イベント ビューアー ツールを使用します。
Visual Studio でパフォーマンス プロファイラーを開くには、Alt+F2 キーを押します。
[イベント ビューアー] チェック ボックスをオンにします。
イベント ビューアーの右側にある小さな歯車アイコンを選択して、構成ウィンドウを開きます。
次の表の [追加プロバイダー] で、[有効] チェック ボックスをクリックし、プロバイダー名、キーワード、レベルを入力して、構成するプロバイダーごとに行を追加します。 プロバイダー GUID を入力する必要はありません。自動的に計算されます。
[OK] を選択して構成設定を確認します。
[開始] を選択して、アプリの実行とログの収集を開始します。
[収集を停止] を選択するかアプリを終了してログの収集を停止し、収集されたデータを表示します。
トレースを表示する
Visual Studio は、自身が収集したトレースを表示することも、他のツールで収集されたトレースを表示することもできます。 他のツールからのトレースを表示するには、[ファイル]>[開く] を使用し、ファイル ピッカーでトレース ファイルを選択します。 Visual Studio プロファイラーは、.etl ファイル (ETW の標準形式)、.nettrace ファイル (EventPipe の標準形式)、.diagsession ファイル (Visual Studio の標準形式) をサポートしています。 Visual Studio でのトレース ファイルの使用の詳細については、Visual Studio ドキュメントを参照してください。
Note
Visual Studio は、明示的に構成されていなくても、ETW または EventPipe から一部のイベントを自動的に収集します。 [プロバイダー名] 列または [イベント名] 列にわからないイベントが表示される場合、それらをフィルターで除外するには、右側のフィルター アイコンを使用して、表示するイベントのみを選択します。
PerfView
PerfView は、.NET チームによって作成されたパフォーマンス ツールであり、ETW トレースを収集して表示できます。 また、他のツールによって収集されたさまざまな形式のトレース ファイルを表示することもできます。 このチュートリアルでは、デモ アプリ の ETW トレースを収集し、収集されたイベントを PerfView のイベント ビューアーで調べます。
トレースを収集する
リリース ページから PerfView をダウンロードします。 このチュートリアルは PerfView バージョン 2.0.76 を使用して行われましたが、最新バージョンも使用できるはずです。
管理者のアクセス許可で PerfView.exe を開始します。
Note
ETW トレース収集には常に管理者のアクセス許可が必要ですが、PerfView を使用して既存のトレースを表示するだけの場合、特別なアクセス許可は必要ありません。
[収集] メニューの [実行] を選択します。 これにより、デモ アプリへのパスを入力する新しいダイアログが開きます。
収集するイベントを構成するには、ダイアログの下部にある [詳細オプション] を展開します。 [追加プロバイダー] テキスト ボックスに、前述の標準的なテキスト形式を使用してプロバイダーを入力します。 ここでは、「Demo:1:4」と入力します。これは、キーワード ビットが 1 (
Startupイベント) で詳細度が 4 (Informational) であることを意味します。
アプリを起動してトレースの収集を開始するには、[コマンドの実行] ボタンを選択します。 アプリが終了すると、現在のディレクトリにトレース PerfViewData.etl が保存されます。
トレースを表示する
左上のメイン ウィンドウ ドロップダウン テキスト ボックスで、トレース ファイルを含むディレクトリを選択します。 次に、下のツリー ビューでトレース ファイルをダブルクリックします。
イベント ビューアーを表示するには、トレース ファイルの下のツリー ビューに表示される [イベント] 項目をダブルクリックします。
トレース内のすべてのイベントの種類が左側の一覧に表示されます。 Demo\AppStarted などのイベントの種類をダブルクリックすると、その種類のすべてのイベントが右側の表に表示されます。
詳細情報
PerfView の使用に関する詳細については、PerfView のビデオ チュートリアルを参照してください。
dotnet-トレース
dotnet-trace は、EventPipe トレースを使用して .NET Core アプリからトレースを収集できるクロスプラットフォームのコマンド ライン ツールです。 トレース データの表示はサポートしていませんが、収集したトレースは PerfView や Visual Studio などの他のツールで表示できます。 dotnet-trace は、既定の .nettrace 形式のトレースを Chromium や Speedscope などの他の形式に変換することもサポートしています。
トレースを収集する
dotnet-trace をダウンロードしてインストールします。
コマンド ラインで、dotnet-trace collect コマンドを実行します。
E:\temp\EventSourceDemo\bin\Debug\net6.0>dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe次のような出力が表示されます。
E:\temp\EventSourceDemo\bin\Debug\net6.0> dotnet-trace collect --providers Demo:1:4 -- EventSourceDemo.exe Provider Name Keywords Level Enabled By Demo 0x0000000000000001 Informational(4) --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_20220317_021512.nettrace [00:00:00:00] Recording trace 0.00 (B) Press <Enter> or <Ctrl+C> to exit... Trace completed.dotnet-trace では、
--providers引数でのプロバイダー構成の記述に、従来のテキスト形式を使用します。 dotnet-trace を使用してトレースを取る方法の詳細オプションについては、dotnet-trace のドキュメントを参照してください。
EventListener
System.Diagnostics.Tracing.EventListener はインプロセスから使用できる .NET API であり、System.Diagnostics.Tracing.EventSource によって生成されたイベントのコールバックを受信します。 この API を使用して、カスタム ログ ツールを作成したり、メモリ内のイベントをシリアル化もせずに分析したりすることができます。
EventListener を使用するには、EventListener から得られた種類を宣言し、EnableEvents を呼び出して目的の EventSource からのイベントをサブスクライブし、新しいイベントが入手可能になると必ず呼び出される OnEventWritten をオーバーライドします。 多くの場合、OnEventSourceCreated をオーバーライドすることによって、どの EventSource オブジェクトが存在するかを検出することは有用ですが、これは必須ではありません。 メッセージが受信されるとコンソールに出力される EventListener の実装例を次に示します。
このコードをデモ アプリに追加します。
class ConsoleWriterEventListener : EventListener { protected override void OnEventSourceCreated(EventSource eventSource) { if(eventSource.Name == "Demo") { EnableEvents(eventSource, EventLevel.Informational); } } protected override void OnEventWritten(EventWrittenEventArgs eventData) { Console.WriteLine(eventData.TimeStamp + " " + eventData.EventName); } }新しいリスナーのインスタンスを作成するように
Mainメソッドを変更します。public static void Main(string[] args) { ConsoleWriterEventListener listener = new ConsoleWriterEventListener(); DemoEventSource.Log.AppStarted("Hello World!", 12); DemoEventSource.Log.DebugMessage("Got here"); DemoEventSource.Log.DebugMessage("finishing startup"); DemoEventSource.Log.RequestStart(3); DemoEventSource.Log.RequestStop(3); }アプリをビルドして実行します。 これまでは出力がありませんでしたが、コンソールにイベントが書き込まれるようになりました。
3/24/2022 9:23:35 AM AppStarted 3/24/2022 9:23:35 AM RequestStart 3/24/2022 9:23:35 AM RequestStop
.NET