Zorka

General purpose functions

zorka.jmx()

zorka.jmx(<mbsName>, <objectName>, <attr1>, <attr2>, ...)

Returns value of given object. Looks in <mbsName> mbean server for object named <object-name>, fetches <attr1> from it, then fetches <attr2> from result of previous fetch etc. Depending on object type, attribute fetch can involve invoking getter (arbitrary objects), looking for a key (map objects), indexing (lists or arrays). This way user can access arbitrarily deep into structure of an object available via JMX.

zorka.jmxc()

zorka.jmxc(<mbsName>, <objectName>, <methodName>, <methodSignature>, <arg1>, <arg2>, ...)

Calls a JMX operation on given mbean. In addition to method name, method signature is also required as mbean can have several different operations (methods) having the same name but different argument lists.

Method signature is a string where each characters defines data type for corresponding argument. The following types are supported:

b, B - byte, java.lang.Byte;
c, C - char, java.lang.Character;
s, S - short, java.lang.Short;
i, I - int, java.lang.Integer;
l, L - long, java.lang.Long;
f, F - float, java.lang.Float;
d, D - double, java.lang.Double;
T - java.lang.String;

Note that there are representations for both boxed and unboxed variants of basic data types. It is important to select correct variants as JMX distinguishes between boxed and unboxed types.

zorka.jmxLister()

zorka.jmxLister(<mbsName>, <objectName>)

Creates RankLister instance that will search through all attributes of objects matching <objectName> and look for ZorkaStats objects. This is useful for constructing rankings of method call statistics.

zorka.get()

zorka.get(<object>, <attr>, <attr>, ...)

Extracts attribute chain from object in the same way zorka.jmx() does when it finds mbean.

zorka.getter()

zorka.getter(<object>, <attr>, <attr>, ...)

Creates a getter object. Getter object takes some other object and exposes get() method that extracts data in the same way zorka.get() does.

zorka.log()

zorka.logDebug(<message>, <args>...)
zorka.logInfo(<message>, <args>...)
zorka.logWarning(<message>, <args>...)
zorka.logError(<message>, <args>...)

This function logs a message to zorka log. Extra arguments <args> will be woven into <message> using String.format(). If last extra argument is an exception (instance of java.lang.Throwable) it won't be used in string formating - it's stack trace will appear in log instead.

zorka.mbean()

zorka.mbean(<mbs>, <mbean-name>)
zorka.mbean(<mbs>, <mbean-name>, <description>)

Creates and returns a new generic mbean. MBean will be registered under a given name in a given mbean server. Returned object contains put() method that can be used to populate mbean with attributes - either plain values or getter objects (see zorka.getter() function).

zorka.rate()

zorka.rate(<mbs>, <object-name>, <attr>, ..., <nom>, <div>, <horizon>)

This function is useful for calculating (windowed) average rates of two attributes of an object (nominator and divider) in a selected time horizon. It looks for object <object-name> in <mbs> mbean server, then descends using <attr> arguments (the same way zorka.jmx() works), finaly uses <nom> and <div> parameters as nominator and divider, calculates deltas of both parameters over <horizon> time window and returns <nom> delta divided over <div> delta.

zorka.registerAttr()

zorka.registerAttr(<mbsName>, <beanName>, <attrName>, <obj>)
zorka.registerAttr(<mbsName>, <beanName>, <attrName>, <obj>, <desc>)

Registers arbitrary object <obj> in an <attrName> attribute of mbean named <beanName> in mbean server <mbsName>. Optionally description can be added using <desc> argument.

zorka.registerMbs()

zorka.registerMbs(<mbsName>, <mbsObject>)

Register mbean server <mbsObj> under <mbsName>. This is useful in conjunction with instrumentation for catching additional mbean servers and registering them. See how registering of JBoss5 mbean server works.

zorka.reload()

zorka.reload(<mask>)

Reloads all configuration scripts in $ZORKA_HOME/conf directory matching given <mask>. Note that this only means executing scripts once again. It is script implementer responsiblity to make sure that script is able to execute multiple times (and do reconfiguration properly).

zorka.fileTrapper()

zorka.fileTrapper(id)
zorka.rollingFileTrapper(id, loglevel, path, maxFiles, maxSize, logExceptions)
zorka.dailyFileTrapper(id, loglevel, path, logExceptions)
zorka.removeFileTrapper(id)

These functions allow creating, accessing and removing file trappers (loggers). File trappers can be used to log arbitrary things to local files (spy events in particular). There are two types of file trappers: rolling file trapper (that keeps limited amount of log files of limited size. Rolling trappers can be created using rollingFileTrapper() function. Daily file trappers create files with .YYYY-MM-DD extension, so logs are split in daily basis. Daily trappers are created using dailyFileTrapper() function. Both functions register created trappers with id tag. Both functions return trapper created earlier if it has been registered with the same id. Using fileTrapper() function it is possible to access trappers created earlier without creating new ones (if none exists). Use removeFileTrapper() function to unregister and dispose file trappers.

Configuration access

    zorka.hasCfg(key)

    zorka.boolCfg(key)
    zorka.boolCfg(key, defval)

    zorka.intCfg(key)
    zorka.intCfg(key, defval)

    zorka.longCfg(key)
    zorka.longCfg(key, defval)

    zorka.stringCfg(key)
    zorka.stringCfg(key, defval)

These are convenience functions for accessing configuration settings from zorka.properties file. Adminstrator can place arbitrary configuration settings into zorka.properties and then use them in BSH scripts. First function hasCfg() checks if given setting exists in zorka.properties and is contains non-empty string - returns true if so, or false if not. There are three sets of functions for parsing boolean, integer and long and string settings. Those functions return parsed values or supplied values if valid settings in zorka.properties do not exist or are not parsable. Boolean parsing boolCfg() functions recognize true/false and yes/no values (case-insensitive).

    zorka.listCfg(key, defv1, defv2, ...)

List parsing function listCfg() parses string containing comma-separated values and returns it as list of strings containing (trimmed) values.

    zorka.mapCfg(prefix, defk1, defv1, defk2, defv2, ...)

Map parsing function mapCfg() looks for a set of configuration properties with common prefix prefix. and creates map containing property keys stripped of prefix and property values.

    zorka.isInitialized()

This function returns true if agent has finished its initialization phase (and initial execution of configuration scripts). This function can be useful for reload-aware scripts.

Reflection support

zorka.getField(obj, name)
zorka.setField(obj, name, value)

These functions can be used to directly access object fields. Both private and public fields can be accessed.

General API