Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: DOCS-1536


The aggregator qualifier specifies how the Machine Agent aggregates the values reported during a one-minute period. Specify the aggregation qualifier as aggregator="aggregator type" This value is an enumerated type. If no value is reported during that minute, no data is reported to the controller, and an UNCHANGED notice appears in the Machine Agent log for that metric. Valid values are:

Aggregator Type



Default. Average of all reported values in that minute.


Sum of all reported values in the minute, causes the metric to behave like a counter.


Last reported value in the minute.

Time Roll Up Qualifier

The time-rollup qualifier specifies how the Controller rolls up the values when it converts from one-minute granularity tables to 10-minute granularity and 60-minute granularity tables over time. The value is an enumerated type. Valid values are:

Roll up Strategy



Average of all one-minute values when adding it to the 10-minute granularity table; average of all 10-minute values when adding it to the 60-minute granularity table.


Sum of all one-minute values when adding it to the 10-minute granularity table; sum of all 10-minute values when adding it to the 60-minute granularity table.


Last reported one-minute value in that 10-minute interval; last reported ten-minute value in that 60-minute interval.

Cluster Rollup Qualifier

The cluster-rollup qualifier specifies how the Controller aggregates metric values in a tier (a cluster of nodes). The value is an enumerated type. Valid values are:

Roll up Strategy



Aggregates the metric value by averaging the metric values across each node in the tier.


Aggregates the metric value by adding up the metric values for all the nodes in the tier.

For example, if a tier has two nodes, Node A and Node B, and Node A has 3 errors per minute and Node B has 7 errors per minute, the INDIVIDUAL qualifier reports a value of 5 errors per minute and and COLLECTIVE qualifier reports 10 errors per minute. INDIVIDUAL is appropriate for metrics such as % CPU Busy where you want the value for each node. COLLECTIVE is appropriate for metrics such as Number of Calls where you want a value for the entire tier.


  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 the following structure:

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

    Use the following 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 Standalone Machine Agent)
    2. JVM
    3. Custom Metrics
    Custom metrics must have the path prefixes:
    1. Custom Metrics
    2. Server|Component:<tier-name-or-tier-id>

    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 inspect the URL. The ID appears as the component value in the URL, as shown:


    Custom Metrics are currently not supported in dashboards.


    The Machine Agent has to be associated with the target/destination for the metrics. If you try to publish metrics to a Tier that is not associated with the Machine Agent, the metrics can not be reported.

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

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

    You can insert a custom metric alongside an existing type of metric. For example, the following declaration causes the custom metric named pool usage to appear alongside the JMX metrics:

    • Server|Component:18|JMX|Pool|First|pool usage

    The metric can then be used in health rules as would other types of JMX metrics.


  1. Select the execution style from one of the following:

    Execution Style




    Choose 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 Standalone Machine Agent process is terminated.

    while [ 1 ]; do
    ... the actual script goes here ...
    sleep 60


    Choose 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 as shown in the example.



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



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

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

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