Getting Started with Scripting

This section contains information about implementing zorka extension scripts. Agent reads all files files ending with .bsh extension in alphabetical order. Scripts are interpreted in built-in beanshell interpreter and all declared objects will be available to monitoring clients.

Basics of scripting zorka have been described below. For more advanced tutorial and reference see links on sidebar.

Introduction to Zorka API

The API acronym might sound familiar to programmers, yet in this context it expands to *Agent Programming Interface* rather as Zorka beanshell scripts are not applications per se.

Zorka exposes standard BeanShell environment (with access to all classes visible from system class loader plus all Zorka code). There are several library objects visible:

• zorka - zorka-specific library functions (logging, JMX access etc., always available);
• spy - functions for configuring instrumentation engine (available if spy is enabled);
• tracer - functions for configuring method call tracer;
• zabbix - zabbix-specific functions (available if zabbix interface is enabled);
• nagios - nagios-specific functions (available if nagios interface is enabled);
• syslog - functions for sending messages to log host using syslog protocol;

All above things are visible Beanshell scripts from $ZORKA_HOME/scripts directory. Interfaces to monitoring systems (zabbix, nagios etc.) can call Beanshell functions as well (both built-in and user-defined) but due to their syntax are typically limited to simple calls. For example:

zorka.jmx["java","java.lang:type=OperatingSystem","Arch"]

is equivalent to:

zorka.jmx("java","java.lang:type=OperatingSystem","Arch");

MBean servers

Zorka can track many mbean servers at once. This is useful for example in JBoss 4/5/6 which have two mbean servers: platform specific (JVM) and application server specific (JBoss). Each mbean server is available at some name. Known names:

• java - standard plaform mbean server;
• jboss - JBoss JMX kernel mbean server;

MBean server name is passed in virtually all functions looking for object names or registering/manipulating objects/attributes in JMX.

First BSH script

Here we create simple script defining trivial function. Let's add trivial.bsh file to <zorka-home>/conf directory with the following code:

os_arch() {
  return zorka.jmx("java","java.lang:type=OperatingSystem","Arch");
}

Now agent can be queried for example by zabbix_get tool:

$ zabbix_get -s 127.0.0.1 -p 10115 -k 'os_arch[]'
amd64
$

In order to not pollute common namespace, it is recommended to enclose newly defined functions in their own namespaces. Beanshell does not have notion of namespace but it has closures that can be used as namespaces:

__os() {
  arch() {
    return zorka.jmx("java","java.lang:type=OperatingSystem","Arch");
  }
  cpus() {
    return zorka.jmx("java","java.lang:type=OperatingSystem","AvailableProcessors");
  }
  return this;
}
os = __os();

In above example os namespace has been created and it contains arch() and cpus() functions that are accessible to zabbix:

$ zabbix_get -s 127.0.0.1 -p 10115 -k 'os.arch[]'
amd64
$ zabbix_get -s 127.0.0.1 -p 10115 -k 'os.cpus[]'
8

Administrator can define any kind of logic in beanshell functions and thus extend agent functionality of agent at will.