Functions

IxoraRMS allows the user to create custom queries where performance counters can be processed through the use of functions. Functions can modify an existing counter or can create a virtual one by processing one or more existing counters. Below is a reference of the available functions:

op="script"

The most powerful function is the Script which allows you to use Java language syntax to process counters and return a result.

    <function op="script">

        <param id=""/>

        <code>java function body</code>

    </function>

The contents of the <code> tag are the body of a complete Java function, which means all arithmetical operators, conditional statements, loops and local variables are allowed. Code must return a value of type Double, or null, by using the return statement. If more exit points are present, all must follow the same rule.

Note that returning null has the significance of rejecting the current set of values, without sending any data to screen controls, effectively performing a filter.

Values for all resources specified through the <param> tag are available as local variables, named after their id. When id is not a valid Java identifier, names 'r0', 'r1' and so on will be used, with 'r0' identifying the first parameter.

Examples:

1. This is an example where the resource selector are defined without regular expressions. The function sums up processor user time and system (privileged) time and returns it as a third counter which will be displayed as 'Total Time'.

    <query>

        <resource id="user" rid="-/-/root/Processor/[% User Time]"/>

        <resource id="priv" rid="-/-/root/Processor/[% Privileged Time]"/>

        <function id="total" op="script" name="Total Time" description="Total processor time (user + system)">

            <param id="user"/>

            <param id="priv"/>

            <code>return user + priv;</code>

        </function>

    </query>

In the example above both 'user' and 'priv' were valid Java identifiers.

2. This is an example where the resource selectors are defined using regular expressions. The function calculates the number of active connections in each connection pool.

<query>

<code>return size-free;</code>

</function>

</query>

Tip: When you only need to convert the value of an existing counter you can define a function in-line with the resource definition by using the code resource style attribute.

3. This is an example of an in-lined function definition that coverts the original value from kilobytes to megabytes:

<resource code="return (float)used/1024;" description="Used(MB)" id="used" iname="$entity[1]/$entity[2]/$counter" name="Used(MB)" rid="-/-/root/(.*)/(.*)/jvmRuntimeModule/[jvmRuntimeModule.usedMemory]"/>

op="sum"

Accepts one parameter as input and accumulates its values over time. Returns the current accumulated value.

    <function op="sum">

        <param id=""/>

    </function>

op="average"

Accepts one parameter as input and calculates an average of its values over time. Returns the current average value.

    <function op="average">

        <param id=""/>

    </function>

op="diff"

Accepts one parameter as input and returns the difference between its current value and the previous (differential).

f(x, t) = x(t1) - x(t0);

where x = value, t = time

    <function op="diff">

        <param id=""/>

    </function>

op="timediff"

Accepts one parameter as input and returns the time relative difference between its current value and the previous.

f(x, t) = ( x(t1) - x(t0) ) / ( t1- t0 );

where x = value, t = time

    <function op="timediff">

        <param id=""/>

    </function>

op="identity"

Accepts one parameter as input and returns its value unchanged. Mostly used internaly by the application itself.

    <function op="identity">

        <param id=""/>

    </function>

op="filter"

Accepts one parameter as input and returns its value unchanged but only if matches one of the predefined values. Multiple <value> tags are allowed.

<function op="filter">

        <param id=""/>

        <value>value1</value>

        <value>value2</value>

...

   </function>

If no value is matched then this function rejects the current data and screen controls are not updated.

Limitations

As with reactions one function can only operate with counters of entities which are provided by the same source; e.g the definition of a reaction can use all the counters from an agent without providers (this is the case with most agents) whereas when providers are used (as in the case of Unix or some of the SQL agents) it can only operate with counters contributed by the same provider.