EventSource の使用を開始する

[アーティクル]
04/08/2023

この記事の対象: ✔️ .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 の使用を開始する

イベントをログに記録する

トレースファイルを収集して表示する

EventSource の詳細情報

フィードバック

その他のリソース

次の方法で共有

EventSource の使用を開始する

イベントをログに記録する

トレース ファイルを収集して表示する

EventSource の詳細情報

フィードバック

その他のリソース

トレースファイルを収集して表示する