Zorka

This section contains most basic information about agent installation and configuration.

Agent directory layout

By convention zorka files reside in <appserver-home>/zorka directory which wil be refered as agent home directory. It contains the following objects:

zorka.jar - agent jar (all dependencies included);
scripts/*.bsh - extension scripts loaded at agent startup;
log/* - log and trace files will be stored here;
templates/* - templates for zabbix (and maybe other monitoring systems); this directory isn't used by agent itselfand can be safely removed after installation;
zorka.properties - main configuration file;

Agent is installed into application using -javaagent:<path-to-zorka.jar>=<zorka-home-dir> option. Home directory can be passed as a part of -javaagent:... clause or as -Dzorka.home.dir=<zorka-home-dir> property.

For instructions specific to particular application servers, see links in Quickstarts section on the left.

Main configuration file (zorka.properties)

Most important configuration settings can be entered into zorka.properties file which is read at agent startup. This file can contain either settings that are recognizable by agent itself or custom settings that can be used in extension scripts. This file also contains references to BSH script that should be loaded and executed by agent at startup. In default configuration scripts are automatically included based on names of loaded classes. There is also possibility to manually preload scripts. Those scripts are responsible for detailed configuration of all agent subsystems (instrumentation engine, trappers etc.). Scripts are loaded from ${zorka.home.dir}/scripts directory.

Automatic configuration script selection

When scripts.auto property is set to default value of yes, automatic selection of script is enabled. Default built in configuration is already defined and compiled into agent. It is possibly to add new items or override existing ones in zorka.properties file. In order to add new selection rules, add the following setting to zorka.properties:

auto.<package-prefix> = script.bsh

For example:

auto.org.apache.tomcat = apache/tomcat.bsh
auto.com.mycompany.myapp = mycompany/myapp.bsh

Manual script execution (on agent initialization)

In order to disable automatic selection, administrator needs to disable automatic configuration mechanism using scripts.auto setting and enter comma separated list of scripts using scripts setting.

scripts.auto = no
scripts = jvm.bsh, zabbix.bsh, apache/tomcat.bsh, jdbc/pgsql.bsh, ldap.bsh

This will load scripts responsible for monitoring general JVM settings, zabbix support, apache tomcat, postgresql JDBC driver and ldap client connections. Note that some scripts might depend on other scripts and are automatically loaded.

Substitution and templating in configuration file

It is possible to use environment variables, system properties or other zorka configuration properties in zorka.propeties file. In order to do so, use the following substitution macros:

${$SOME_VAR} - will be substitued with SOME_VAR environment variable;
${@some.property} - will be substituted with some.property from java system properties;
${&some.setting} - will refer to other setting in zorka.properties; note that those macros are resolvedwhen settings are used, so it is potentially possible to have circular reference between two or more settingswhich will lead to errors;

In contrast to standard agent substitutions, agent will not walk down object tree using . as separator, so for example @some.property will be literally interpreted as some.property string from system properties, not as property field from some object from system properties.

As in standard substitutions, it is possible to set alternative references or default values using | and : characters. For example: ${$SOME_VAR|$OTHER_VAR|@other.property|&zorka.setting:defval} will try SOME_VAR variable, OTHER_VAR variable if first is null, other.property variable if OTHER_VAR is null or zorka.setting if other.property is not existent. Finally, defval value will be used if all previous are null.

Note that standard substitutions (that is, not starting with $, @ or & characters) will be left unmodified in order to be usable from .bsh scripts or spy or tracer components.

Online reconfiguration

Administrator can force agent to reload without restarting whole application. It will:

reload zorka.properties file;
reset BSH interpreter inside agent and reload all .bsh scripts pointed in zorka.properties;
restart all trappers and agent interfaces (eg. changing zabbix protocol port on the fly is possible);
reload spy configuration and reinstrument affected classes;
reinstrument all classes that have been included or excluded from tracing (relative to previous configuration);

Agent reconfiguration can be triggered by calling reload() method of zorka:type=ZorkaControl,name=ZorkaControl mbean (eg. using jconsole) or by calling zorka.reload[] via zabbix interface.

Note that reinstrumenting classes drains permgen on Sun JVM. Agent 'calculates deltas' between reloads in order to minimize number of reinstrumented classes but administrator still needs to ensure that changes don't exceed safe threshold (1000 classes consuming around 50MB of permgen is a good rule of thumb).

Zorka diagnostics

Zorka creates its own mbean that contains diagnostic information regarding agent itself. There is also zabbix template making use of it:

Template_Zorka_Diagnostics.xml - template monitoring zorka agent itself; it collects statistics about various agent subsystems and defines some triggers alerting if something inside agent goes wrong;

Note that this template has over 20 items. Consider disabling unused ones.