次の方法で共有

EventSource の概要

  • [アーティクル]

この記事は、✔️.NET Framework 4.5 以降のバージョン ✔️ .NET Core 3.1 以降のバージョン 適用されます

このチュートリアルでは、System.Diagnostics.Tracing.EventSourceを使用して新しいイベントをログに記録する方法、トレース ファイル内のイベントを収集する方法、トレースを表示する方法、および EventSource の基本的な概念を理解する方法について説明します。

手記

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 では、Publish-subscribe パターンを使用します。このパターンでは、サブスクライバーは、有効にする必要があるイベントを示し、サブスクライブされたイベントのすべてのシリアル化を制御する必要があります。 EventSource には、Event Tracing for Windows (ETW) と EventPipe (.NET Core のみ) からサブスクライブするための統合があります。 カスタム サブスクライバーは、System.Diagnostics.Tracing.EventListener API を使用して作成することもできます。

このデモでは、EventPipe .NET Core アプリの例を示します。 その他のオプションについては、「イベント トレースの収集と表示を参照してください。 EventPipe は、.NET Core ランタイムに組み込まれているオープンでクロスプラットフォームのトレース テクノロジであり、.NET 開発者はトレース収集ツールとポータブル コンパクト トレース形式 (*.nettrace ファイル) を提供します。 dotnet-trace は、EventPipe トレースを収集するコマンド ライン ツールです。

  1. dotnet-trace ダウンロードしてインストールします。
  2. 上記のコンソール アプリをビルドします。 このデモでは、アプリの名前が 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 でファイルを開くと、ログに記録されたイベントが表示されます。

Visual Studio nettrace ファイルのする

リスト ビューでは、最初のイベントが Demo/AppStarted イベントであることを確認できます。 テキスト列には保存された引数があります。タイムスタンプ列は、ログ記録が開始されてから 27 ミリ秒後にイベントが発生したことを示し、右側に呼び出し履歴を表示できます。 他のイベントは、dotnet-trace によって収集されるすべてのトレースで自動的に有効になりますが、気が散る場合は、それらを無視したり、UI の表示からフィルターで取り除いたりすることができます。 これらの追加イベントは、プロセスと jitted コードに関するいくつかの情報をキャプチャします。これにより、Visual Studio でイベント スタック トレースを再構築できます。

EventSource の詳細