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 itself and 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. Those scripts are responsible for detailed configuration of all agent subsystems (instrumentation engine, trappers etc.). Scripts are loaded from ${zorka.home.dir}/scripts directory and are passed to agent using scripts property, for example:

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.

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.