Tivoli Performance Viewer のロギングをスクリプトで開始/停止する

tWAS (WebSphere Application Server traditonal) のメトリックは、PMI (Performance Monitoring Infrastructure) と呼ばれる機能によって生成されます。
生成されたメトリックを取得し表示するための機能が、TPV (Tivoli Performance Viewer) です。TPV は、メトリックをログ・ファイルに記録する機能も持っています。

以下のスクリプトを github に公開しましたので、その概要を記載します。
* TPV のロギングを開始/停止する jython スクリプト
* PMI のカスタム統計セットを設定する jython スクリプト

参照：[github twas-pmi-tpv](https://github.com/splendormy/twas-pmi-tpv)


## TPV のロギングを開始/停止する jython スクリプト
まずは、TPV ロギングを開始/停止する jython スクリプト `tpvLogging.py` です。
開発に必要な情報は、以下の URL に記載されていますが、少し分かりにくい部分もありました。

- [WebSphere Application Server 9.0.5 - スクリプトを使用した Tivoli Performance Viewer データのロギング](https://www.ibm.com/docs/ja/was/9.0.5?topic=mosh-logging-tivoli-performance-viewer-data-by-using-scripting)

スクリプトの説明は省略します。詳細は、[github](https://github.com/splendormy/twas-pmi-tpv) に掲載したスクリプトを参照してください。
メトリックの取得間隔/取得期間、ログ・ファイルのサイズ/数などは、スクリプト内で固定値を指定しています。


## アプリケーション・サーバーの事前準備
TPV でアプリケーション・サーバーのメトリックを取得するには、以下の２つの事前準備が必要です。
これらの設定は、tWAS の管理コンソールで「モニターおよびチューニング > Performance Monitoring Infrastructure (PMI)」に進み、対象とするアプリケーション・サーバーを選択すると表示される画面で設定できます。

1. PMI を使用可能にする
デフォルトで PMI は使用可能になっています。

1. 統計セットを指定する
デフォルトで「基本」が指定されています。
メトリックによってオーバーヘッドの大小が異なりますが、取得するメトリックが多いとスループットに影響を与える可能性があります。
プロダクションで使用する場合は、必要最低限のメトリックのみを取得するのがお勧めです。（統計セットとして「カスタム」を選択し、必要なメトリックのみを有効化することになります。）

取得可能なメトリック(カウンター)の情報は、下記 URL の子文書に記載されています。子文書内の「カウンター定義」の表を右にスクロールするとオーバーヘッドの大小も確認できます。

- [WebSphere Application Server 9.0.5 - PMI データ編成](https://www.ibm.com/docs/ja/was/9.0.5?topic=pmi-data-organization)

## 統計セットを設定する jython スクリプト
必要なメトリックだけを統計セット「カスタム」として定義するのは面倒な作業です。
この設定を行う jython スクリプトが `pmiSetupForBASE.py` と `pmiSetupForND.py` です。名前からもわかるように、`pmiSetupForBASE.py` が Base 構成用で、`pmiSetupForND.py` が ND (Network Deployment) 構成用です。

`pmiSetupForBASE.py` と `pmiSetupForND.py` では、以下のメトリック(カウンター)のみを有効化するようになっていますが、必要に応じてカスタマイズできます。
|モジュール|メトリック(カウンター)|
|---|---|
|connectionPoolModule|6: freePoolSize プール内にある空き管理接続の数<br>5: poolSize 接続プールのサイズ<br>2: numDestroys プールの作成以降に破棄された管理接続の総数<br>1: numCreates プールの作成以降に作成された管理接続の総数<br>8: faults 接続プールでの障害 (タイムアウトなど) の総数<br>13: avgWaitTime 接続が認可されるまでの平均待ち時間(ms)|
|j2cModule|同上|
|threadPoolModule|3: activeThreads 同時にアクティブなスレッドの数<br>4: poolSize プール内のスレッドの平均数|
|servletSessionsModule|7: liveSessions メモリーのキャッシュに入れられているセッションの数|

詳細は、[github](https://github.com/splendormy/twas-pmi-tpv) に掲載したスクリプトを参照してください。

## Base 構成での実行
説明した jython スクリプトを Base 構成で実行する例を記載します。


### PMI カスタム統計セットの設定
最初に実行するのが、カスタム統計セットを設定する jython スクリプト `pmiSetupForBASE.py` です。
このスクリプトは構成作業として最初に１回実行することなります。

wsadmin で jython スクリプト `pmiSetupForBASE.py` を実行するには、以下のオプションを指定します。

|オプション|説明|
|---|---|
|-lang jython|jython 言語を指定|
|-host (ホスト名)|アプリケーション・サーバーが稼働しているホストの名前|
|-port (ポート番号)|アプリケーション・サーバーの SOAP コネクターのポート番号|
|-f (スクリプトのパス)|`pmiSetupForBASE.py` のパス|
|(アプリケーション・サーバー名)|アプリケーション・サーバーの名前<br>(Base構成の場合は server1)|

実行例は以下の通りです。
PMI カスタム統計セットが正しく設定されているかは、tWAS 管理コンソールで確認できます。
設定を反映するには、アプリケーション・サーバーの再起動が必要です。

```bash:PMI カスタム統計セットの設定
[/opt/IBM/WebSphere/AppServer9.0/profiles/AppSrv01]# bin/wsadmin.sh -lang jython -host localhost -port 8880 -f /work/py/pmiSetupForBASE.py server1
WASX7209I: ノード xxxxNode01 のプロセス "server1" に、SOAP コネクターを使用して接続しました。プロセスのタイプは UnManagedProcess です。
WASX7303I: 次のオプションはスクリプト環境に渡され、argv 変数に格納される引数として使用可能になります: "[server1]"

cell = xxxxNode01Cell
node = xxxxNode01
server = server1

統計セットをカスタムに変更しました。[ basic ]->[ custom ]

alarmManagerModule の全てのカウンターを無効化しました。[  ]->[  ]
beanModule の全てのカウンターを無効化しました。[ 35,34,9,1,26,11,12,2,25 ]->[  ]
cacheModule の全てのカウンターを無効化しました。[  ]->[  ]
connectionPoolModule の全てのカウンターを無効化しました。[ 7,12,2,13,9,6,1,5 ]->[  ]
DCSStats.Group の全てのカウンターを無効化しました。[  ]->[  ]
hamanagerModule の全てのカウンターを無効化しました。[  ]->[  ]
jvmRuntimeModule の全てのカウンターを無効化しました。[ 4,1,3,5 ]->[  ]
j2cModule の全てのカウンターを無効化しました。[ 7,12,2,13,6,1,5 ]->[  ]
objectPoolModule の全てのカウンターを無効化しました。[  ]->[  ]
orbPerfModule の全てのカウンターを無効化しました。[  ]->[  ]
schedulerModule の全てのカウンターを無効化しました。[  ]->[  ]
servletSessionsModule の全てのカウンターを無効化しました。[ 7 ]->[  ]
StatGroup.SIBService の全てのカウンターを無効化しました。[  ]->[  ]
SipContainerModule の全てのカウンターを無効化しました。[  ]->[  ]
systemModule の全てのカウンターを無効化しました。[ 1 ]->[  ]
threadPoolModule の全てのカウンターを無効化しました。[ 4 ]->[  ]
transactionModule の全てのカウンターを無効化しました。[ 4,16,14 ]->[  ]
webAppModule の全てのカウンターを無効化しました。[ 13,11 ]->[  ]
ardModule の全てのカウンターを無効化しました。[  ]->[  ]
webServicesModule の全てのカウンターを無効化しました。[  ]->[  ]
wlmModule の全てのカウンターを無効化しました。[  ]->[  ]
wsgwModule の全てのカウンターを無効化しました。[  ]->[  ]
xdProcessModule の全てのカウンターを無効化しました。[  ]->[  ]

connectionPoolModule の指定のカウンターを有効化しました。[  ]->[ 6,5,2,1,8,13 ]
j2cModule の指定のカウンターを有効化しました。[  ]->[ 6,5,2,1,8,13 ]
servletSessionsModule の指定のカウンターを有効化しました。[  ]->[ 7 ]
threadPoolModule の指定のカウンターを有効化しました。[  ]->[ 3,4 ]

構成を保管しました。アプリケーション・サーバーを再起動してください。

[/opt/IBM/WebSphere/AppServer9.0/profiles/AppSrv01]
```


### TPV ロギングの開始
wsadmin で jython スクリプト `tpvLogging.py` を実行するには、以下のオプションを指定します。

|オプション|説明|
|---|---|
|-lang jython|jython 言語を指定|
|-host (ホスト名)|アプリケーション・サーバーが稼働しているホストの名前|
|-port (ポート番号)|アプリケーション・サーバーの SOAP コネクターのポート番号|
|-f (スクリプトのパス)|`tpvLogging.py` のパス|
|(アプリケーション・サーバー名)|アプリケーション・サーバーの名前<br>(Base構成の場合は server1)|
|start または stop|TPV のロギングを開始する場合は start を、<br>停止する場合は stop を指定|

実行例は、以下の通りです。
TPV のロギングを開始すると、logs/tpv 内に `tpv_(アプリケーション・サーバー名)_??????_?.xml` というファイルが作成され、メトリックがロギングされます。

```bash:TPVロギングの開始
[/opt/IBM/WebSphere/AppServer9.0/profiles/AppSrv01]# bin/wsadmin.sh -lang jython -host localhost -port 8880 -f /work/py/tpvLogging.py server1 start
WASX7209I: ノード xxxxNode01 のプロセス "server1" に、SOAP コネクターを使用して接続しました。プロセスのタイプは UnManagedProcess です。
WASX7303I: 次のオプションはスクリプト環境に渡され、argv 変数に格納される引数として使用可能になります: "[server1, start]"

cell = xxxxNode01Cell
node = xxxxNode01
server = server1

TPV のロギングを開始します。
params = [UserPreferences: nodeName: xxxxNode01, serverName: server1, userId: tpvLogging, refreshRate: 60, bufferSize: 20, numLogFiles: 5, logFileSize: 104857600, loggingDuration: 172800, logFileName: tpv, viewLog: false, tpvLogFormat: xml]
TPV のロギングを開始しました。

[/opt/IBM/WebSphere/AppServer9.0/profiles/AppSrv01]# ls logs/tpv
合計 40
drwxr-xr-x    8 root           4096 May 11 08:17 ..
drwxr-xr-x    2 root            256 May 11 08:17 .
-rw-r--r--    1 root          12626 May 11 08:17 tpv_server1_1683760623533_1.xml
[/opt/IBM/WebSphere/AppServer9.0/profiles/AppSrv01]#
```


### TPV ロギングの停止
jython スクリプト `tpvLogging.py` のオプションに stop を指定して実行すると、TPV ロギングが停止します。

実行例は、以下の通りです。
TPV のロギングを停止すると、logs/tpv 内の `tpv_(アプリケーション・サーバー名)_??????_?.xml` は zip ファイルに圧縮されます。

```bash:TPV ロギングの停止
[/opt/IBM/WebSphere/AppServer9.0/profiles/AppSrv01]# bin/wsadmin.sh -lang jython -host localhost -port 8880 -f /work/py/tpvLogging.py server1 stop
WASX7209I: ノード xxxxNode01 のプロセス "server1" に、SOAP コネクターを使用して接続しました。プロセスのタイプは UnManagedProcess です。
WASX7303I: 次のオプションはスクリプト環境に渡され、argv 変数に格納される引数として使用可能になります: "[server1, stop]"

cell = xxxxNode01Cell
node = xxxxNode01
server = server1

TPV のロギングを停止します。
params = [UserPreferences: nodeName: xxxxNode01, serverName: server1, userId: tpvLogging, refreshRate: 60, bufferSize: 20, numLogFiles: 5, logFileSize: 104857600, loggingDuration: 172800, logFileName: tpv, viewLog: false, tpvLogFormat: xml]
TPV のロギングを停止しました。

[/opt/IBM/WebSphere/AppServer9.0/profiles/AppSrv01]# ls -al logs/tpv
合計 24
drwxr-xr-x    8 root           4096 May 11 08:17 ..
-rw-r--r--    1 root           7080 May 11 08:18 tpv_server1_1683760623533_1.zip
drwxr-xr-x    2 root            256 May 11 08:18 .
[/opt/IBM/WebSphere/AppServer9.0/profiles/AppSrv01]#
```


## ND (Network Deployment) 構成での実行
次に、ND 構成で実行する場合を説明します。


### PMI カスタム統計セットの設定
カスタム統計セットを設定するために、jython スクリプト `pmiSetupForND.py` を実行します。
このスクリプトは構成作業として最初に１回実行することなります。

wsadmin で jython スクリプト `pmiSetupForND.py` を実行するには、以下のオプションを指定します。

|オプション|説明|
|---|---|
|-lang jython|jython 言語を指定|
|-host (ホスト名)|Deployment Manager が稼働しているホストの名前|
|-port (ポート番号)|Deployment Manager の SOAP コネクターのポート番号|
|-f (スクリプトのパス)|`pmiSetupForND.py` のパス|
|(ノード名)|アプリケーション・サーバーが存在するノードの名前|
|(アプリケーション・サーバー名)|アプリケーション・サーバーの名前|

動作は Base 構成の場合と同様なので、実行例の掲載は省略します。
設定を反映するには、構成を同期化し、アプリケーション・サーバーを再起動する必要があります。


### TPV ロギングの開始/停止
ND 構成の場合は、対象のアプリケーション・サーバーが稼働しているノード上の **Node Agent に接続**して jython スクリプト `tpvLogging.py` を実行します。
つまり、wsadmin で jython スクリプト `tpvLogging.py` を実行する際に、以下のようにオプションを指定します。

|オプション|説明|
|---|---|
|-lang jython|jython 言語を指定|
|-host (ホスト名)|アプリケーション・サーバーが稼働しているホストの名前<br>(Node Agentが稼働しているホストの名前)|
|-port (ポート番号)|**Node Agent** の SOAP コネクターのポート番号|
|-f (スクリプトのパス)|`tpvLogging.py` のパス|
|(アプリケーション・サーバー名)|アプリケーション・サーバーの名前|
|start または stop|TPV のロギングを開始する場合は start を、<br>停止する場合は stop を指定|

動作は Base 構成の場合と同様なので、実行例の掲載は省略します。


## 終わりに
TPV のロギングを開始/停止する jython スクリプトと、PMI のカスタム統計セットを設定する jython スクリプトの紹介でしたがいかがでしたでしょうか。
実運用で使用する場合は、アプリケーション・サーバーの起動完了後に TPV のロギングを開始し、アプリケーション・サーバーの停止前に TPV のロギングを停止することになるかと思います。
tWAS もまだまだ現役で使用されているようなので、何かのお役に立てば幸いです。