Prepare 0.7 release.

Author: rlewczuk

CHANGES.md

@@ -1,3 +1,18 @@
+Zorka 0.7 (2013-01-06)
+----------------------
+
+ * refactor spy API to use string keys (instead of convoluted stage-slot convention);
+ * get rid od ON_COLLECT stage, use asynchronous queue collector;
+ * refactor logger to act as aggregator of (attachable) trappers, remove loggger <-> file trapper redundancies;
+ * lots of redundant code eliminated (eg. threading code in trappers, rank listers, agent integrations etc.)
+ * lots of cleanups, javadocs, bugfixes, simplify package structure and limit inter-package dependencies;
+ * performance optimization of ZorkaStatsCollector (and removal of JmxAttrCollector);
+ * rudimentary stress testing / microbenchmarking framework implemented;
+ * spy now supports OSGi-based frameworks (eg. WSO2 Carbon, see sample script on how to configure it);
+ * remove custom pool executors, use standard ThreadPoolExecutor instead;
+ * support for matching classes and methods by annotations;
+
+
 Zorka 0.6 (2012-12-22)
 ----------------------
 

configs/samples/scripts/auditcas2.bsh configs/samples/scripts/audit_cas.bsh

@@ -19,24 +19,16 @@
 
 __cas() {
 
-  useSyslog = true;
-  useZabbix = true;
-
   request = new ThreadLocal();
 
-  syslogTrapper = useSyslog ? syslog.trapper("audit", "127.0.0.1", zorka.getHostname()) : null;
-  zabbixTrapper = useZabbix ? zabbix.trapper("audit", "127.0.0.1", zorka.getHostname()) : null;
+  syslogTrapper = syslog.trapper("audit", "127.0.0.1", zorka.getHostname(), syslog.F_AUDIT);
+  zabbixTrapper = zabbix.trapper("audit", "127.0.0.1", zorka.getHostname(), "cas.audit");
 
   audit(sdef, expr) {
-    if (useSyslog)
-      sdef = sdef.onSubmit(
-        spy.syslogCollector(syslogTrapper, expr, syslog.S_INFO, syslog.F_LOCAL5, zorka.getHostname(), "cas.audit"));
-
-    if (useZabbix)
-      sdef = sdef.onSubmit(
-        spy.zabbixCollector(zabbixTrapper, expr, "cas.audit"));
-
-    spy.add(sdef);
+    spy.add(sdef.onSubmit(
+      spy.trapperCollector(syslogTrapper, zorka.INFO, "cas", expr),
+      spy.trapperCollector(zabbixTrapper, zorka.INFO, "cas", expr)
+    ));
   }
 
 

configs/samples/scripts/auditcas3.bsh configs/samples/scripts/audit_snmp.bsh

@@ -157,10 +157,10 @@ __jboss() {
 
     jbossMbs = null;
 
-    process(stage,record) {
+    process(record) {
       synchronized (super) {
         if (super.jbossMbs == null) {
-          mbs = record.get(spy.ON_RETURN,0);
+          mbs = record.get("MBS");
           zorka.registerMbs("jboss", mbs);
           super.jbossMbs = mbs;
           zorka.logInfo("Registered JBoss MBean server as 'jboss'");
@@ -172,7 +172,7 @@ __jboss() {
   } // __mbsRegister()
 
   spy.add(spy.instance()
-    .onReturn(0, (com.jitlogic.zorka.spy.SpyProcessor)__mbsRegister())
+    .onReturn(spy.fetchArg("MBS", 0), (com.jitlogic.zorka.spy.SpyProcessor)__mbsRegister())
     .include(spy.byMethod("org.jboss.mx.server.MBeanServerImpl", "<init>")));
 
   return this;

configs/samples/scripts/auditcas1.bsh

@@ -124,7 +124,7 @@ __jboss7() {
   __mbsRegister() {
     jbossMbs = null;
 
-    process(stage,record) {
+    process(record) {
       synchronized (super) {
         if (super.jbossMbs == null) {
           mbs = java.lang.management.ManagementFactory.getPlatformMBeanServer();
@@ -140,8 +140,8 @@ __jboss7() {
 
 
   spy.add(spy.instance()
-    .onReturn(spy.FETCH_NULL, (com.jitlogic.zorka.spy.SpyProcessor)__mbsRegister())
-    .include(spy.byMethod("org.jboss.modules.ModuleLoader", "installMBeanServer")));
+    .onReturn((com.jitlogic.zorka.spy.SpyProcessor)__mbsRegister())
+    .include(spy.byMethod(spy.AC_STATIC, "org.jboss.modules.ModuleLoader", "installMBeanServer", "void")));
 
 
 

configs/zabbix/scripts/jboss.bsh

@@ -23,7 +23,7 @@ __wso2() {
 
   __carbonOSGiConfigurer() {
 
-    process(stage, record) {
+    process(record) {
       zorka.logInfo("(Re)Configuring OSGi parameters for Zorka Spy ...");
 
       p = record.get("PARAM");

configs/zabbix/scripts/jboss7.bsh

@@ -10,7 +10,8 @@ implemented at first):
 
 * programmability - zorka can be extended using BeanShell scripts;
 
-* bytecode instrumentation - zorka can instrument your code in several ways and present collected values via JMX Beans;
+* bytecode instrumentation - zorka can instrument your code in several ways and perform arbitrary actions with collected
+data, eg. present them as statistics via JMX, send to file, syslog, as SNMP traps or execute arbitrary beanshell script;
 
 * mapped mbeans - user can map calcluated values from some mbeans into other mbeans (on attribute basis);
 standard JMX clients can fetch these values;

configs/zabbix/scripts/wso2.bsh

@@ -135,7 +135,7 @@ as BeanShell scripts.
 
 Spy definition example:
 
-    collect(record) {
+    process(record) {
       mbs = record.get(4,0);
       zorka.registerMbs("jboss", mbs);
     }
@@ -163,33 +163,22 @@ to choose stage (or probe point):
     sdef = sdef.onReturn(args...);
     sdef = sdef.onError(args...);
     sdef = sdef.onSubmit(args...);
-    sdef = sdef.onCollect(args...);
 
-### Fetching arguments
+### Fetching, processing and collecting data
 
 Data to be fetched by probes can be defined using `withArguments()` method:
 
     sdef = sdef.onEnter(arg1, arg2, ...);
 
-Arguments can passed as numbers representing argument indexes or special data. For instance methods visible arguments
-start with number 1 at number 0 there is reference to object itself (`this`). For static methods arguments start with
-number 0.
-
-There are some special indexes that represent other data possible to fetch by instrumentation probes:
-
-* `spy.FETCH_TIME` (-1) - fetch current time;
-* `spy.FETCH_RET_VAL` (-2) - fetch return value (this is valid only on return points);
-* `spy.FETCH_ERROR` (-3) - fetch exception object (this is valid only on error points);
-* `spy.FETCH_THREAD` (-4) - fetch current thread;
-* `spy.FETCH_NULL` (-5) - fetch null constant (useful in some cases);
-
-It is also possible to fetch classes - just pass strings containing fully qualified class names instread of integers.
+Fetch probes, processors and collectors can be used as arguments (see spy library functions). Fetch probes produce data
+that are passed through processors to collectors as dictionary objects (`Map<String,Object>`). Data are accessed using
+string keys as in ordinary hash maps. Processors can get named values from map objects or write other values to passed
+maps. Processors can also filter out records. Collectors are just special kinds of processors that have some side
+effects. >Collector can update statistics, write to logs, send messages via syslog etc.
 
 Additional notes:
 
-* remember that argument fetch can be done in various points, use `sdef.onXXX()` method to select proper stage;
-
-* when instrumenting constructors, be sure that this reference (if used) can be fetched only at constructor return -
+* when instrumenting constructors, be sure that `this` reference (if used) can be fetched only at constructor return -
 this is because at the beginning of a constructor this points to an uninitialized block of memory that does not
 represent any object, so instrumented class won't load and will crash with class verifier error;
 
@@ -200,24 +189,3 @@ represent any object, so instrumented class won't load and will crash with class
 Using `include()` method administrator can add matching rules filtering which methods are to be instrumented. Methods
 matching any of passed matchers will be included. Matchers can be defined using `spy.byXXX()` functions.
 
-### Access to data in spy records
-
-Spy processors and collectors access data stored in records using references that can have two forms:
-
-* simple indexes (numbers) - will always refer to slot in current processing stage (stage processor has been added to);
-these are simple integers; slot indexes start at 0;
-
-* full references - contain both stage identifier and slot  number; these are strings with first character indicating
-stage and followed by index, eg. `E0` means first slot in `ON_ENTER` stage;
-
-The following characters are legal:
-
-* `E` - `ON_ENTER`;
-* `R` - `ON_RETURN`;
-* `X` - `ON_EXCEPTION`;
-* `S` - `ON_SUBMIT`;
-* `C` - `ON_COLLECT`;
-
-
-### Formatting strings
-

docs/UserGuide/01intro.md

@@ -514,10 +514,6 @@ In addition `keyExpr` can contain expressions fetching record arguments `${n.att
 
 It is also possible to attach single-method call statistic directly as mbean attribute:
 
-    spy.zorkaStat(mbsName, beanName, attrName, tstampField, timeField);
-
-All parameters are the same as in `toStats()` method (except for `keyExpr` which is missing).
-
 #### Intercepting and presenting objects via Zorka Getter
 
 Presenting intercepted values as mbean attributes is possible with `toGetter()` method:
@@ -527,14 +523,6 @@ Presenting intercepted values as mbean attributes is possible with `toGetter()`
 This will present intercepted object as ValGetter attribute. Each time attribute is accessed (eg. via jconsole),
 Zorka will fetch value using attribute chain `(attr1, attr2, ...)` as in `zorka.jmx()` call.
 
-#### Logging collected events via Syslog
-
-    spy.syslogCollector(trapper, expr, severity, facility, hostname, tag)
-
-Parameter `trapper` must be a reference to trapper object obtained using `syslog.trapper()`. Parameter `expr` is message
-template (analogous to `keyExpr` in other collectors). Remaining parameters - `severity`, `facility`, `hostname` and
-`tag` work in the same way as in `syslog.log()` method.
-
 #### Sending collected events as SNMP traps
 
     spy.snmpCollector(trapper, oid, spcode, bindings)
@@ -543,22 +531,24 @@ Parameter `trapper` must be a reference to trapper object obtained using `snmp.t
 `enterprise-oid` field set to `oid` and all variables will have their keys starting with `oid`. Traps will be of
 `enterpriseSpecific` (6) type and specific code will be set to `spcode`.
 
-#### Sending collected events to Zabbix
+#### Using trappers with spy
 
-    spy.zabbixCollector(trapper, expr, key)
-    spy.zabbixCollector(trapper, expr, host, key)
+    spy.trapperCollector(trapper, logLevel, tagExpr, msgExpr, errExpr, errField)
 
-Parameter `trapper` must be a reference to zabbix trapper obtained using `zabbix.get()` function. Parameter `expr` is
-message template (analogous to `keyExpr` in other collectors). Parametry `key' refers to zabbix item key that will be
-populated. Item must be of proper type (text or number depending on data that is submitted).
+This function creates collector that will send messages via trapper. Several trapper types are available:
 
-#### Sending collected records to log file
+* file trappers - trappers that log messages to log file;
+* syslog trappers - trappers that send syslog messages;
+* zabbix trappers - trappers that send traps directly to zabbix;
 
-    spy.fileCollector(trapper, expr, logLevel)
+Arguments:
 
-Parameter `trapper` must be a reference to file trapper obtained using `zorka.fileTrapper()`, `zorka.dailyFileTrapper()`
-or `zorka.rollingFileTrapper()`. Second parameter `expr` contains template string used to create log messages. Parameter
-`logLevel` must be one of: `zorka.TRACE`, `zorka.DEBUG`, `zorka.INFO`, `zorka.WARN`, `zorka.ERROR` and `zorka.FATAL`.
+* `trapper` - configured and started trapper object;
+* `logLevel` - log level (ZorkaLogLevel constant);
+* `tagExpr` - log tag;
+* `msgExpr` - log message (if call succeeds);
+* `errExpr` - log message (if error occurs);
+* `errField` - spy record field that contains intercepted exception object;
 
 #### Passing records to another processing chain
 

docs/UserGuide/03config.md

@@ -3,7 +3,7 @@
     <groupId>com.jitlogic.zorka</groupId>
     <artifactId>zorka</artifactId>
     <packaging>pom</packaging>
-    <version>0.6.1-SNAPSHOT</version>
+    <version>0.7.0</version>
     <name>zorka: parent aggregator</name>
     <url>http://www.jitlogic.com/zorka</url>
 

docs/UserGuide/04apiref.md

@@ -6,7 +6,7 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xs
     <parent>
         <groupId>com.jitlogic.zorka</groupId>
         <artifactId>zorka</artifactId>
-        <version>0.6.1-SNAPSHOT</version>
+        <version>0.7.0</version>
     </parent>
     <dependencies>
         <dependency>

pom.xml

@@ -192,11 +192,11 @@ public ZabbixTrapper trapper(String id) {
      * @param defaultHost default host name
      * @return zabbix trapper
      */
-    public ZabbixTrapper trapper(String id, String serverAddr, String defaultHost) {
+    public ZabbixTrapper trapper(String id, String serverAddr, String defaultHost, String defaultItem) {
         ZabbixTrapper trapper = trappers.get(id);
 
         if (trapper == null) {
-            trapper = new ZabbixTrapper(serverAddr, defaultHost, "traps");
+            trapper = new ZabbixTrapper(serverAddr, defaultHost, defaultItem);
             trappers.put(id, trapper);
             trapper.start();
         }