Filtering and subchains

Spy plugins have capability of interrupting further processing of spy definition chain at any stage (enter, return, error or submit). This can be done when plugin process(rec) { .. } method returns null instead of reference rec. There is a set of predefined filters (implemented in Java) or administrator can implement his own filtering manually using Bean Shell.

Predefined filters

Regex filter

spy.regexFilter(src, regex);
spy.regexFilterOut(src, regex);

These two functions allow filtering of records. First one will pass only records matching regex on argument number src. Second one will do exactly opposite thing if filterOut argument is true or behave as first one if false.

Value set filters

spy.valSetFilter(field, candidates)
spy.valSetFilterOut(field, candidates)

First function creates filter that will pass only records, whose field contain value present in supplied set of candidates. Second function creates inverted version of such filter (that filters out matching records instead of passing them).

Comparator filters

spy.scmp(a, op, b)
spy.vcmp(a, op, v)

These two methods can be used to filter out unwanted records. First one compares values from two slots of a record, second one compares value from record slot with some constant. Arguments a and b are slot numbers, v is a constant value and op is one of operators: spy.GT, spy.GE, spy.EQ, spy.LE, spy.LT, spy.NE. Both functions will coerce input values to proper types in order to make comparison possible. Floating point values (float or double) are compared with 0.001 accuracy. For example:

  • scmp(0, spy.GT, 1) will pass only records for whose value from slot 0 is greater than value from slot 1;

  • vcmp(0, spy.LT, 42) will pass only records for whose value from slot 0 is less than 42;

Logical filters

spy.and(filter1, filter2, ...)
spy.or(filter1, filter2, ...)

Logical filters allow combining other filters. Filter created by spy.and() function will pass record only if all filters supplied as its argument pass. Filter created by spy.or() will pass record if any of supplied filters pass.

spy.longerThan()

spy.longerThan(interval)
spy.longerThan(field,interval)

This filter is used to detect methods that execute longer interval (in milliseconds). First function creates filter that looks for time in field named T. Second one allows specifying field name. Note that field has to contain nanosecond-resolution value (taken from System.nanoTime() - as agent itself is doing).

Processing subchains

spy.subchain(spy1, spy2, ...)

This function will create synchronously executed processing chain. It will work the same way normal processing chain works (eg. add, remove and change values passed through chain via spy record). When some plugin filters out processed event, processing will stop inside subchain itself but will resume at the next plugin in parent processing chain.