Use JavaScript Calculators

A JavaScript calculator reads input metrics and produces output metrics according to calculations specified in a user-created JavaScript text file. The new calculated metrics can appear in the Investigator tree under the Virtual Custom Agent. The metrics can also appear in any node of the Investigator tree, according to the output metric that is specified in the calculator script. A calculated metric can be shut off, but the calculator producing it does not know about the shutoff state.
apmdevops97
A JavaScript calculator reads input metrics and produces output metrics according to calculations specified in a user-created JavaScript text file. The new calculated metrics can appear in the Investigator tree under the Virtual Custom Agent. The metrics can also appear in any node of the Investigator tree, according to the output metric that is specified in the calculator script. A calculated metric can be shut off, but the calculator producing it does not know about the shutoff state.
The Enterprise Manager JavaScript engine allows you hot-deploy JavaScript calculators to a running Enterprise Manager.
Writing JavaScript Calculators
JavaScript calculator files must end with a 
.js
 extension and must reside in the Enterprise Manager scripts directory. Sample JavaScript calculator files are provided in the Enterprise Manager 
examples/scripts/
directory.
JavaScript calculators specify input metrics and produce one or more output metrics.
The
execute( )
Function
Each calculator must have an execute() function that takes two arguments. Also, helper functions are available to help build metrics to send back to the Enterprise Manager. The syntax is:
function execute(metricData,javascriptResultSetHelper)
Where
  • metricData -- is an array of metric Data supplied to the function when it is called at every 15 seconds before execute() intervals
  • javascriptResultSetHelper -- is an object that collects the new metric data produced by the script and sends them back to the EM
    • kDefaultFrequency - is used as input to the frequency argument of the addMetric() helper function
    • kIntegerConstant - maps to the integer constant metric type
    • kIntegerFluctuatingCounter - maps to the integer fluctuating counter metric type
    • kLongConstant - maps to the long constant metric type
    • kLongFluctuatingCounter - maps to the long fluctuating counter metric type
    • kLongTimestamp - maps to the long timestamp metric type
    • kLongTimestampConstant - maps to the long timestamp constant metric type
    • kIntegerPercentage - maps to the integer percent metric type
    • kIntegerDuration - maps to the integer duration metric type
    • kLongDuration - maps to the long duration metric type \
    • kLongIntervalCounter - maps to the long interval counter metric type
    • kStringIndividualEvents - maps to the string metric type
    • addMetric(metricName, count, value, min, max, metricType, frequency) - supports setting the count/value/min/max of a metric value, which is needed for the rate and interval count metric types, where the "value" of the metric is based on its "count"
    • getCustomMetricAgentMetric(agentMetric)
      - helps build a fully qualified metric name using the agent metric supplied and filling in the rest based on the name of the SuperDomain custom metric agent
The execute() function is called every 15 seconds by the scripting engine.
Specifying Input Metrics
The calculator script can specify the input metrics that it receives in one of two ways:
  • The easiest way to specify input metrics is with a pair of methods: function
    getAgentRegex()
    which returns a string containing a regular expression to match agents and function
    getMetricRegex()
    which returns a string containing a regular expression to match metrics.
  • You can also use the method function
    getMetricSpecifier()
    , which returns a metric Specifier.
The regular expressions created as strings in function
getAgentRegex()
and function getMetricRegex() must use character escaping differently than other regular expressions you use in Introscope -- for example, in metric groupings or in the Search view. Any Java escape characters that are returned from these JavaScript functions must also be escaped in the JavaScript. So, for example, '\|' must be escaped as '\\|' in the JavaScript.
Global Variable Log
All JavaScript calculator functions have access to a global variable log, which is of type
IModuleFeedbackChannel
. For example:
function execute(metricData,javascriptResultSetHelper) { log.info("message"); log.error("message"); log.debug("message"); }
If you want to use advanced JavaScript features or are concerned with ECMA compliance, the script engine embeds the Mozilla Rhino JavaScript library, version 1.6_R1.
Creating Output Metric Data
Creating output metric data requires:
  • Metric name --
    consisting of the agent plus the full path to the appropriate node in the metric tree.
    • You can create the agent name that is based on the incoming data. The new calculated data appears along with metric data the agent reports.
      or 
    • You can specify a new calculator metric name to show the calculated metric data in its own node in the metric tree.
  • Data value --
    calculated by the script.
  • Result data type --
    specified by a constant value from the class com.wily.introscope.spec.metric.MetricTypes.
  • Reporting Frequency -- The frequency at which the new metric data is reported to the Enterprise Manager, which can be obtained from the incoming data, or specified explicitly. You can change the frequency to a multiple of the Enterprise Manager default frequency (15 seconds).
Here is a typical calculated value from a script:
javascriptResultSetHelper.addMetric(metricName, heapUsedValue,Packages.com.wily.introscope.spec.metric.MetricTypes.kIntegerFluctuatingCounter,frequency)
Specify regular expressions with care, as they can potentially match any metrics that you produce. For instance, a regular expression of "EJB.*Time.*" could insert a new value under EJB. The regular expression inserts a new value under "EJB" when you have a regex on "EJB.*Time.*". You can either change your regular expression to do this, or remove metric data from your own metrics.
Add a JavaScript Calculator
To install a new JavaScript calculator, copy the JavaScript text file into the
<EM_Home>
/scripts directory. When you want to use a different directory, configure the
introscope.enterprisemanager.javascript.dir
property.
Scripts are automatically deployed from this scripts directory at the frequency that the
introscope.enterprisemanager.javascript.refresh
property specifies. You can change the
introscope.enterprisemanager.javascript.
refresh
 property value in the 
IntroscopeEnterpriseManager.properties
 file. The property default is 60 seconds. 
After successful deployment, the new metrics appear in the Metric Browser tree.
Running JavaScript Calculators on the MOM
You can run a JavaScript calculator on the MOM to produce metrics for the MOM Custom Metric Agent. The calculator cannot produce metrics for agents that are connected to a Collector, but can see input metrics from agents in the Collectors.
More information
: About Calculators
If a calculator is added, modified, or deleted in a clustered environment, the MOM automatically propagates the change to all Collectors. This propagation does not occur when automatic updates for Collectors are turned off.
The
runOnMOM
Function
A JavaScript calculator that should not run on the MOM must implement a
runOnMOM
function that returns false, such as in the following example:
// return false if the script should not run on the MOM // default is true. function runOnMOM() { return false; }
If the
runOnMOM
function returns
true
or is not implemented, the JavaScript calculator also runs on the MOM.
Reducing the Number of Logged Metric Creation Errors
When a calculator runs on the MOM and creates a metric for an agent that exists in the Collectors, there is a one-time logging of the event at the WARN level. 
Example
5/15/07 02:32:20 PM PDT [WARN] [Manager.MetricCalculatorBean] Calculator Registered Metric <ID=7, JavaScript calculator C:\workspaces\workspaceKrakatau\com.wily.introscope.em.feature\rootFilesMOM\.\scripts\HeapUsedPercentage.js>. A JavaScript calculator in the MOM cannot output metric data to an agent that exists in a Collector: SuperDomain|rhart-dt1|EPAgentProcess1|EPAgent15|GC Heap:Heap Used (%) 5/15/07 02:32:20 PM PDT [WARN] [Manager.MetricCalculatorBean]
Subsequent events are logged only at the DEBUG level.
Turn Off the Automatic Update for Collectors
Clustered environments are automatically set to propagate an added, modified, or deleted JavaScript calculator to all Collectors. However, you can turn off this feature if you do not want the calculators propagated.
Follow these steps:
  1. Open the
    IntroscopeEnterpriseManager.properties
    file on the MOM.
  2. Edit the 
    introscope.enterprisemanager.javascript.hotdeploy.collectors.enable
     property, which has the default value of
    true
    . Change the value to
    false
    .
  3. Verify that the change has been applied by viewing the
    JavaScriptCalculatorsMOM.properties
    file in the
    <EM_Home>
    \config\internal\server\scripts directory on the Collector.
  4. Save and close the file.
  5. Restart the MOM.