JavaScript Calculators

Document created by Hiko_Davis Employee on Jan 29, 2015Last modified by Guenter_Grossberger on Sep 7, 2016
Version 11Show Document
  • View in full screen mode

Overview

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, or 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.

 

Installation

To install a new JavaScript calculator, copy the JavaScript text file into the <EM_Home>/scripts directory of your Enterprise Manager installation. You can use another directory for scripts; if you do, specify the directory using the introscope.enterprisemanager.javascript.dir property.

 

Scripts are automatically deployed from this scripts directory at the frequency specified by the introscope.enterprisemanager.javascript.refresh property, which by default is 60 seconds.

 

After successful deployment, the new metrics appear in the Metric Browser tree.

 

Functions

getAgentRegex

Returns a string containing a regular expression to match agents

 

function getAgentRegex() {
    return ".*";
}
     

 

getMetricRegex

Returns a string containing a regular expression to match metrics

 

function getMetricRegex() {
    return "CPU.*";
}
     

 

getFrequency

Must return a multiple of default system frequency (currently 15 seconds)

 

function getFrequency() {
     return 15;
}
     

 

getMetricSpecifier

Returns a metric Specifier

 

function  getMetricSpecifier() {
     return "CPU\\|.*";
}
     

 

execute

Each calculator must have an execute() function that takes two arguments. Additionally, 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.

 

Logging

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

Note: If you want to use advanced JavaScript features or are concerned with ECMA compliance, note that the script engine embeds the Mozilla Rhino JavaScript library, version 1.6_R1.

Even without additional log configuration my logging from a JavaScript calculator gets written to IntroscopeEnterpriseManager.log (for INFO and DEBUG):

9/07/16 03:34:00.012 PM GMT [INFO] [Harvest Engine Pooled Worker] [Manager.JavaScript|MyScript.js] info test
9/07/16 03:34:00.013 PM GMT [DEBUG] [Harvest Engine Pooled Worker] [Manager.JavaScript|MyScript.js] debug test

If you want to change the log level you can do so in IntroscopeEnterpriseManager.properties:

log4j.logger.Manager.JavaScript|MyScript.js=DEBUG, console, logfile

If you want to redirect the JavaScript logging to a separate file you have to create a new log4j appender in IntroscopeEnterpriseManager.properties:

log4j.logger.Manager.JavaScript|MyScript.js=DEBUG, scriptlogfile 
log4j.appender.scriptlogfile.File=logs/javascript.log
log4j.appender.scriptlogfile=com.wily.org.apache.log4j.RollingFileAppender
log4j.appender.scriptlogfile.layout=com.wily.org.apache.log4j.PatternLayout
log4j.appender.scriptlogfile.layout.ConversionPattern=%d{M/dd/yy hh:mm:ss.SSS a z} [%-3p] [%t] [%c] %m%n
log4j.appender.scriptlogfile.MaxBackupIndex=4
log4j.appender.scriptlogfile.MaxFileSize=50MB


Running JavaScript Calculators on the MOM

You can run a JavaScript calculator on the MOM to produce metrics for the MOM's Custom Metric Agent. While it cannot produce metrics for agents that are connected to a Collector, it can see input metrics from agents in the Collectors.

If a calculator is added, modified, or deleted in a clustered environment, the MOM will automatically propagate the change to all Collectors unless you turn off the automatic update for collectors. For more information, see "Turning off the automatic update for Collectors".

 

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 will run on the MOM.

 

Reducing the number of logged metric creation errors

If 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, such as in the following 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 (%)]

 

Turning 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 could turn this feature off if you do not want the calculators propagated.

 

To turn off the automatic update for Collectors:

 

1.Open the property file on the MOM Enterprise Manager.

2.Edit the property

introscope.enterprisemanager.javascript.hotdeploy.collectors.enable which has the default value of true. Change the value to false.

3.Verify 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 your changes.

5.Restart the MOM Enterprise Manager.

6 people found this helpful

Attachments

    Outcomes