参加者の追跡

2025-06-22

追跡参加要素は、ワークフロー開発者が TrackingRecord オブジェクトにアクセスして処理できるようにする拡張ポイントです。 .NET Framework 4.6.1 には、Windows イベントトレーシング (ETW) イベントとして追跡レコードを書き込む標準の追跡参加要素が含まれています。要件を満たしていない場合は、カスタム追跡参加要素を作成することもできます。

参加者の追跡

追跡インフラストラクチャでは、参加者がレコードのサブセットをサブスクライブできるように、送信追跡レコードにフィルターを適用できます。フィルターを適用するメカニズムは、追跡プロファイルを使用します。

.NET Framework 4.6.1 の Windows Workflow Foundation (WF) は、追跡レコードを ETW セッションに書き込む追跡参加要素を提供します。参加要素は、構成ファイルに追跡固有の動作を追加することによって、ワークフローサービスで構成されます。 ETW 追跡参加要素を有効にすると、追跡レコードをイベントビューアーで表示できます。 ETW ベースの追跡用 SDK サンプルは、ETW ベースの追跡参加要素を使用して WF 追跡を理解するのに適した方法です。

ETW 追跡参加者

.NET Framework 4.6.1 には、ETW セッションに追跡レコードを書き込む ETW 追跡参加要素が含まれています。これは、アプリケーションのパフォーマンスやサーバーのスループットへの影響を最小限に抑えながら、非常に効率的な方法で行われます。標準の ETW 追跡参加要素を使用する利点は、受信した追跡レコードを Windows イベントビューアーの他のアプリケーションログとシステムログで表示できることです。

標準の ETW 追跡参加要素は、次の例に示すように、Web.config ファイルで構成されます。

<configuration>
  <system.web>
    <compilation debug="true" targetFramework="4.0" />
  </system.web>
  <system.serviceModel>
    <behaviors>
      <serviceBehaviors>
        <behavior>
          <etwTracking profileName="Sample Tracking Profile"/>
        </behavior>
      </serviceBehaviors>
    </behaviors>
   <tracking>
      <profiles>
        <trackingProfile name="Sample Tracking Profile">
        ….
       </trackingProfile>
      </profiles>
    </tracking>
  </system.serviceModel>
</configuration>

注

<etwTracking/>や<etwTracking profileName=""/>など、trackingProfile名が指定されていない場合は、Machine.config ファイルに .NET Framework 4.6.1 と共にインストールされた既定の追跡プロファイルが使用されます。

Machine.config ファイルでは、既定の追跡プロファイルはワークフローインスタンスのレコードとエラーをサブスクライブします。

ETW では、イベントはプロバイダー ID を介して ETW セッションに書き込まれます。 ETW 追跡参加要素が追跡レコードを ETW に書き込む際に使用するプロバイダー ID は、Web.config ファイルの診断セクション ( <system.serviceModel><diagnostics> の下) で定義されます。既定では、ETW 追跡参加要素は、次の例に示すように、既定のプロバイダー ID が指定されていない場合に使用します。

<system.serviceModel>
        <diagnostics etwProviderId="52A3165D-4AD9-405C-B1E8-7D9A257EAC9F" />

次の図は、ETW 追跡参加要素を介した追跡データのフローを示しています。追跡データが ETW セッションに到達すると、さまざまな方法でアクセスできます。これらのイベントにアクセスする最も便利な方法の 1 つは、アプリケーションやサービスからのログとトレースを表示するために使用される一般的な Windows ツールであるイベントビューアーを使用することです。

ETW 追跡プロバイダーを介した追跡データのフロー。

参加者イベントデータの追跡

追跡参加要素は、追跡レコードごとに 1 つのイベントの形式で、追跡対象のイベントデータを ETW セッションにシリアル化します。イベントは、100 ~ 199 の範囲内の ID を使用して識別されます。追跡参加要素によって出力される追跡イベントレコードの定義については、「追跡イベントリファレンス」トピックを参照してください。

ETW イベントのサイズは、ETW バッファーサイズ、または ETW イベントの最大ペイロードのいずれか小さい方の値によって制限されます。イベントのサイズがこれらの ETW の制限のいずれかを超えた場合、イベントは切り捨てられ、その内容は任意の方法で削除されます。変数、引数、注釈、およびカスタムデータは選択的に削除されません。切り捨ての場合、イベントサイズが ETW 制限を超える原因となった値に関係なく、これらのすべてが切り捨てられます。削除されたデータは、 <item>..<item>に置き換えられます。

変数、引数、およびカスタムデータ項目の複合型は、 NetDataContractSerializer クラスを使用して ETW イベントレコードにシリアル化されます。このクラスには、シリアル化された XML Steam に CLR 型の情報が含まれます。

ETW 制限によるペイロードデータの切り捨てにより、重複する追跡レコードが ETW セッションに送信される可能性があります。これは、複数のセッションがイベントをリッスンしていて、セッションのペイロード制限が異なる場合に発生する可能性があります。

下限のセッションでは、イベントが切り捨てられる可能性があります。 ETW 追跡参加要素には、イベントをリッスンしているセッションの数に関する知識がありません。セッションのイベントが切り捨てられた場合、ETW 参加者はイベントの送信を 1 回再試行します。この場合、より大きなペイロードサイズを受け入れるように構成されたセッションは、イベントを 2 回取得します (切り捨ておよび切り捨てされていないイベント)。すべての ETW セッションを同じバッファーサイズ制限で構成することで、重複を防ぐことができます。

イベントビューアーでの ETW 参加者からの追跡データへのアクセス

ETW 追跡参加要素によって ETW セッションに書き込まれるイベントには、イベントビューアーを介してアクセスできます (既定のプロバイダー ID を使用する場合)。これにより、ワークフローによって出力された追跡レコードをすばやく表示できます。

注

ETW セッションに出力されるレコードイベントの追跡では、100 から 199 の範囲のイベント ID が使用されます。

イベントビューアーで追跡レコードの表示を有効にするには

イベントビューアーを起動する (EVENTVWR.EXE)
[イベントビューアー]、[アプリケーションとサービスログ]、[Microsoft]、[Windows]、[Application Server-Applications] の順に選択します。
右クリックし、[ 分析ログの表示]、[デバッグログ] が選択されていることを確認します。そうでない場合は、チェックマークが横に表示されるように選択します。分析ログ、パフォーマンス ログ、デバッグ ログが表示されます。
分析ログを右クリックし、[ログの有効化] を選択します。ログは、%SystemRoot%\System32\Winevt\Logs\Microsoft-Windows-Application Server-Applications%4Analytic.etl ファイルに存在します。

カスタム追跡参加者

追跡参加要素 API を使用すると、ワークフローランタイムによって出力された追跡レコードを処理するカスタムロジックを含めることができる、ユーザー指定の追跡参加要素を使用して追跡ランタイムを拡張できます。カスタム追跡参加要素を記述するには、開発者は TrackingParticipant クラスに Track メソッドを実装する必要があります。このメソッドは、ワークフローランタイムによって追跡レコードが生成されるときに呼び出されます。

追跡参加者は、 TrackingParticipant クラスから派生します。システム提供の EtwTrackingParticipant は、受信した追跡レコードごとに Windows イベント追跡 (ETW) イベントを生成します。カスタム追跡参加要素を作成するには、 TrackingParticipantから派生するクラスが作成されます。基本的な追跡機能を提供するには、 Trackをオーバーライドします。 Track は、追跡レコードがランタイムによって送信されたときに呼び出され、必要な方法で処理できます。次の例では、すべての追跡レコードをコンソールウィンドウに出力するカスタム追跡参加要素クラスが定義されています。 BeginTrackメソッドとEndTrackメソッドを使用して追跡レコードを非同期的に処理するTrackingParticipant オブジェクトを実装することもできます。

class ConsoleTrackingParticipant : TrackingParticipant
{
    protected override void Track(TrackingRecord record, TimeSpan timeout)
    {
        if (record != null)
        {
            Console.WriteLine("=================================");
            Console.WriteLine(record);
        }
    }
}

特定の追跡参加要素を使用するには、次の例に示すように、追跡するワークフローインスタンスに登録します。

myInstance.Extensions.Add(new ConsoleTrackingParticipant());

次の例では、WriteLine アクティビティを含むSequence アクティビティで構成されるワークフローが作成されます。 ConsoleTrackingParticipantが拡張機能に追加され、ワークフローが呼び出されます。

Activity activity= new Sequence()
{
    Activities =
    {
        new WriteLine()
        {
            Text = "Hello World."
        }
    }
};

WorkflowApplication instance = new WorkflowApplication(activity);

instance.Extensions.Add(new ConsoleTrackingParticipant());
  instance.Completed = delegate(WorkflowApplicationCompletedEventArgs e)
            {
                Console.WriteLine("workflow instance completed, Id = " + instance.Id);
                resetEvent.Set();
            };
            instance.Run();
            Console.ReadLine();

次の方法で共有

参加者の追跡