EventPipe

EventPipe は、ETW や perf_events と同様に、トレース データを収集するために使用できるランタイム コンポーネントです。 EventPipe の目的は、.NET 開発者が、ETW や perf_events などのプラットフォーム固有の高権限コンポーネントに依存することなく、簡単に .NET アプリケーションをトレースできるようにすることです。

EventPipe は多くの診断ツールの背後にあるメカニズムです。これを使用することで、ランタイムによって生成されたイベントや、EventSource で記述されたカスタム イベントを利用できます。

この記事では、EventPipe の概要を示します。 EventPipe をどのような場合にどのような方法で使用するか、およびニーズに合わせて最適に構成する方法について説明します。

EventPipe の基本

EventPipe により、ランタイム コンポーネント (たとえば、Just-In-Time コンパイラまたはガベージ コレクター) によって生成されたイベントと、ライブラリおよびユーザー コード内の EventSource インスタンスから書き込まれたイベントが集約されます。

その後、イベントは .nettrace ファイル形式でシリアル化され、ファイルに直接書き込んだり、アウトプロセスで使用するために診断ポートを介してストリーミングしたりできます。

EventPipe のシリアル化形式の詳細については、EventPipe 形式のドキュメントを参照してください。

EventPipe と ETW/perf_events

EventPipe は .NET ランタイムの一部であり、.NET Core でサポートされるすべてのプラットフォームで同じように動作するよう設計されています。 これにより複数のプラットフォーム間で、dotnet-counters、dotnet-gcdump、dotnet-trace などの EventPipe に基づくトレース ツールのシームレスな動作が実現します。

ただし、EventPipe はランタイムの組み込みコンポーネントであるため、そのスコープはマネージド コードとランタイム自体に限定されます。 EventPipe イベントには、マネージド コード フレーム情報のみを含むスタックトレースがあります。 他のアンマネージド ユーザー モード ライブラリ、ネイティブ コードの CPU サンプリング、カーネル イベントからイベントを生成する場合は、ETW や perf_events などの OS 固有のトレース ツールを使用する必要があります。 Linux では、perfcollect ツール が perf_events と LTTng の使用を自動化するのに役立ちます。

EventPipe と、ETW または perf_events とのもう 1 つの大きな違いは、管理者または root の特権の要件です。 ETW または perf_events を使用してアプリケーションをトレースするには、管理者または root である必要があります。 EventPipe を使用すると、トレーサー (dotnet-trace など) が、アプリケーションを起動したユーザーと同じユーザーとして実行されている限り、アプリケーションをトレースできます。

次の表に、EventPipe、ETW、perf_events の違いの概要を示します。

EventPipe を使用して .NET アプリケーションをトレースする

EventPipe を使用すると、さまざまな方法で .NET アプリケーションをトレースできます。

• EventPipe の上に構築された診断ツールのどれかを使用します。

• Microsoft.Diagnostics.NETCore.Client ライブラリを使用して、EventPipe セッションを構成して開始するための独自のツールを作成します。

• 環境変数を使用して EventPipe を開始します。

EventPipe イベントを含む nettrace ファイルを作成した後、PerfView または Visual Studio でそのファイルを表示できます。 Windows 以外のプラットフォームでは、dotnet-trace convert コマンドを使用して nettrace ファイルを speedscope または Chromium トレース形式に変換し、speedscope または Chrome DevTools を使用して表示できます。

TraceEvent を使用してプログラムで EventPipe トレースを分析することもできます。

EventPipe を使用するツール

これは EventPipe を使用してアプリケーションをトレースする最も簡単な方法です。 これらの各ツールの使用方法の詳細については、各ツールのドキュメントを参照してください。

• dotnet-counters を使用すると、.NET ランタイムとコア ライブラリによって生成されるさまざまなメトリックに加えて、自分で作成できるカスタム メトリックを監視および収集することができます。

• dotnet-gcdump を使用すると、アプリケーションのマネージド ヒープを分析するためにライブ プロセスの GC ヒープ ダンプを収集できます。

• dotnet-trace を使用すると、パフォーマンスを分析するためにアプリケーションのトレースを収集できます。

環境変数を使用したトレース

EventPipe を使用する場合の推奨される方法は、dotnet-trace または Microsoft.Diagnostics.NETCore.Client ライブラリを使用することです。

ただし、次の環境変数を使用すると、アプリで EventPipe セッションを設定し、それによってトレースをファイルに直接書き込むことができます。 トレースを停止するには、アプリケーションを終了します。

• DOTNET_EnableEventPipe: ファイルに直接書き込む EventPipe セッションを開始するには、これを 1 に設定します。 既定値は 0 です。

• DOTNET_EventPipeOutputPath: EventPipe が DOTNET_EnableEventPipe を介して実行するように構成されている場合に、その出力となるトレース ファイルへのパス。 既定値は trace.nettrace です。これは、アプリが実行されているのと同じディレクトリに作成されます。

  注意

  .NET 6 以降では、DOTNET_EventPipeOutputPath 内の文字列 {pid} のインスタンスは、トレースされているプロセスのプロセス ID に置き換えられます。

• DOTNET_EventPipeCircularMB: EventPipe の内部バッファーのサイズをメガバイトで表す 16 進数。 この構成値は、EventPipe が DOTNET_EnableEventPipe 経由で実行されるように構成されているときにのみ使用されます。 既定のバッファー サイズは 1024 MB であり、0x400 == 1024 であるため、この環境変数が 400 に設定されることになります。

  注意

  ターゲット プロセスによるイベントの書き込みが頻繁すぎる場合、このバッファーがオーバーフローして、一部のイベントが削除される可能性があります。 削除されるイベントが多すぎる場合は、バッファー サイズを増やし、削除されるイベントの数が減少するかどうかを確認します。 バッファー サイズを大きくしても削除されるイベントの数が減らない場合は、リーダーが遅いために、ターゲット プロセスのバッファーのフラッシュが妨げられている可能性があります。

• DOTNET_EventPipeProcNumbers: これを 1 に設定すると、EventPipe イベント ヘッダーのプロセッサ番号をキャプチャできるようになります。 既定値は 0 です。

• DOTNET_EventPipeConfig: DOTNET_EnableEventPipe を使用して EventPipe セッションを開始するときに、EventPipe セッション構成を設定します。 構文は次のとおりです。

  <provider>:<keyword>:<level>

  コンマで連結することによって複数のプロバイダーを指定することもできます。

  <provider1>:<keyword1>:<level1>,<provider2>:<keyword2>:<level2>

  この環境変数が設定されていないが、EventPipe が DOTNET_EnableEventPipe によって有効になる場合は、次に示すキーワードとレベルを使用して次のプロバイダーを有効にすることでトレースが開始されます。

  • Microsoft-Windows-DotNETRuntime:4c14fccbd:5
  • Microsoft-Windows-DotNETRuntimePrivate:4002000b:5
  • Microsoft-DotNETCore-SampleProfiler:0:5

  .NET でのいくつかの既知のプロバイダーの詳細については、既知のイベント プロバイダーに関するページを参照してください。