この章ではエージェント(.NET)のインストール方法を説明します。
エージェント(.NET)の対応環境
対応OS
エージェント(.NET)を正常にインストールできるOSは次の通りです。
Windows Server 2003 SP2以上 x86/x64(5.4.0.4までサポート)
Windows Server 2008 x86/x64(R2を含む)
Windows Server 2012 x64 (R2を含む)
Windows Server 2016 x64
Windows Server 2019 x64(5.4.0.5からサポート)
Windows Server 2022 x64(5.5.2.0からサポート)
クライアント向けWindowsの場合、エージェント(.NET)はWindows XP SP3以上でも動作しますが、公式のサポートは上記OSでのみ提供します。
Windows Server 2003 (SP2): 5.4.0.4バージョンを最後にサポート終了。
Windows Server 2008: 5.5.1.11バージョンを最後にサポート終了。
Webサーバ及び.NETフレームワーク
- Webサーバ
IIS6.0以上(6.0、7.0、7.5、8.0、8.5、10.0)
- .NETフレームワーク
.NET Framework 2.0以上(2.0、3.0、3.5、4.0~4.8)
- .NETコア
.NET Core 2.0以上(2.0、2.1、3.0、3.1、5.0~6.0)
.NET Core/5+はLinux OSもサポートしますが、この場合、.NET Core 2.0以降のOSを対象にサポートします。このリストは、現在のMicroSoftの公式文書によるものです。
Prerequisites for .NET Core on Linux
https://learn.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x
Red Hat Enterprise Linux 7, 6 - 64-bit (x86_64 or amd64)
CentOS 7 - 64-bit (x86_64 or amd64)
Oracle Linux 7 - 64-bit (x86_64 or amd64)
Fedora 28, 27 - 64-bit (x86_64 or amd64)
Debian 9 (64-bit, arm32), 8.7 or later versions - 64-bit (x86_64 or amd64)
Ubuntu 18.04 (64-bit, arm32), 16.04, 14.04 - 64-bit (x86_64 or amd64 or ARM64)
Linux Mint 18, 17 - 64-bit (x86_64 or amd64)
openSUSE 42.3 or later versions - 64-bit (x86_64 or amd64)
SUSE Enterprise Linux (SLES) 12 Service Pack 2 or later - 64-bit (x86_64 or amd64)
Alpine Linuxはサポートしません。(glibcベースのLinux OSのみをサポートし、muslベースはサポートしません)
ARM64環境の場合は、5.6.2.21バージョンからサポートします。
エージェントのインストールとアンインストール
一般サーバとクラウドの単独仮想マシン環境
エージェントのインストール
jennifer-agent-dotnet-[version].zipファイルを解凍すると、Installer.exeとInstaller.exe.configファイルが作成されます。Installer.exeファイルを実行すると、bin、config、logsおよびutilityディレクトリが作成され、プログラムの登録が完了します。
ディレクトリ | 説明 |
|---|---|
bin | エージェント実行ファイルが存在するディレクトリ |
config | エージェントが適用されているアプリケーション用の構成および設定ファイルを保存するためのディレクトリ |
extension | 拡張アダプターが保存されるディレクトリ |
logs | エージェントログファイルを保存するディレクトリ |
service_dump | サービスダンプファイルを保存するディレクトリ |
utility | ユーティリティファイルが存在するディレクトリ |
プログラムが正常に登録された後、監視対象のアプリケーションを決定し、エージェント(.NET)を実行するための構成ファイルを作成します。この操作に関する詳しい情報については エージェント構成ファイルの設定 を参照してください。
エージェントのアンインストール
エージェントをアンインストールする2つの方法を説明します。1つは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)を直接バージョンアップすることも可能です。
既存のInstaller.exeファイルを新しいバージョンのInstaller.exeで上書きします。
上書きした新しいInstaller.exeを実行します。
監視しているプロセスがある場合、そのプロセスを再起動して、新しいバージョンのエージェントを適用します。(例えば、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"メニューが表示されます。メニューを選択すると、画面の右側に設定入力画面が表示されます。
エージェントを選択したアプリケーションツールに適用
設定項目は次の通りです。
フィールド名 | 説明 |
|---|---|
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種類の有効化タイプがあります。
ライブラリの有効化:プロセス内部で有効化されるCOM+アプリケーション
サーバの有効化: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)の必要なオプション説明を参照しながら値を設定します。
AOT(Ahead-of-time)ビルドしたバイナリの場合はエージェントが動作しません。
アプリケーション開始点の登録
スタンドアロンタイプのプログラムはプログラム独自のアプリケーション開始点を持ってます。それをモニタリングするには.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
アプリケーション開始点を把握する方法は次の通りです。
顧客に適切なアプリケーション開始点を確認する
デコンパイラなどを利用して、該当EXE/DLLファイルをデコンパイルして探す
JENNIFERエージェントログディレクトリ(¥agent.net¥logs)配下に"profiler"というディレクトリを生成するとモニタリング対象プログラムで実行されるクラスとメソッドが出力される。これを利用してアプリケーション開始点を把握する。(注意: profilerディレクトリは容量が大きくなる可能性が高いので、確認後必ず削除)
バッチ処理の設定
バッチ処理プロセスは基本的にスタンドアロン型アプリケーションの設定とその方法が同様です。但し、データサーバにバッチ処理のための専用ドメインを構成し、そのドメインを利用することが異なります。
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をインストールで使用しましたが、下記のように多くの変更点があります。
以前のバージョンのconfディレクトリはJENNIFER5の場合、configディレクトリに変更されています。
Webサイト用の構成ファイルはconfig¥iisディレクトリに個別に保存されます。
COM+用の構成ファイルはconfig¥complusディレクトリに個別に保存されます。
JENNIFER_PROFILE環境変数は使用しません。該当exeファイル名で始まるconfファイルが存在すると自動的に適用されます。
Webアプリケーションの場合、JENNIFER4では「仮想アプリケーション」単位でconfファイルを作成しましたが、JENNIFER5では「アプリケーションプール」単位で作成します。
既存profiler.iniファイルで設定したプロファイル関連オプションをconfファイルに統合しました。
JENNIFERバージョン4.xから移行するには
移行は次のように実施します。
[JENNIFER 4.x インストールディレクトリ]内のuninstall_jennifer.batファイルを実行し、バージョン4.x.をアンインストールします。
[JENNIFER 5.x インストールディレクトリ]内のinstaller.exeファイルを実行し、バージョン5.x.xをインストールします。
構成ファイルは互換性がないため、新しい構成ファイルを作成します。
Linux - .NET Core/5+ 環境
インストール
JENNIFER.netエージェントの圧縮ファイル(jennifer-agent-dotnet-[version].zip)を解凍します。解凍すると次のファイルが生成されます。
Installer.exe
Installer.exe.config
Binaries.zip
agent-installer.dll
agent-installer.runtimeconfig.json
agent-installer3.dll
agent-installer3.runtimeconfig.json
agent-setup (5.6.2.2バージョンから追加)
agent-setup-arm64 (5.6.2.21バージョンから追加)
Linux環境にインストールするには、.NET Core2.0 Runtimeのインストールが前提です。その上で次のコマンドを実行するとインストールができます。
Linux環境でのインストールコマンドはagent-setupを実行するだけです。
$ ls -l agent-setup -rw-rw-rw-. 1 kevin kevin 3556464 Dec 15 16:21 agent-setup $ chmode u+x agent-setup $ ls -l agent-setup -rwxrw-rw-. 1 kevin kevin 3556464 Dec 15 16:21 agent-setup [x86_64 環境の場合] $ sudo ./agent-setup [ARM64 環境の場合] $ sudo ./agent-setup-arm64
[.NET Core 2.2 以下の場合] $ sudo dotnet agent-installer.dll [.NET Core 3.0 以上の場合] $ sudo dotnet agent-installer3.dll
正常にインストールができると、次のディレクトリが生成されます。
ディレクトリ | 説明 |
|---|---|
bin/ | エージェントの実行ファイルが格納されているディレクトリ |
config/ | エージェントの設定ファイルを保存するディレクトリ |
logs/ | エージェントのログディレクトリ |
utility/ | ユーテリティの実行ファイルが格納されているディレクトリ |
アンインストール
agnet-installer.dll実行時、"/u"パラメータを指定すると、アンインストールされます。または、uninstaller.shファイルを実行します。(agent-setup実行時も同一方法)
$ sudo dotnet agent-installer.dll /u または $ sudo dotnet agent-installer3.dll /u または $ sudo ./uninstaller.sh
$ sudo ./agent-setup /u
上記のコマンドを実行してもシステムに登録されている情報のみを消去し、動作中のプロセスではJENNIFERエージェントのモジュールが使われ続けています。
そのため、既存モニタリング中のプロセスがある場合は、プロセスを再起動する必要があります。
バージョンアップおよび以前のバージョンにロールバック
バージョンアップ
.netエージェントのバージョンアップはJENNIFERコンソールの[管理>エージェントアップグレード]画面で簡単にできます。または、次の手順で手動ですることも可能です。
新しいバージョンのjennifer-agent-dotnet-[version].zipの内容を既存ディレクトリに上書き解凍します。
agent-installer.dllファイルを実行してJENNIFERモジュールを更新します。
既に動作中のプロセスがありましたら、該当プロセスを再起動します。
以前のバージョンにロールバック
インストールディレクトリには今までインストールされていたエージェントのファイルが”/bin.[version]”ディレクトリに保存されてます。
例えば、5.4.0.1バージョンのエージェントをインストールしたことがある場合、"./bin.5.4.0.1"ディレクトリが存在します。このバージョンにロールバックするには、"/bin"ディレクトリを削除して"/bin.5.4.0.1"のディレクトリ名を"/bin"に変更します。
変更が完了したら、既存プロセスを再起動します。
設定ファイルの構成
モニタリングのために以下の2つの作業が必要です。1つはconfファイルを生成、もう1つは環境変数の構成です。
/configディレクトリにconfファイルを生成
モニタリング対象のタイプによってconfファイル名が決まります。.NET Coreアプリケーションは2つのタイプがあります。
[dll] $ dotnet [...net.dll...] 例) $ dotnet CoreCoreLin.dll
[ELF/EXE] $ [...net_elf/exe...] 例) $ ./CoreCoreLin c:¥app>CoreCoreLin.exe
dllで実行される場合は<dllファイル名>.dll.conf、ELF/EXEタイプで実行される場合は<ELF/EXEファイル名>.<elf/exe>.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※ARM64環境の場合は以下のファイルを指定します。
CORECLR_PROFILER_PATH=libAriesProfilerARM64.so
もし、shellファイルを利用して実行されるアプリケーションであれば、その.shファイルに次のように環境変数を設定します。
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
export CORECLR_PROFILER_PATH=libAriesProfiler.so※ARM64環境の場合は以下のファイルを指定します。
export CORECLR_PROFILER_PATH=libAriesProfilerARM64.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デーモンとして実行される場合、デーモンが実行されるサービスアカウントが.NETエージェントのインストールディレクトリにアクセスできる権限が必要です。
Linux Dockerの.NET Core環境
インストール
インストール方法は次の2種類があります。
docker run実行時.NETエージェントモジュールがあるパスと変数を指定する方法
既存.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
└───x862
モジュールのパスと環境変数を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つを指定 |
IgnoreAgentConfigFile | 1 | もし、複数のコンテナが一つのボリュームを共有してモニタリングする場合に設定 |
この方法は既存Dockerfileの変更なしでインストールが可能です。次は設定の例です。
$ docker run -v /opt/jennifer/dotnet:/netagent -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 ...[既存パラメータ]...又は、confファイルを使わず、すべての設定を環境変数で設定することも可能です。
$ docker run -v /opt/jennifer/dotnet:/netagent -e ARIES_DOMAIN_ID=1000 -e ARIES_SERVER_ADDRESS=127.0.0.1 -e IgnoreAgentConfigFile=1 -e ARIES_SERVER_PORT=5000 -e CORECLR_ENABLE_PROFILING=1 -e CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8} -e CORECLR_PROFILER_PATH=/netagent/bin/libAriesProfiler.so ...[既存パラメータ]...ARM64環境の場合はlibAriesProfiler.soの代わりにlibAriesProfilerARM64.soファイルを指定します。
.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 /netagent2
環境変数を追加します。
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 2790ARM64環境の場合はlibAriesProfiler.soの代わりにlibAriesProfilerARM64.soファイルを指定します。
上記の例は動的にインスタンスIDを発行する場合ですが、特定のIDを指定する場合はARIES_INST_ID 環境変数を追加します。
ENV ARIES_INST_ID 121
AKS(Azure Kubernetes Service) 環境
エージェント5.6.2.7バージョンからサポートします。
インストール
k8sはコンテナに対するオーケストレーションツールなので、インストール方法はコンテナ環境と同じように次の2つに分けられます。
実行時に.NETエージェントバイナリがあるPVとPodを接続し、環境変数を指定する方法。
既存の.NET CoreコンテナのDockerfileに.NETエージェントバイナリと環境変数を含める方法。
1番目の方法は既存サービスのために構成したDockerfileを変更する必要がないという利点がありますが、PV/PVCを準備してこれを接続するためにdeployment/podのyamlファイルを変更する必要があります。2番目の方法を選択すると、他の設定は不要ですが、既存のデプロイメントプロセスで構成したDockerfileをユーザ側で修正しなければならないというデメリットがあります。そのため、お客様の状況に合わせて、2つの方法のいずれかを適切に選択して適用する必要があります。
実行時にPVとPodを接続し、環境変数を指定する方法
まずエージェントのバイナリが必要ですので、圧縮ファイル(jennifer-agent-dotnet-[version].zip)を解凍して出てきたファイルから、Binaries.zipファイルを解凍します。
Installer.exe
Installer.exe.config
Binaries.zip
agent-installer.dll
agent-installer.runtimeconfig.json
agent-installer3.dll
agent-installer3.runtimeconfig.json
agent-setup (5.6.2.2バージョンから追加)
agent-setup-arm64 (5.6.2.21バージョンから追加)
$ unzip Binaries.zip
.NETエージェントバージョンが5.6.2.1以下の場合、次のコマンドを実行します。
[.NET Core 2.2 以下]
$ dotnet agent-installer.dll --unzip
[.NET Core 3.0 以上]
$ dotnet agent-installer3.dll --unzip
例えば, /opt/jennifer/dotnetディレクトリに圧縮を解凍してコマンドを実行すると次のようにディレクトリが生成されます。
/opt/jennifer/dotnet
├───bin
│ └───net40
├───config
├───extension
│ ├───netcore
│ └───sample
|───logs
|───service_dump
└───utility
├───net40
│ ├───x64
│ └───x86
├───x64
└───x86該当ファイルをPVにコピーする必要があるため、まず、PVを生成します。
$ kubectl apply -f https://raw.githubusercontent.com/jennifersoft/jennifer5-aks/main/agent_pv.yaml
上記のyamlファイルはAzure環境を対象にazurefileタイプでのPV/PVCを生成する例になりますが、お客様の環境に合わせてyamlファイルの内容を変更して適用することも可能です。
PV生成後、"kubectl get pv"コマンドで"NAME"を確認します。
C:\temp> kubectl get pv NAME CAPACITY ACCESS MODES ...[생략]... AGE pvc-5cef2cb5-a37b-483e-9138-d08ff1ef74d4 1Gi RWX ...[생략]... 20h
出力されたNAMEを利用して、PVが属するStorage Accountを確認します。
C:\temp> kubectl describe pv pvc-5cef2cb5-a37b-483e-9138-d08ff1ef74d4 Name: pvc-5cef2cb5-a37b-483e-9138-d08ff1ef74d4 Labels: <none> ...[省略]... Capacity: 1Gi Node Affinity: <none> Message: Source: Type: CSI (a Container Storage Interface (CSI) volume source) Driver: file.csi.azure.com FSType: VolumeHandle: mc_testaks_aks-jennifer-demo_koreacentral#f0ae5f59e9e7a4036b1d8cb#pvc-5cef2cb5-a37b-483e-9138-d08ff1ef74d4# ...[省略]...
Azure Storage Explorerなどのツールを使ってローカルの 「/opt/jennifer/dotnet」 ディレクトリをコピーします。
ここでは、「/opt/jennifer/dotnet」ディレクトリに解凍した内容をPVにコピーする際に、「/extracted」ディレクトリを作成し、その直下にコピーしたものと仮定して説明します。
deploymentを実行するyamlファイル内に登録したコンテナでvolumeを使って接続し、環境変数も一緒に設定します。
apiVersion: apps/v1
kind: Deployment
...[省略]...
spec:
...[省略]...
template:
...[省略]...
spec:
containers:
...[省略]...
env:
- name: CORECLR_ENABLE_PROFILING
value: "1"
- name: CORECLR_PROFILER
value: "{6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}"
- name: CORECLR_PROFILER_PATH
value: "/extracted/bin/libAriesProfiler.so"
- name: ARIES_IGNORE_CONF_FILE
value: "1"
- name: ARIES_SERVER_ADDRESS
value: "127.0.0.1"
- name: ARIES_SERVER_PORT
value: "5000"
- name: ARIES_DOMAIN_ID
value: "1000"
- name: ARIES_INST_ID
value: "-1"
volumeMounts:
- mountPath: "/extracted"
name: volume
volumes:
- name: volume
persistentVolumeClaim:
claimName: jennifer5-agent-fileARM64環境の場合はlibAriesProfiler.soの代わりにlibAriesProfilerARM64.soファイルを設定します。
Azure App Services環境
App Serviceで動作する.NET WebApplicationは次の4種類です。
ASP.NET Web Application on .NET Framework for Windows (5.4.0.3以上)
ASP.NET Core Web Application on .NET Framework for Windows (5.4.0.3以上)
ASP.NET Core Web Application on .NET Core for Windows (5.5.0.10以上)
ASP.NET Core Web Application on .NET Core for Linux(x86_64) (5.6.0以上)
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) |
ARIES_INST_ID | -1 | JENNIFERサーバで自動的に設定する場合 | |
ARIES_IGNORE_CONF_FILE | 1 | confファイルなしで動作 |
必須設定の環境変数以外に、自動で設定される環境変数は次のとおりです。これらの環境変数は手動で設定しても自動で上書きされます。
環境変数名 | 値 | 説明 |
|---|---|---|
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"メニューがありますが、モジュールのロックがありますので、必ず削除後にインストールしなければなりません。
デプロイ スロット(Deployment Slot)の場合
Azureでのデプロイメントスロットは「AppService」と同じように扱われます。そのため、デプロイメントスロットを作成する場合、そこにもJENNIFERジェントをインストールし、環境変数を追加する必要があります。
ただ、環境変数を追加すると展開スロットのインスタンスも有効にありますので、これを防ぐ場合は「ARIES_ENABLE」環境変数を「0」の値で「Deployment slot setting」と一緒に設定します。