「BOM for Windows Ver.8.0」（以下、BOM）の「カスタム監視」を使用すると、BOM標準の監視設定にはない、独自の監視を行えます。 製品コラムではこれまで、PowerShellスクリプトを利用して実現した、さまざまなカスタム監視項目を紹介しました。今回は、BOMの利用者が独自にカスタム監視項目を作成できるように、具体的な設定のベストプラクティスを紹介します。

カスタム監視項目とは

　BOMのカスタム監視項目を使用すると、任意の外部プログラムを定期的に実行して、プログラムからの戻り値（監視値、終了コード、メッセージなど）を取得し、その監視値をBOMでしきい値に基づいてそのステータスを監視することができます（画面1）。BOMは「サービス監視」「プロセッサ監視」「メモリ監視」「プロセス監視」「イベントログ監視」など、さまざまな監視項目を提供していますが、標準の監視項目で対応できない監視方法については、カスタム監視項目を使用して柔軟に対応できます。

画面1　BOMのカスタム監視項目

指定可能なプログラムと指定方法

　カスタム監視項目で実行可能なプログラムは、コンソールアプリケーション（.exe）とバッチファイル（.bat、.cmd）です。プログラムにスクリプト実行エンジンとして「cmd.exe」、「cscript.exe」（Windows Script Host《WSH》のコンソールホスト）、「powershell.exe」（Windows PowerShell 5.1）または「pwsh.exe」（クロスプラットフォームの.NET版PowerShell）を指定し、その引数として、スクリプト（.vbs、.js、.ps1など）やコマンドプロンプトのコマンドラインや、PowerShellのスクリプトブロックを記述することもできます。いずれの場合も、標準出力に監視値が正しく出力できれば監視可能です。

プログラムの指定方法:

　目的の監視値だけを返す都合の良いコンソールアプリケーションは、独自に開発しない限り存在しないでしょう。そのため通常は、バッチファイルやスクリプトを利用することになります。例えば、バッチファイルであれば「echo <値>」や「type <値を含むファイル>」、WSHスクリプトであれば「WScript.Echo <値>」、PowerShellスクリプトであれば値を含むオブジェクト、「Write-Host <値>」、「Write-Output <値>」 、「return <値>」、「Get-Content <値を含むファイル>」 などの方法で監視値をBOMに返します。

　バッチファイルとスクリプトでは、スクリプトのほうが柔軟性が高く、複雑な処理を実装できます。特に、PowerShellはWindows ServerやWindowsのシステム管理を得意としています。PowerShell登場以前は、WSHスクリプトがシステム管理に人気があり、多用されていました。しかし、WSHスクリプトとしてよく利用されるVBScript（.vbs）は、既に非推奨となり、将来の廃止が決まっています（時期は未定）。WSHスクリプトとしては、JScript（.js）も利用できますが、JScriptはMicrosoftによるJavaScriptの古い実装であり、ほとんど使われてこなかったはずです。

ITニュース. VBScript廃止までのタイムライン発表｜かつて山市良とよばれたおじさんのブログ（2024年05月24日配信）

　Windows Serverでは、Windows PowerShell 5.1（powershell.exe）とPowerShell（pwsh.exe）の2つのPowerShellのいずれかをスクリプト実行エンジンとして利用できます。このうちWindows Serverに標準搭載されているのは、Windows PowerShell 5.1です。一方、新しい.NET版のPowerShell（pwsh.exe）は、利用するために事前にWindows Serverにインストールしておく必要があります。Windows PowerShell 5.1は開発が終了しており、汎用スクリプトにはPowerShell（pwsh.exe）が推奨されています。しかし、オンプレミスのWindows Serverの管理には、Windows PowerShell 5.1で十分です。また、Windows PowerShell 5.1でなければ利用できない、レガシなPowerShellモジュールもまだまだ存在するため、そういったPowerShellモジュールを利用する場合はWindows PowerShell 5.1を使用するほうが安全です。

戻り値の要件

 　カスタム監視項目は、戻り値として監視値（標準出力の値）、終了（EXIT）コード、エラーが発生した場合はエラーコードとエラーメッセージを取得します。正しく監視するには、プログラムの実行が成功（終了コード0）し、その監視値が正の整数値（64ビット符号なし整数《UINT64》）である必要があります。負の整数値は扱えません。一部の言語では、-1を失敗とするのが一般的あるいは慣例になっていることがありますが、BOMの監視値として-1を返すと、巨大な整数値（UINT64の最大値）となってしまい、大きい値をしきい値で危険としている場合は危険ステータスになってしまうので注意してください。

　また、小数点を含む正の実数（1.1など）は小数点以下が切り捨てられます。カスタム監視項目では、単一の監視値が返ってくることを想定していますが、複数の値が返ってくる場合は最初の値のみが監視値として扱われます。 例えば、WSHスクリプトに//NoLogoオプションを付けないと、最初に表示されるロゴ（Microsoft (R) Windows Script Host Version 10.0 Copyright (C) Microsoft Corporation. All rights reserved.）により、プログラムの実行は失敗として扱われます。戻り値とステータス、監視値のいくつかのパターンを以下の表にまとめました。

戻り値とステータス、値:

画面2　負の整数値が64ビット符号なし整数（UINT64）として扱われた結果、-1は巨大な数値（UINT64の最大値）になってしまう

画面3　文字列は取得値として使用できない。文字列が返ってきた場合、ステータス「正常」、値「(N/A)」になる

画面4　プログラムの実行失敗やスクリプト内で発生したエラー、スクリプトの0以外の終了コードは、ステータス「失敗」、値「(N/A)」に

プログラムの実行アカウント

　カスタム監視項目で指定したプログラムは、既定では、BOMインストール後の初期設定ウィザードで指定した監視対象のインスタンスの監視に利用するアカウントの権限で実行されます。BOMのローカル監視の既定はローカルシステムアカウント（NT AUTHORITY￥SYSTEM）です。代理監視の場合は、監視元と共通の名前とパスワードを持つ監視対象のローカルユーザーアカウント、またはActive Directoryのドメインユーザーアカウントになります。

　カスタム監視項目のプロパティの「拡張設定」タブでは、プログラムを実行する「実行ユーザーアカウント」としてローカルまたはドメインユーザーアカウントの資格情報（ユーザー名、ドメイン名、パスワード）を指定することができます（画面5）。

画面5　カスタム監視項目のプログラムを実行する「実行ユーザーアカウント」を設定できる

　なお、カスタム監視項目の「設定」タブにある「テスト」ボタンのクリックによる実行は、「拡張設定」タブ で実行ユーザーアカウントを明示的に設定していない限り、常にローカルシステムアカウント（NT AUTHORITY￥SYSTEM）の権限で実行されることに留意してください。実行アカウントが異なる場合、ユーザープロファイルやユーザー環境変数の違い（ローカルシステムアカウントの%TEMP%はC:￥Windows￥Tempなど） の影響で、テスト実行時のプログラムの挙動と、監視時のプログラムの挙動が違ってくる場合があります。

バッチファイルの実装例（設定は簡単だけど、バッチを書くのが難）

　バッチファイル（.bat、.cmd）によるカスタム監視項目の一例を紹介します。次のバッチファイル「getlogonusers.bat」は、quserコマンドを実行し、ヘッダー（英語コードページでは1行、日本語コードページでは2行）を引いた行数をログオン中のユーザー数として返します。ログオン中のユーザーがいない場合は標準出力には何も返ってこない（「* に対するユーザーは存在しません。」エラーになる）ため、ヘッダー行を引いてマイナスになる場合は0を返します。

[getlogonusers.bat]（プレーンテキストで表示、ダウンロード）

　バッチファイルはプログラムのテキストボックスに直接指定できるので、バッチファイルさえ用意できればカスタム監視項目の設定は簡単です（画面6）。「設定」タブにある「テスト」ボタンをクリックすると、すぐに実行を開始し、取得される戻り値を確認できます。

画面6　バッチファイルを利用したログオン中のユーザー数の監視。プログラム「cmd.exe」、引数「/c "バッチファイルのパス"」のように指定することも可能

　バッチファイルは実行する複数のコマンドを書き込んで、連続で実行するという目的には、簡単で便利に利用できます。しかし、監視したい値を取得して返すバッチファイルを正しく書くのはハードルが高いかもしれません。汎用スクリプトに強い、強力なスクリプト環境であるPowerShellのほうが、カスタム監視項目には適しています。

PowerShellスクリプトの実装例（カスタム監視の推奨）

　スクリプト言語および実行エンジンとしてのPowerShellは、システムの管理を自動化するために一般的に使用されています。Windows Serverの多くのGUI管理ツールも背後ではPowerShellで動いていたりします。標準のPowerShellモジュールで、OSの設定、パフォーマンスデータ、セキュリティ設定、イベントログにアクセスできるほか、サーバーの役割に対応したPowerShellモジュールにより、その管理機能は拡張されます。他の多くのスクリプト言語は、テキストだけを受け入れ返しますが、PowerShellは.NET Frameworkまたは.NETオブジェクトを受け入れて返します。

　Windows PowerShell 5.1はサポートされているWindows Serverで標準で利用できるため、BOMのカスタム監視項目で実行するスクリプトとして特に適しています。値の取得だけでなく、システム設定の変更も可能であるため、カスタムアクション項目に利用することもできます。

　PowerShellスクリプトによるカスタム監視の例として、Windows ServerおよびWindowsの「信頼性モニター」（perfmon /rel）の安定性指標を監視するPowerShellスクリプト「get-ReliabilityMetrics.ps1」と「get-ReliabilityMetrics2.ps1」を作成しました。

 [get-ReliabilityMetrics.ps1]（プレーンテキストで表示、ダウンロード） 

  [get-ReliabilityMetrics2.ps1]（プレーンテキストで表示、ダウンロード） 

　「get-ReliabilityMetrics.ps1」は、直近の（最後の監視間隔の1時間）安定性指標を整数値で返します。信頼性モニターの安定性指標は過去1か月、1時間ごとに1～10（10が最も安定）の値（合計720の値） で安定性を示します。スクリプトは、その最後の値を取得し、小数点以下の切り捨てにより下がってしまう粒度の問題に対処するため、値を10倍してから四捨五入して返します（画面7）。つまり、スクリプトが返す監視値は10～100となります。

画面7　信頼性モニターの直近1時間の監視期間の安定性指標を示すスクリプト（値は10倍にして四捨五入）

　「get-ReliabilityMetrics2.ps1」は、「get-ReliabilityMetrics.ps1」の機能にテキストログ出力機能を加えたものです。「信頼性モニター」の下部に「信頼性の詳細の表示」には、安定性に関係する情報/重要/警告イベントが表示されます。スクリプトの引数としてテキストファイルのパスを指定して実行すると、これらのイベントのうち、直近の監視期間の間に記録されたものをテキストファイルに出力します（画面8）。引数にテキストファイルのパスが指定されない場合、テキストファイルへの出力は行いません。

画面8　安定性指標の値（10倍の値）に加え、期間中に記録されたイベントをテキストファイルに出力するスクリプト

　安定性指標の取得には、WMI（Windows Management Instrumentation）の「Win32_ReliabilityStabilityMetrics」クラスを、イベントの取得には「Win32_ReliabilityRecords」クラスを使用しました。

Win32_ReliabilityStabilityMetrics class｜ReliabilityMetricsProvider Provider（Microsoft Learn）
Win32_ReliabilityRecords class｜ReliabilityMetricsProvider Provider（Microsoft Learn）

　「get-ReliabilityMetrics2.ps1」をカスタム監視項目に設定するには、プログラムとして「powershell.exe」を指定し、引数に「-ExecutionPolicy Bypass -File "スクリプトのパス" "テキストファイルの出力先パス"」のように設定します。安定性指標の10倍の値が返ってくるため、しきい値としては注意「70より小さい」、危険「30より小さい」とすればよいでしょう。テキストファイルのパスを省略すれば、「get-ReliabilityMetrics.ps1」と同じように動作します。

エラー処理のヒント

　バッチファイルやスクリプトで適切なエラーハンドリングを行うことは重要です。最終的に、有効な監視値を返せない場合は、0以外の終了コードで終了して、カスタム監視項目のステータスを「失敗」にし、値を「(N/A)」にすることをお勧めします。バッチファイルの場合は、「exit 1（または0以外の数字）」 または「exit /b 1（または0以外の数字）」でバッチファイルを終了させます）。WSHスクリプトの場合は「WScript.Quit(1または0以外の数字);」、PowerShellスクリプトの場合は「exit 1（または0以外の数字）」または「throw」（エラーコードは0x80004005《不明なエラー》、終了コードは1）で終了します（「get-ReliabilityMetrics.ps1」の例を参照）。

予約済み変数の活用

　カスタム監視項目の「設定」タブの「プログラム」および「引数」のテキストボックスには、パスの指定などにBOMの予約済み変数を使用できます。以下の表に、予約済み変数の一部を抜粋しました。予約済み変数は、BOMによる監視が実行される際に、実際の値に展開されます。カスタム設定では、スクリプトの配置場所やログファイルの出力先の場所のルールを決めておかないと、さまざまな場所に分散してしまう可能性があります。予約済み変数を使用すると、ルールに基づいた配置を徹底できるというメリットがあります。

※カスタム監視項目の「設定」タブにある「テスト」ボタンによるテスト実行では、予約済み変数は使用できないことに注意してください（実際の値に展開されず、予約済み変数の文字列そのままが渡されます）。

予約済み変数（一部抜粋）:

※すべての予約済み変数の一覧は、「BOM for Windows Ver.8.0 ユーザーズマニュアル（say-tech.co.jp）」の「第14章 予約済み変数」で確認できます。

　画面9は、スクリプトの格納場所として「$(DataDir)￥custom_scripts」を使用し、テキストファイルの出力先のパスとして「$(DetectedDataDir)￥$(MonitorID).txt」を、予約済み変数を使用して指定した例です。引数に予約済み変数を使用する場合は、この例のように空白の存在で引数が分割されてしまうことを防止するため、ダブルコーテーション（""）やシングルコーテーション（''）で囲んでください。

画面9　BOMの予約済み変数を使用したプログラム「get-ReliabilityMetrics2.ps1」の設定例

　このように予約済み変数を使用することで、バッチファイルやスクリプトの配置場所をBOM関連のデータと同じ場所（の配下）にまとめることができます。「$(DataDir)￥support_scripts」には、BOMの製品やテンプレートに付属するスクリプトが格納されています。この例では、「$(DataDir)￥custom_scripts」を作成し、その中にカスタム監視項目で使用するスクリプトを配置しました。

　出力ファイルの場所とファイル名を「$(DetectedDataDir)￥$(MonitorID).txt」にすることで、BOMの標準の監視項目が収集データに使用するのと同じルールに則ったパスにファイルを格納することができ、別の監視設定とファイル名が重複することがなくなるという利点があります。また、「メール送信」アクション項目の添付ファイル設定に共通のパス指定を使えて便利です（画面10）。予約済み変数で指定されたパスとファイル名を含む「メール送信」は、別の監視項目にコピーすることで、添付ファイルのパスを変更しなくても対応できるからです。

画面10　「メール送信」アクション項目の添付ファイル設定と、実際に送信された添付ファイル付きメール

　最後に、予約済み変数を利用した、面白いカスタム監視項目の例を紹介します。次のPowerShellスクリプト「getnumoferror.ps1」は、引数に指定したイベントログのログ（System、Security、Application、Microsoft-Windows-NTLM/Operationalなど）に過去1時間に記録された重大（Critical、1）またはエラー（Error、2）レベルのログの数を返すスクリプトです。監視項目名をログ名にすることで、PowerShellスクリプトの引数を$(MonitorName)で渡すことができます。これにより、1つのカスタム監視項目を設定したら、それを次々にコピーして監視項目名だけを変更することで、複数の監視対象のプログラム設定およびしきい値設定を共通化できます（画面11）。

  [getnumoferror.ps1]（プレーンテキストで表示、ダウンロード）  

画面11　$(MonitorName)（監視項目名）を引数にすることで、共通のプログラム設定で異なる対象（この例ではログ名）を監視させる例