スクリプトを使用したモニタリング拡張機能の作成

モニタリング拡張スクリプト（別名、カスタムモニターまたはハードウェアモニター）を作成して、Splunk AppDynamics がすでに収集してコントローラにレポートしているメトリックセットにカスタムメトリックを追加できます。スクリプトは、1 分ごとにカスタムメトリックをマシンエージェントに報告します。マシンエージェントは、これらのメトリックをコントローラに渡します。

このページでは、シェルスクリプトを使用してカスタムメトリックを追加する手順について説明します。この手順には例が含まれます。

既存の拡張機能の確認

独自の拡張機能を作成する前に、作成され、Splunk AppDynamics コミュニティのメンバー間で共有されている拡張機能を確認してください。新しい拡張機能が継続的に追加されています。他のユーザが必要なもの、または必要なものに近いものをすでに作成している可能性があります。必要なものに近いものをダウンロードし、変更をいくつか加えれば使用できる場合があります。

無料ダウンロードについては、製品ページを参照してください。

モニタリング拡張機能の作成

スクリプトを使用してモニタリング拡張機能を作成するには、次のようにします。

  1. スクリプトを作成します。「スクリプトファイルの作成」を参照してください。
  2. monitor.xml 構成ファイルを作成します。「monitor.xml ファイルの作成」を参照してください
  3. <machine_agent_home>/monitors にサブディレクトリ <your_extension_dir> を作成します。「マシンエージェントのモニターディレクトリの下にディレクトリを作成する」を参照してください。
  4. スクリプトファイルと monitor.xml をコピーします。
  5. マシンエージェントを再起動します。

メトリックの定義

メトリック名は、同じメトリックパス内で一意である必要がありますが、メトリック階層全体に対して一意である必要はありません。メトリックブラウザに表示されるときに名前全体が表示されるように、短いメトリック名を使用することを推奨します。メトリックをコントローラにアップロードするときにメトリック名の前にメトリックパスを付加します。

注: メトリックパスを含める際は、カスタムメトリックの末尾に垂直バー（パイプ記号）を含めないでください。

メトリック処理修飾子

コントローラには、メトリックの処理方法（集約、時間ロールアップ、および階層ロールアップ）を示すさまざまな修飾子があります。メトリック修飾子には、次の 3 つのタイプがあります。

  1. アグリゲータ修飾子
  2. 時間ロールアップ修飾子
  3. クラスタロールアップ修飾子

スクリプトで、メトリックの名前と値のペアの後にメトリック修飾子を指定します。スクリプトファイル内の一般的なメトリックエントリは、次のような構造です。

name=<metric name>,value=<long value>,aggregator=<aggregator type>, time-rollup=<time-rollup strategy>, cluster-rollup=<cluster-rollup strategy>

アグリゲータ修飾子

集約修飾子では、1 分間にレポートされた値をマシンエージェントでどのように集約するかを指定します。集約修飾子は、aggregator="aggregator type" のように指定します。 この値は列挙型です。その 1 分の間に値がレポートされない場合、コントローラにはデータはレポートされず、そのメトリックについてマシンエージェントログに UNCHANGED 通知が表示されます。有効な値は次のとおりです。
アグリゲータタイプ 説明

AVERAGE

（デフォルト）その 1 分にレポートされたすべての値の平均

SUM

その 1 分にレポートされたすべての値の合計。これにより、メトリックはカウンタと同様に動作します

OBSERVATION

その 1 分にレポートされた最後の値

時間ロールアップ修飾子

時間ロールアップ修飾子では、時間が経過して 1 分単位のテーブルから 10 分単位のテーブル、および 60 分単位のテーブルに変換するときに、コントローラで値をどのようにロールアップするかを指定します。値は列挙型です。有効な値は次のとおりです。

ロールアップ戦略 説明

AVERAGE

1 分間のすべての値の平均（10 分単位のテーブルに追加する場合）。または 10 分間のすべての値の平均（60 分単位のテーブルに追加する場合）

SUM

1 分間のすべての値の合計（10 分単位のテーブルに追加する場合）。または 10 分間のすべての値の合計（60 分単位のテーブルに追加する場合）

CURRENT

その 10 分間隔で最後にレポートされた 1 分間の値。またはその 60 分間隔で最後にレポートされた 10 分間の値

クラスタロールアップ修飾子

クラスタロールアップ修飾子では、コントローラで階層（ノードのクラスタ）内のメトリック値をどのように集約するかを指定します。値は列挙型です。有効な値は次のとおりです。

ロールアップ戦略 説明

個人

階層内の各ノードでのメトリック値を平均して、メトリック値を集計します

COLLECTIVE

階層内のすべてのノードのメトリック値を合計して、メトリック値を集計します

たとえば、階層に 2 つのノード、ノード A とノード B があり、ノード A に 1 分あたり 3 個のエラーがあり、ノード B に 1 分あたり 7 個のエラーがある場合、INDIVIDUAL 修飾子では 1 分あたり 5 個のエラーが値としてレポートされ、COLLECTIVE 修飾子では 1 分あたり 10 個のエラーがレポートされます。INDIVIDUAL は、各ノードの値が必要な CPU 使用率（% CPU Busy）などのメトリックに適しています。COLLECTIVE は、階層全体の値が必要なコール数（Number of Calls）などのメトリックに適しています。

モニタリング拡張スクリプトの追加

モニタリング拡張スクリプトを追加するには、次のようにします。

マシンエージェントのモニタディレクトリの下へのサブディレクトリの作成

<machine_agent_home>/monitors ディレクトリは、マシンエージェントの拡張機能のリポジトリです。新しい拡張機能ごとに、/monitors ディレクトリの下にサブディレクトリを作成します。エージェントを実行するユーザには、このサブディレクトリに対する読み取り、書き込み、および実行権限が必要です。

たとえば、JVM で開いているファイルをモニタする拡張機能を作成するには、<machine_agent_home>/monitors の下に "openfiles" という名前のサブディレクトリを作成します。構造は次のようになります。

マシンエージェントのサブディレクトリ

スクリプトファイルの作成

スクリプトは、STDOUT にデータを書き込みます。マシンエージェントは、STDOUT を解析して、1 分ごとにコントローラに情報を送信します。スクリプトファイルを作成するには、次の手順を使用します。

注:

Windows カスタムメトリックの場合、.bat ファイルよりも PowerShell と VBScript が推奨されます。

Windows でカスタムメトリックを生成する場合、.bat ファイルの代わりに PowerShell スクリプトおよび VBasic スクリプトを使用することを推奨します。標準の Windows バッチ（.bat）スクリプトでメトリック名をエコーすると、名前が引用符で囲まれます。引用符が原因で、マシンエージェントはこれらのメトリックを無視します。PowerShell スクリプトと VBasic スクリプトにはこの問題はありません。

  1. メトリックの name-value ペアを指定します。各メトリックには、java の 'long' 値に変換される name-value ペアがあります。スクリプトファイル内の一般的なメトリックエントリは、次のような構造です。
    name=<metric name>,value=<long value>,aggregator=<aggregator type>, time-rollup=<time-rollup strategy>, cluster-rollup=<cluster-rollup strategy>
    フォーム形式

    標準形式

    Hardware Resources| Instrument Name=Instrument Value

    完全修飾形式

    Hardware Resources| <metric name>,value=<long value>

  2. メトリックのカテゴリを定義します。次に例を示します。

    1. インフラストラクチャ（デフォルトのハードウェアメトリックについては、「マシンエージェント」を参照してください）。

    2. JVM

    3. カスタム指標：カスタム指標には、パスのプレフィックスが必要です。

      - カスタム指標

      - サーバー|コンポーネント：<tier-name-or-tier-id>

  3. カスタム メトリック プレフィックスが付加されたメトリックは、アプリケーション内のすべての階層で共通です。Server|Component:<tier-name-or-tier-id> プレフィックスが付加されたメトリックは、指定の階層の下にのみ表示されます。

    階層のコンポーネント ID を見つけるには、その階層に対してダッシュボードを開き、URL を確認します。ID は、URL のコンポーネント値として表示されます。

    警告: マシンエージェントは、メトリックのターゲットまたは宛先に関連付けられている必要があります。マシンエージェントに関連付けられていない階層にメトリックを公開しようとしても、そのメトリックはレポートされません。

    「|」文字は、メトリック階層内のブランチを分離し、メトリックツリー内でのメトリックの表示位置をコントローラに伝えます。

    Custom Metrics|Hardware Resources|Disks|Total Disk Usage %
Custom Metrics|Hardware Resources|Disks|Disk 1|Current Disk Usage %

    既存のタイプのメトリックの次にカスタムメトリックを挿入できます。たとえば、次の宣言により、pool usage という名前のカスタムメトリックが JMX metrics:Server|Component:18|JMX|Pool|First|pool usage の次に表示されます。

  4. その後、このメトリックを、他のタイプの JMX メトリックと同様に、正常性ルールで使用できます。同じスクリプトファイルを使用して複数のメトリックをモニターするには、スクリプトを編集してメトリックごとに異なる行が STDOUT に書き込まれるようにします。例：
    name=Custom Metrics|Hardware Resources|Disks|Total Disk Usage %, value=23
name=Custom Metrics|Hardware Resources|Disks|Disk 1|Current Disk Usage %, value=56

ステップ 1 で作成したサブディレクトリへのスクリプトファイルのコピー

エージェントプロセスに、スクリプトファイルに関する実行権限と、ファイルの内容に関する実行権限があることを確認します。

monitor.xml ファイルの作成

カスタムモニタリング拡張スクリプトごとに、monitor.xml ファイルを作成します。monitor.xml ファイルで、ステップ 2 で作成したスクリプトファイルを実行します。次のサンプルファイルを編集して、独自のファイルを作成できます。

<monitor>
<name>HardwareMonitor</name>
<type>managed</type>
<description>Monitors system resources - CPU, Memory, Network I/O, and Disk I/O.</description>
<monitor-configuration>     </monitor-configuration>
<monitor-run-task>
<!--  Edit execution-style as needed. -->
<execution-style>continuous</execution-style>
<name>Run</name>
<type>executable</type>
<task-arguments></task-arguments>
<executable-task>
<type>file</type>
<!--  Use only one file element per os-type. -->
<file os-type="linux">linux-stat.sh</file>
<file os-type="mac">macos-stat.sh</file>
<file os-type="windows">windows-stat.bat</file>
<file os-type="solaris">solaris-stat.sh</file>
<file os-type="sunos">solaris-stat.sh</file>
<file os-type="aix">aix-stat.sh</file>
</executable-task>
</monitor-run-task>
</monitor>

os-type 属性は、executable-task ファイル要素のオプションです（1 つの os-type のみ指定されている場合）。1 つの monitor.xml ファイルで、os-type ごとに 1 つのスクリプトを実行します。

  1. 実行スタイル（continuous または periodic）を選択します。
    実行形式説明例

    continuous

    一定期間のデータ収集を平均する必要がある場合は、continuous を選択します。たとえば、1 分間の平均 CPU 使用率に使用します。モニターを「continuous」として宣言する場合、スクリプトも無限ループで実行する必要があります。これにより、マシンエージェントプロセスが終了するまで、スクリプトは継続して実行されます。

    while [ 1 ]; do...実際のスクリプトがここに入ります...sleep 60done

    periodic

    システム パフォーマンス カウンタからデータを定期的にレポートするには、periodic を選択します。periodic タスクは、デフォルトで 1 分ごとに実行され、データが集約されます。

    異なる頻度を指定するには、execution-frequency-in-seconds 要素を使用します。実行頻度は 60 未満にする必要があります。periodic 実行形式の場合、タイムアウト設定を指定することもできます（例に示しています）。

    <monitor-run-task>

    ...

    <execution-style>periodic</execution-style> <execution-frequency-in-seconds>30</execution-frequency-in-seconds> <execution-timeout-in-secs>30</execution-timeout-in-secs>

    ...

    </monitor-run-task>

    注: <execution-frequency-in-seconds> を 300 秒（5 分）よりも大きい値に設定しないでください。拡張機能では、少なくとも 5 分ごとにメトリックを収集する必要があります。
  2. スクリプトファイルの名前を monitor.xml ファイルの <file> 要素に追加します。必ず正しい os-type 属性を使用してください。os-type 値は、System.getProperty("os.name") の呼び出しから返された値と一致する必要があります。 
    <file os-type="your-os-type">{script file name}</file>

    スクリプトの相対パスまたは絶対パスのいずれかを使用できます。

ステップ 1 で作成したサブディレクトリへの monitor.xml ファイルのコピー

マシンエージェントの再起動

注:

必須のエージェントプロパティ

controller-info.xml ファイルおよびコマンドラインのエージェントの start コマンドで、エージェントが正しく設定されていることを確認します。「データベースエージェントの構成プロパティ」を参照してください。

マシンエージェントを再起動すると、ログファイルに次のメッセージが表示されます。

Executing script [<script_name>] on the console to make sure your changes work with the machine agent.

モニタリング拡張スクリプトの実行の確認

拡張機能の実行を確認するには、少なくとも 1 分間待ってから、メトリックブラウザでメトリックデータを確認します。

これらのメトリックのいずれかに基づいてアラートを作成できるようになりました。

例：UNIX でのオープンファイル用のモニタリング拡張機能の作成

JVM のすべてのオープンファイルをモニタするためのカスタムモニタを作成するには、次の手順を実行します。

  1. カスタムモニタリポジトリに新しいディレクトリを作成します。

  2. 特定のプロセス名（たとえば、Author、Publish など）に対応するようにこの UNIX スクリプトを変更して、スクリプトファイルを作成します。

    lookfor="<process name 1>"
pid=`ps aux | grep "$lookfor" | grep -v grep | tr -s " " | cut -f2 -d' '`
count1=`lsof -p $pid | wc -l | xargs`
lookfor="<process name 2>"
pid=`ps aux | grep "$lookfor" | grep -v grep | tr -s " " | cut -f2 -d' '`
count2=`lsof -p $pid | wc -l | xargs`
echo "name=JVM|Files|<process name 1>,value="$count1
echo "name=JVM|Files|<process name 2>,value="$count2

  3. 次の monitor.xml ファイルを作成し、ステップ 2 で示した UNIX スクリプトをポイントします。

    <monitor>
<name>MyMonitors</name>
<type>managed</type>
<description>Monitor open file count </description>
<monitor-configuration>
</monitor-configuration>
<monitor-run-task>
<execution-style>continuous</execution-style>
<name>Run</name>
<type>executable</type>
<task-arguments>
</task-arguments>
<executable-task>
<type>file</type>
<file>openfilecount.sh</file>
</executable-task>
</monitor-run-task>
</monitor>

Example: Create a Monitoring Extension to Check Process Status in Windows

  1. Create a new directory in the custom monitor repository.

  2. Create the script file by modifying this Windows PowerShell script for the specific process name (for example: Author, Publish, and so on). The following Windows PowerShell script checks if a process instance is running on the machine.

    注: To generate custom metrics on Windows, we recommend that you use PowerShell and VBasic scripts instead of .bat files.When a standard Windows batch (.bat) script echoes metric names, it surrounds the names with quotes. The quotes will cause the Machine Agent to ignore these metrics. PowerShell and VBasic scripts do not have this issue.
    $procName='<PROCESS_NAME>'
$procStatus=Get-Process -Name $procName -ErrorAction SilentlyContinue
if($procStatus) {
write-output "name=Custom Metrics|Process|$procName|Running, value=1"
} else {
write-output "name=Custom Metrics|Process|$procName|Running, value=0"
}

  3. Create the following monitor.xml file and point it to the Windows PowerShell script shown in Step 2. If you experience an error, try Example: Run Machine Agent Custom Extensions with Customized Commands and Arguments.

    <monitor>
<name>MyMonitors</name>
<type>managed</type>
<description>Monitor open file count </description>
<monitor-configuration>
</monitor-configuration>
<monitor-run-task>
<execution-style>continuous</execution-style>
<name>Run</name>
<type>executable</type>
<task-arguments>
<argument name="" default-value="-Command"></argument>
<argument name="" default-value="C:\\absolute\\path\\to\\powershell\\script\\mp.ps1"></argument>
</task-arguments>
<executable-task>
<type>command</type>
<command>C:\\absolute\\path\\to\\powershell\\executable\\powershell.exe</command>
</executable-task>
</monitor-run-task>
</monitor>

If you have provided the PowerShell program for the Machine Agent and are unable to see custom metrics, follow these steps:

  1. Create a .bat file in the same folder where you created the PowerShell script and monitor.xml file.

    Example .bat file
    process_checker.bat

  2. Add the following lines of code into the .bat file. Ensure that you are using the correct PowerShell script file name. In this example, the PowerShell script file name is process_status_checker.ps1.

    @echo off
Powershell.exe -executionpolicy remotesigned -File process_status_checker.ps1

  3. Add the following lines of code to the monitor.xml file. Ensure that you are using the correct .bat file name. In this example, the .bat file name is process_checker.bat.

    <monitor>
<name>MyMonitors</name>
<type>managed</type>
<description>Monitor process status</description>
<monitor-configuration>
</monitor-configuration>
<monitor-run-task>
<execution-style>periodic</execution-style>
<execution-frequency-in-seconds>60</execution-frequency-in-seconds>
<execution-timeout-in-secs>60</execution-timeout-in-secs>
<name>MyMonitors</name>
<type>executable</type>
<task-arguments></task-arguments>
<executable-task>
<type>file</type>
<file os-type=“windows”>process_checker.bat</file>
</executable-task>
</monitor-run-task>
</monitor>

例：カスタマイズされたコマンドと引数を使用してマシンエージェントのカスタム拡張機能を実行

デフォルトでは、マシンエージェントはシェルスクリプトとして bash シェルスクリプトを実行します。この例は、bash シェルスクリプトを bash スクリプトとして実行する方法を示します。

スクリプト example.sh では、以下の monitor.xml ファイルを作成するとスクリプトが ./example.sh として実行されます。 

<monitor>
<name>HardwareMonitor</name>
<type>managed</type>
<enabled>false</enabled>
<enable-override os-type="solaris">true</enable-override>
<enable-override os-type="sunos">true</enable-override>
<description>Monitors system resources - CPU, Memory, Network I/O, and Disk I/O.
</description>
<monitor-configuration>
</monitor-configuration>
<monitor-run-task>
<execution-style>continuous</execution-style>
<name>Run</name>
<type>executable</type>
<task-arguments>
</task-arguments>
<executable-task>
<type>file</type>
<file>example.sh</file>
</executable-task>
</monitor-run-task>
</monitor>

スクリプトを "bash example.sh" として実行するには、次の手順を実行します。

  1. 以下に示すように monitor.xml ファイルを変更します。<task-arguments> オプションと <executable-task> オプションは実装の変更に合わせて調整します。

    <monitor>
<name>ExampleMonitor</name>
<type>managed</type>
<enabled>true</enabled>
<description>Monitors system resources - CPU, Memory, Network I/O, and Disk I/O.
</description>
<monitor-configuration>
</monitor-configuration>
<monitor-run-task>
<execution-style>continuous</execution-style>
<name>Run</name>
<type>executable</type>
<task-arguments>
<argument name="arg1" is-required="true" default-value="example.sh"/>
</task-arguments>
<executable-task>
<type>command</type>
<command>bash</command>
<arguments-pattern>$arg1</arguments-pattern>
<wait-for-process-exit>true</wait-for-process-exit>
</executable-task>
</monitor-run-task>
</monitor>