エージェント(.NET)のインストール及び構成

この章ではエージェント(.NET)のインストール方法を説明します。

エージェント(.NET)の対応環境

対応OS

エージェント（.NET）を正常にインストールできるOSは次の通りです。

クライアント向けWindowsの場合、エージェント（.NET）はWindows XP SP3以上でも動作しますが、公式のサポートは上記OSでのみ提供します。

エージェントのインストールとアンインストール

一般サーバとクラウドの単独仮想マシン環境

エージェントのインストール

jennifer-agent-dotnet-[version].zipファイルを解凍すると、Installer.exeとInstaller.exe.configファイルが作成されます。Installer.exeファイルを実行すると、bin、config、logsおよびutilityディレクトリが作成され、プログラムの登録が完了します。

エージェント(.NET)のインストーラのディレクトリの説明

ディレクトリ

説明

bin

エージェント実行ファイルが存在するディレクトリ

config

エージェントが適用されているアプリケーション用の構成および設定ファイルを保存するためのディレクトリ

extension

拡張アダプターが保存されるディレクトリ

logs

エージェントログファイルを保存するディレクトリ

service_dump

サービスダンプファイルを保存するディレクトリ

utility

ユーティリティファイルが存在するディレクトリ

プログラムが正常に登録された後、監視対象のアプリケーションを決定し、エージェント(.NET)を実行するための構成ファイルを作成します。この操作に関する詳しい情報については エージェント構成ファイルの設定 を参照してください。

エージェントのアンインストール

エージェントをアンインストールする２つの方法を説明します。１つはInstall.exeを"/u"パラメータで実行する方法です。もう1つはInstall.exeと同じパスにあるuninstall.batを実行する方法です。

D:¥work¥jennifer5¥agnet.net> Installer.exe /u
または
D:¥work¥jennifer5¥agent.net> uninstall.bat

コマンド実行後、監視対象のプロセスを再起動します。（例、iisreset）

エージェント(.NET)がインストールされているディレクトリはエージェントの使用がすべてのプロセスから解放された後、削除されます。

JENNIFERモジュールが読み込まれているプロセスが存在している場合、ディレクトリの削除ができません。削除ができない場合はJENNIFERモジュールを読み込んでいるプロセスを停止し、もう一度削除してください。

バージョンアップ(パッチ)とロールバック

バージョンアップ(パッチ)方法

クライアントの[管理 > エージェントアップグレード]画面から新しいバージョンを簡単に適用できます。または以下の手順でエージェント（.NET）を直接バージョンアップすることも可能です。

  1. 既存のInstaller.exeファイルを新しいバージョンのInstaller.exeで上書きします。

  2. 上書きした新しいInstaller.exeを実行します。

  3. 監視しているプロセスがある場合、そのプロセスを再起動して、新しいバージョンのエージェントを適用します。（例えば、IISの場合、リサイクル）

以前のバージョンへロールバックする方法

/binディレクトリに、使用されているエージェントインストールファイルがInstaller.[version number].exeの形式で保存されています。以前、インストールしたバージョンのエージェントを登録するには該当バージョンのインストールファイルを再度実行します。

登録の完了後、既存の.NETプロセスを再起動して反映します。（例えば、IISの場合、リサイクル）

エージェント構成ファイルの設定

エージェントファイルをインストール後、監視対象の.NETアプリケーションに対する構成ファイルの設定が必要です。監視対象のアプリケーションがIIS WebやNTサービスまたはCOM+アプリケーションの場合はbin/IISConfigHelper.exeツールで設定します。一方、スタンドアロン型のアプリケーションの場合は構成ファイルを手動で設定します。

IIS Webアプリケーションの設定

IIS Webアプリケーションはアプリケーションプール(Application Pool)単位でプロセス（w3wp.exe）が生成されます。エージェントもw3wp.exeプロセス単位で構成ファイルを設定します。

例えば、以下の画面には"cshtml_web"、"DefaultAppPool"と"Jennifer40.WebSiteTest4"が".NET Webアプリケーション (.NET web applications)"を含むアプリケーションプールに登録されています。

IISに登録されたアプリケーションプール

上図では".NET v2.0"、".NET v2.0 Classic"、".NET v4.5"、".NET v4.5 Classic"および"Classic .NET AppPool"に登録されているアプリケーションがないため、そこにはエージェント（.NET）のインストールができません。

この環境で/bin/IISConfigHelper.exeツールを実行している場合、"IIS"ノードで有効化できる3つのアプリケーションプール名が表示されます。

エージェントをインストールできるアプリケーションプールのリスト

インストール用のアプリケーションプールを右クリックすると、"Install"メニューが表示されます。メニューを選択すると、画面の右側に設定入力画面が表示されます。

エージェントを選択したアプリケーションツールに適用

設定項目は次の通りです。

エージェント(.NET)の必要なオプション説明

フィールド名

説明

Jennifer Server

データサーバのDNS名またはIPアドレス

Server Port

データサーバのlisten_port番号

Domain Id

データサーバに登録したドメインID

値：1から32767までの整数

Start Instance Id

エージェント（.NET）が有効なアプリケーション用の識別子です。


データサーバに接続されている各エージェントのIDはユニークである必要があります。最大100インスタンスまで単一ドメインにアクセスできます。（100インスタンスを超えて設定すると、新規エージェントからのアクセスは拒否されます）


IISのWebアプリケーションの場合、複数のw3wp.exeプロセスを"Webガーデン (Web Garden)"設定に合わせて有効化できるため、範囲を指定する必要があります。

Auto ID

チェックを入れるとインスタンスのIDが自動生成されます。

Auto Select

IIS Webアプリケーションの場合のみ有効なオプションです。チェックを入れると、使用できるアプリケーションプールに属するすべてのWebアプリケーションを監視します。


チェックを外した場合は下のインスタンスリストにリストアップされているインスタンスの中でチェックを入れたものが監視可能です。

設定後、［Save]ボタンを押して設定を保存します。この設定は[アプリケーションプール名].confファイルとして[agent installation folder]\config\iisに保存されます。

COM+ アプリケーションの設定

コンポーネントサービスに登録したCOM+アプリケーションは主に次の2種類の有効化タイプがあります。

  1. ライブラリの有効化：プロセス内部で有効化されるCOM+アプリケーション

  2. サーバの有効化：dllhost.exeプロセスで有効化されるCOM+アプリケーション

ライブラリの有効化タイプのCOM+アプリケーションの場合は別途の設定は必要ありません。ただし、サーバの有効化タイプのCOM+アプリケーションはエージェント（.NET）の構成ファイルを設定する必要があります。

/bin/IISConfigHelper.exeツールを実行すると、"サーバの有効化(server activation)"タイプのCOM+アプリケーションが自動的に表示されます。監視対象のアプリケーションを右クリックして、"Install"メニューを選択します。例えば、次の画面は"MyComponentServer"のCOM+アプリケーションの設定例です。

サーバの有効化の種類に応じたCOM+アプリケーション用の構成ファイルの設定

入力項目については エージェント(.NET)の必要なオプション説明を参照してください。

サービスアプリケーションの設定

/bin/IISConfigHelper.exeツールではNTサービスに登録されている.NET Frameworkベースのアプリケーションが"NT Service"ノードに表示されます。

次の画面は"Install"メニューを使用して、5つの.NET Frameworkベースのサービスの中で"RemoteTestService40"のサービスの構成ファイルを設定する例を示しています。

サービスアプリケーション用の構成ファイルの設定

入力項目についてはエージェント(.NET)の必要なオプション説明を参照してください。

スタンドアロン型アプリケーションの設定

スタンドアロンのEXEプログラム(IISやCOM+サービスではない)の場合、構成ファイルを手動で設定する必要があります。confディレクトリのapp_pool.confファイルをコピーし、[EXE ファイル名].exe.confの名前で保存します。

保存したファイルをテキストエディターで開いて、エージェント(.NET)の必要なオプション説明を参照しながら値を設定します。

アプリケーション開始点の登録

スタンドアロンタイプのプログラムはプログラム独自のアプリケーション開始点を持ってます。それをモニタリングするには.confファイルにアプリケーション開始点を直接設定する必要があります。次のようなオプションを利用してアプリケーション開始点を.confファイルに設定します。

profile_service_class = TestName.ThreadTest threadFunc 
profile_service_class = ThisClass OneWithArray(System.Object[])System.Void 
profile_service_pattern = TxServerRootNamespace.* 
profile_service_super = WebSiteTest.TxServerPMSuper 
profile_service_interface = SiteTest.ITxServerProfileTarget

アプリケーション開始点を把握する方法は次の通りです。

バッチ処理の設定

バッチ処理プロセスは基本的にスタンドアロン型アプリケーションの設定とその方法が同様です。但し、データサーバにバッチ処理のための専用ドメインを構成し、そのドメインを利用することが異なります。

server_address =  <データサーバのIP>
server_port = <データサーバのポート番号>
domain_id = <データサーバへ構成したバッチ処理専用ドメインID>
inst_id = <エージェントID>
inst_id_pool = 1

上記の設定に加えてアプリケーションの開始点を指定しなければなりません。アプリケーション開始点は「application_start_point」オプションに指定します。

server_address = 192.168.0.100
server_port = 5000
domain_id = 1000
inst_id = 200
inst_id_pool = 1

application_start_point = ConsoleApp.Program Main

「application_start_point」オプションは"[Namespace.ClassName] [MethodName]"の形式で指定します。

バッチ処理が早すぎて、データサーバとセッションが結ばれる前に終わってモニタリングができない場合はエージェント設定ファイルに次のオプションを設定するとモニタリング可能です。

send_transaction_in_application_thread = true

send_transaction_in_application_threadオプションはデータサーバとセッションを結ぶまで最大5秒待機状態にするオプションです。テスト環境のみ使用することを推奨します。

エージェントの適用と解除

監視するアプリケーションの構成ファイルを作成後、EXEプロセスを再起動すると、監視が有効になります。

また、.NET Agentをアンインストールする場合は構成ファイルを削除し、EXEプロセスを再起動します。

JENNIFERバージョン4.xとの相違点

JENNIFERバージョン4.xも、IISConfigHelper.exeをインストールで使用しましたが、下記のように多くの変更点があります。

JENNIFERバージョン4.xから移行するには

移行は次のように実施します。

  1. [JENNIFER 4.x インストールディレクトリ]内のuninstall_jennifer.batファイルを実行し、バージョン4.x.をアンインストールします。

  2. [JENNIFER 5.x インストールディレクトリ]内のinstaller.exeファイルを実行し、バージョン5.x.xをインストールします。

  3. 構成ファイルは互換性がないため、新しい構成ファイルを作成します。

Linux - .NET Core環境

インストール

JENNIFER.netエージェントの圧縮ファイル(jennifer-agent-dotnet-[version].zip)を解凍します。解凍すると次のファイルが生成されます。

Linux環境にインストールするには、.NET Core2.0 Runtimeのインストールが前提です。その上で次のコマンドを実行するとインストールができます。

$ sudo dotnet agent-installer.dll

正常にインストールができると、次のディレクトリが生成されます。

ディレクトリの説明

ディレクトリ

説明

bin/

エージェントの実行ファイルが格納されているディレクトリ

config/

エージェントの設定ファイルを保存するディレクトリ

logs/

エージェントのログディレクトリ

utility/

ユーテリティの実行ファイルが格納されているディレクトリ

アンインストール

agnet-installer.dll実行時、"/u"パラメータを指定すると、アンインストールされます。または、uninstaller.shファイルを実行します。

$ sudo dotnet agent-installer.dll /u

または

$ sudo ./uninstaller.sh

上記のコマンドを実行してもシステムに登録されている情報のみを消去し、動作中のプロセスではJENNIFERエージェントのモジュールが使われ続けています。

そのため、既存モニタリング中のプロセスがある場合は、プロセスを再起動する必要があります。

バージョンアップおよび以前のバージョンにロールバック

バージョンアップ

.netエージェントのバージョンアップはJENNIFERコンソールの[管理＞エージェントアップグレード]画面で簡単にできます。または、次の手順で手動ですることも可能です。

  1. 新しいバージョンのjennifer-agent-dotnet-[version].zipの内容を既存ディレクトリに上書き解凍します。

  2. agent-installer.dllファイルを実行してJENNIFERモジュールを更新します。

  3. 既に動作中のプロセスがありましたら、該当プロセスを再起動します。

以前のバージョンにロールバック

インストールディレクトリには今までインストールされていたエージェントのファイルが”/bin.[version]”ディレクトリに保存されてます。

例えば、5.4.0.1バージョンのエージェントをインストールしたことがある場合、"./bin.5.4.0.1"ディレクトリが存在します。このバージョンにロールバックするには、"/bin"ディレクトリを削除して"/bin.5.4.0.1"のディレクトリ名を"/bin"に変更します。

変更が完了したら、既存プロセスを再起動します。

設定ファイルの構成

モニタリングのために以下の2つの作業が必要です。1つはconfファイルを生成、もう１つは環境変数の構成です。

/configディレクトリにconfファイルを生成

モニタリング対象のタイプによってconfファイル名が決まります。.NET Coreアプリケーションは2つのタイプがあります。

[dll]
$ dotnet [...net.dll...]

例)
$ dotnet CoreCoreLin.dll
[ELF(Excutable and Linkable Format)]
$ [...net_elf...]

例)
$ ./CoreCoreLin

dllで実行される場合は<dllファイル名>.dll.conf、ELFタイプで実行される場合は<ELFファイル名>.confにconfファイル名を指定します。confファイルの内容は、app_pool.confの内容をコピーして環境に合わせて変更します。

server_address = <データサーバのIPアドレス＞
server_port =  <データサーバのリスニングポート>
domain_id = <データを保存するドメインID>
inst_id = <エージェントID>
inst_id_pool = 1

環境変数の構成

モニタリング対象プロセスには次の環境変数を適用する必要があります。

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
CORECLR_PROFILER_PATH=libAriesProfiler.so

もし、shellファイルを利用して実行されるアプリケーションであれば、その.shファイルに次のように環境変数を設定します。

export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
export CORECLR_PROFILER_PATH=libAriesProfiler.so

ほとんどの場合、Linuxで実行される.NET Coreアプリケーションは"/etc/systemd/system"ディレクトリのサービスとして登録されています。この場合は、サービスファイルに環境変数の構成を追記します。

[Service]
WorkingDirectory=/home/tusr/corecorelin
ExecStart=/usr/share/dotnet/dotnet /home/tusr/corecorelin/CoreCoreLin.dll
KillSignal=SIGINT
SyslogIdentifier=dotnet-corecorelin
Environment=CORECLR_ENABLE_PROFILING=1
Environment=CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
Environment=CORECLR_PROFILER_PATH=libAriesProfiler.so

Linux Dockerの.NET Core環境

インストール

インストール方法は次の２種類があります。

  1. docker run実行時.NETエージェントモジュールがあるパスと変数を指定する方法

  2. 既存.NET CoreコンテナのDockerfileに.NETエージェントモジュールと環境変数を入れる方法

1つ目の方法は既存の Dockerfileの変更が必要ないですが、shellを使わず実行する場合にコマンドが複雑になります。2つ目の方法は実行コマンドは簡単ですが、既存のDockerfileを修正しなければなりません。

都合に合わせて適切なインストール方法の選択が必要です。

docker runにパラメータを追加する方法

1

.netエージェントの圧縮ファイルを解凍して、次のコマンドを実行します。

$ dotnet agent-installer.dll --unzip

例えば, /opt/jennifer/dotnetディレクトリに圧縮を解凍してコマンドを実行すると次のようにディレクトリが生成されます。

/opt/jennifer/dotnet
├───bin
│   └───net40
├───config
├───extension
│   ├───netcore
│   └───sample
|───logs
|───service_dump
└───utility
    ├───net40
    │   ├───x64
    │   └───x86
    ├───x64
    └───x86

2

モジュールのパスと環境変数をdocker runの実行時に指定します。

ホスト側からコンテナ側へ設定するパス

ホスト側のパス

コンテーナ側のパス

説明

/opt/jennifer/dotnet

netagent

ホスト側のパスはインストールパス、コンテナ側のパスは必ず"netagent"に指定

コンテナ側に設定すべき環境変数

環境変数名

値

説明

CORECLR_ENABLE_PROFILING

1

固定値

CORECLR_PROFILER

{6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}

固定値

CORECLR_PROFILER_PATH

/netagent/bin/libAriesProfiler.so

固定値

ARIES_DEFAULT_CONF

app_pool.conf

/opt/jennifer/dotnet/conf配下のconfファイル中1つを指定

この方法は既存Dockerfileの変更なしでインストールが可能です。次は設定の例です。

$ docker run -e CORECLR_ENABLE_PROFILING=1 -e CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8} -e CORECLR_PROFILER_PATH=/netagent/bin/libAriesProfiler.so -e ARIES_DEFAULT_CONF=app_pool.conf ...[既存パラメータ]...

.NETエージェントが追加されたDockerfileの生成方法

1

エージェントモジュールをコンテナイメージ内部にコピーします。

RUN apt-get update \
    && apt-get install -y --no-install-recommends unzip \
    && rm -rf /var/lib/apt/lists/*
ADD http://...url.../jennifer-agent-dotnet-5.5.1.5.zip /tmp/agent_latest.zip
WORKDIR /tmp
RUN unzip agent_latest.zip -d extracted
WORKDIR /tmp/extracted
RUN dotnet agent-installer.dll --unzip

COPY /tmp/extracted /netagent

2

環境変数を追加します。

ENV CORECLR_ENABLE_PROFILING 1
ENV CORECLR_PROFILER {6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
ENV CORECLR_PROFILER_PATH /netagent/bin/libAriesProfiler.so
ENV ARIES_SERVER_ADDR 192.168.0.10
ENV ARIES_SERVER_PORT 5000
ENV ARIES_DOMAIN_ID 2790

上記の例は動的にインスタンスIDを発行する場合ですが、特定のIDを指定する場合はARIES_INST_ID 環境変数を追加します。

ENV ARIES_INST_ID 121

Azure App Services環境

App Serviceで動作する.NET WebApplicationは次の４種類です。

Windows環境のApp SerivceはExtensionを追加してインストールしてください。

Linux環境の場合は、Linux - .NET コア環境を参照してインストールしてください。

インストール

AzureのApp Servies管理画面にて次のように"Extensions"メニューを選択、"Add"ボタンをクリックします。

Azure Extensionsメニュー

インストール可能な項目中"JENNIFER .NET Agent"項目を選択します。

JENNIFER .NET Agent 選択

インストール完了後、"App Services"管理画面の"Application Settings"画面にて次の環境変数を登録します。

環境変数の設定

環境変数名

値

必須有無

説明

ARIES_SERVER_ADDRESS

[JENNIFERデータサーバのIP]

必須

可変値 (例: 192.168.0.100)

ARIES_SERVER_PORT

[JENNIFERデータサーバのポート]

必須

可変値 (例: 5000)

ARIES_DOMAIN_ID

[JENNIFERデータサーバのドメインID]

必須

可変値 (例: 1000)

必須設定の環境変数以外に、自動で設定される環境変数は次のとおりです。これらの環境変数は手動で設定しても自動で上書きされます。

自動設定される環境変数

環境変数名

値

説明

COR_ENABLE_PROFILING

1

固定値

COR_PROFILER

{6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}

固定値

COR_PROFILER_PATH_32

D:\home\SiteExtensions\JenniferNetAgentExtension\bin\AriesProfiler.dll

固定値

COR_PROFILER_PATH_64

D:\home\SiteExtensions\JenniferNetAgentExtension\bin\AriesProfiler64.dll

固定値

ARIES_RESOLVE_MODULE

v2

固定値

ARIES_AZURE

1

固定値

環境変数を設定後、App Servicesを再起動すると設定が反映されてモニタリングできます。

アンインストール

Azure管理画面の該当App Serviceの"Extension"メニューからインストールされたJENNIFERエージェントExtensionを選択し、"削除(Delete)"します。

JENNIFERエージェントExtensionの削除

但し、この作業はJENNIFERエージェントExtensionファイルが削除されただけで、すでに実行中のWeb Applicationのプロセスに反映するにはApp Serviceの再起動が必要です。

バージョンアップ

バージョンアップのためには、既存のバージョンを削除した後に新しいバージョンをインストールします。この際はApp Serivceの再起動が必要です。

Azure App Serviceの"Extensions"リストで "Update"メニューがありますが、モジュールのロックがありますので、必ず削除後にインストールしなければなりません。