.NET Framework Agent

• exem-dotnetfw-agentは、.NET Frameworkアプリケーションのトランザクション、SQL、例外、外部呼び出し、パフォーマンス情報を収集してサーバーに送信するエージェントです。

• このエージェントは、アプリケーションコードに別途SDK初期化コードを入れる方式ではなく、CLR Profilerを通じて対象プロセスに自動的に進入する構造を使用します。ここでprofilerは実際の配備及び登録基準でExem.DotNetFw.Profiler.x86.dll、Exem.DotNetFw.Profiler.x64.dllを意味します。インストール後に対象サービスが開始されるとprofilerが自動的にロードされ、ランタイムでモニタリング対象メソッドが実行される際にエージェントメソッドが呼び出されるように接続されます。

• 核心的に見ると、このエージェントは次の2段階で理解できます。

1. プロセス開始時にprofilerが自動的に付着する。
2. その後Exem.DotNetFw.Agentがイベントを受け取りデータを収集してサーバーに送信します。

• Exem.DotNetFw.Agentの実際の開始時点が、最初の有効なモニタリングイベント以降に遅延する場合があります。そのためユーザーの立場では「プロセスにはすでに付着しているが、特定のメソッドが呼び出されて初めて本格的に動作するように」見える場合があり、この部分はjava agentと差異があります。
• 理由はprofilerが付着する時点がagentを直ちに実行するには早すぎるためです。profilerはCLR初期区間で先にロードされますが、この時点ではまだアプリケーションのランタイムコンテキストが完全に形成されていない場合があります。java agentの場合、premain()で直ちに初期化が開始されますが、この時はすでにjavaロジックを実行させることができます。
• したがって、実際のトランザクションや有効なモニタリングイベントが一度発生してagentメソッドが呼び出される際に、Exem.DotNetFw.Agentを初期化するようになっています。

サポート環境​

• Windowsで.NET Framework 4.5以上で動作するASP.NETアプリケーション

一目で見る構造​

.NET Frameworkエージェントは大きく3つの構成要素に分かれます。

• profilerはプロセス開始時に付着し、メソッド実行フローに進入する準備をします。
• Exem.DotNetFw.Agentは実際のデータを作成してサーバーに送ります。

構成要素​

1. Exem.DotNetFw.Service​

インストールと運用制御を担当するWindows Serviceです。

主な役割:

• profiler DLL登録
• 対象サービス一覧のロード
• 対象サービスレジストリへのprofiler環境変数設定
• agent適用/解除時の運用設定反映

2. Exem.DotNet.Profiler​

CLRがロードするprofilerです。実際のDLLはExem.DotNetFw.Profiler.x86.dll、Exem.DotNetFw.Profiler.x64.dllです。

主な役割:

• 対象プロセス開始時にCLR profilerとして進入
• 設定ファイルを読み込みモニタリング対象メソッドを決定
• メソッドIL修正
• メソッドの開始、終了、例外時点でエージェントメソッドが呼び出されるように接続

3. Exem.DotNetFw.Agent​

実際の収集と送信を担当するコンポーネントです。実際のDLLはExem.DotNetFw.Agent.dllです。

主な役割:

• HTTP、SQL、例外、外部呼び出しイベント処理
• Agent ID識別
• 設定ロード及びリロード
• サーバー接続及び送受信
• 周期的な状態/パフォーマンス送信

インストール及び適用手順​

インストール過程は単純なファイルコピーではなく、対象.NET Frameworkサービスが次回起動からprofilerを自動ロードするように運用環境を構成する過程です。

1. エージェントファイル配置​

一般的に次の項目が含まれます。

• Exem.DotNetFw.Agent.dll
• Exem.DotNetFw.Profiler.x86.dll
• Exem.DotNetFw.Profiler.x64.dll
• 設定ファイル(cfg)
• インストールスクリプト及び運用ツール

2. エージェントサービス実行​

Exem.DotNetFw.Serviceが実行されると、agentホームパスを基準に必要なファイルを準備し、profiler登録有無を確認します。

3. profiler DLL登録​

サービスはregsvr32を通じてExem.DotNetFw.Profiler.x86.dll、Exem.DotNetFw.Profiler.x64.dllを登録します。この段階はCLRがprofiler COMオブジェクトを認識するために必要です。

4. 対象サービス指定​

cfg/service.targetファイルにprofilerを適用する対象Windows Service一覧を記録します。

5. profiler環境変数設定​

対象サービスレジストリのEnvironment項目に以下の値を追加します。

• COR_ENABLE_PROFILING
• COR_PROFILER

この設定があってこそ、対象サービスが次回起動時にprofilerを自動ロードします。

6. 対象サービス再起動​

すでに実行中のプロセスには新しい設定が即座に反映されないため、通常は対象サービスの再起動が必要です。

動作原理​

このエージェントの基本原理は以下の通りです。

1. 対象プロセス開始時にprofiler自動付着
2. profilerがメソッドIL修正
3. 修正されたメソッドが実行されるとエージェントメソッド呼び出し
4. Exem.DotNetFw.Agentがイベントを受け取りデータ収集及びサーバー送信

1. profiler自動付着​

対象.NET Frameworkプロセスが開始されると、CLRは環境変数を確認し、登録されたprofiler DLL(Exem.DotNetFw.Profiler.x86.dllまたはExem.DotNetFw.Profiler.x64.dll)をロードします。

2. メソッドIL修正​

profilerは設定ファイル(x.advice、x.advice.callback)を読み込みモニタリング対象メソッドを決定した後、該当メソッドのILを修正します。

この修正の目的は次の通りです。

• メソッド開始時にエージェントメソッド呼び出し
• メソッド終了時にエージェントメソッド呼び出し
• 例外発生時にエージェントメソッド呼び出し

3. agentメソッド呼び出しへの接続​

挿入された呼び出しは、ランタイムでagentメソッドを呼び出す方式で接続されます。この段階でprofilerが検知したメソッド実行イベントがExem.DotNetFw.Agentに伝達されます。

4. Exem.DotNetFw.Agent動作​

agentメソッドが呼び出されると、現在のプロセスが収集対象かどうか、Exem.DotNetFw.Agentを初期化できる状態かどうか、初期設定交換中かどうかなどを確認した後、実際の収集ロジックを実行します。

条件が合えばExem.DotNetFw.Agentが初期化され、この時点から設定ロード、サーバー接続、周期作業の開始が進行されます。

運用時の留意事項​

• 設定反映後、対象サービスの再起動が必要な場合があります。
• プロセス開始直後はprofilerが付着していてもサーバー接続がまだ見えない場合があります。

FAQ​

• Q. アプリケーションコードの修正が必要か?

  • 一般的に直接SDK初期化コードを入れなくても構いません。profilerベースで自動付着されます。

• Q. このエージェントはいつからサーバーにデータを送るのか?

  • 現在の構造上、最初の有効なモニタリングイベント以降にExem.DotNetFw.Agentが開始されながらサーバー接続とデータ送信が本格化する場合があります。

• Q. profilerが付着したことと、agentが直ちに送信を開始することは同じ意味か?

  • いいえ。profilerの付着が先であり、実際のExem.DotNetFw.Agentの開始はそれより遅れる場合があります。

• Q. IIS管理者画面で再起動してはいけない理由は何か?

  • 現在の構造でprofiler関連環境変数はw3wp.exeに直接注入されるのではなく、cfg/service.target対象サービス(WAS、W3SVC)のEnvironmentに記録されます。
  • したがって、IIS管理者画面の再起動が実際にはWAS/W3SVCサービスの再起動ではなく、アプリプールrecycleまたはworker process(w3wp.exe)の再生成レベルでのみ動作する場合、サービスが環境変数を再読み込みせずprofilerが期待通りに付着しない場合があります。
  • つまり、このプロジェクトで重要なのはw3wp.exeだけが再び立ち上がることではなく、profiler環境変数を保有する対象サービスが再起動され、新しいw3wp.exeがその環境を継承することです。
  • 運用中にprofilerの再付着が必要な場合は、単純なアプリプールrecycleよりiisreset、IIS管理者サーバーノードの全体再起動、またはWAS/W3SVCサービスの再起動を優先的に検討することが安全です。