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

アグリゲータ修飾子

時間ロールアップ修飾子

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

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

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

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

To add a monitoring extension script:

Create a Subdirectory Under the Machine Agent Monitors Directory

The <machine_agent_home>/monitors directory is the repository for the Machine Agent extensions. For each new extension, create a subdirectory under the /monitors directory. The user running the Agent requires read, write, and execute permissions to this subdirectory.

For example to create an extension that monitors open files in the JVM, create a subdirectory named "openfiles" under <machine_agent_home>/monitors. The structure looks like:

Create the Script File

A script writes data to STDOUT. The Machine Agent parses STDOUT and sends information to the Controller every minute. Use these instructions to create the script file:

1. Specify a name-value pair for the metrics.Each metric has a name-value pair that is converted to a java 'long' value. A typical metric entry in the script file has this structure:

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

   Form	Format
   Standard Form	Hardware Resources| Instrument Name=Instrument Value
   Fully Qualified Form	Hardware Resources| <metric name>,value=<long value>

2. Define the category of the metric, for example:

   1. Infrastructure (for the default hardware metrics, see Machine Agent)

   2. JVM

   3. Custom Metrics, where Custom Metrics must have the path prefixes:

      - Custom Metrics

      - Server|Component:<tier-name-or-tier-id>

3. Metrics with the Custom Metrics prefix are common across all tiers in your application. Metrics with the Server|Component:<tier-name-or-tier-id> prefix appear only under the specified tier.

   To find the component ID of a tier, open the dashboard for the tier and review the URL. The ID appears as the component value in the URL:

   

   Warning: The Machine Agent has to be associated with the target or destination for the metrics. If you attempt to publish metrics to a tier that is not associated with the Machine Agent, the metrics are not reported.

   The "|" character separates the branches in the metric hierarchy notifying the Controller where the metric should appear in the metric tree:

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

   You can insert a custom metric next to an existing type of metric. For example, the following declaration causes the custom metric named pool usage to appear next to the JMX metrics:Server|Component:18|JMX|Pool|First|pool usage

4. You can then use the metric in health rules as would other types of JMX metrics.To monitor multiple metrics with the same script file, edit the script to write a different line for each one to STDOUT. For example:

   name=Custom Metrics|Hardware Resources|Disks|Total Disk Usage %, value=23
   name=Custom Metrics|Hardware Resources|Disks|Disk 1|Current Disk Usage %, value=56

Copy the Script File to the Subdirectory Created in Step 1

Ensure that the Agent process has execute permissions for the script file and for the contents of the file.

Create the monitor.xml File

For each custom monitoring extension script, create a monitor.xml file. The monitor.xml file executes the script file created in Step 2. You can edit the following sample file to create your own file:

<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>

The os-type attribute is optional for the executable-task file element when only one os-type is specified. One monitor.xml file executes one script per os-type.

1. Select the execution style: continuous or periodic.

   Execution Style	Description	Example
   continuous	Select continuous if you want data collection averaged over time. For example, average CPU usage over a minute.For the monitor to be declared as 'continuous', the script should also run in an infinite loop. This ensures that the script keeps running until the Machine Agent process is terminated.	while [ 1 ]; do... the actual script goes here ...sleep 60done
   periodic	Select periodic to report data from system performance counters periodically. The periodic task runs every minute by default, and the data is aggregated. To specify a different frequency, use the execution-frequency-in-seconds element. The execution frequency must be less than 60. For periodic execution style, you can also specify the timeout setting (shown in the example).	<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>

   Note: Do not set the <execution-frequency-in-seconds> higher than 300 seconds (five minutes). The extension must collect metrics at least once every five minutes.
2. Add the name of your script file to the <file> element in the monitor.xml file. Be sure to use the correct os-type attribute. The os-type value should match the value returned from calling System.getProperty("os.name").

   <file os-type="your-os-type">{script file name}</file>

   You can use either the relative or absolute path of the script.

Copy the monitor.xml file to the Subdirectory Created in Step 1

Restart the Machine Agent

After restarting the Machine Agent, you should see following message in your log file:

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

Verify Execution of the Monitoring Extension Script

To verify the execution of extension, wait at least one minute and check the metric data in the Metric Browser.

You can now create alerts based on any of these metrics.