Selecting classes and method for trace

tracer.include(matcher, matcher, ....)
tracer.exclude(matcher, matcher, ....)

First function adds matcher that will include classes (methods), second adds matcher that will exclude classes (or methods). Note that added matcher are evaluated in order they’ve been added, so you may consider adding general exclusions first and add “everything” after that.

Marking trace beginning

tracer.begin(label)
tracer.begin(label, minExecutionTime)
tracer.begin(label, minExecutionTime, flags)

This processor marks beginning of a trace. Tracer will start collecting method call data when it application enters to an instrumented method that has tracer.begin() in its processing chain and will submit collected data at method exit.

Traces are submitted only when execution took more than predefined time. This minimum time can be passed as an argument of tracer.begin() or some system-wide default value can be used. Third variant of this functions allows for setting additional flags to trace (see tracer.flags() for more details).

Adding attributes

Marking trace flags

tracer.flags(flags)
tracer.flags(srcField, flags)

This function sets flags altering tracer behavior. First variant sets flags unconditionally. Second variant sets flags only if given field of spy record contains non-null value. Only currently started trace is marked. The following flags are avaiable:

  • tracer.SUBMIT_TRACE - forces submission of current trace regardless of other conditions;

  • tracer.ALL_METHODS - records all method calls of current trace regardless of other conditions;

  • tracer.DROP_INTERIM - drops interim methods if their execution time is too short;

  • tracer.ERROR_MARK - marks trace error (used for custom error marking, eg. by HTTP status codes);

Configuring tracer output

Storing traces in local files can be configured like this:

tracer.toFile(path, maxFiles, maxSize)
tracer.output(output)

First function creates trace file writer object that can be installed into tracer using second function.

For sending traces to central collector, use tracer.toCentral() function:

 tracer.toCentral(address, port, hostname, password)

Global tracer options

tracer.setTracerMinMethodTime(nanoseconds);
tracer.setTracerMinTraceTime(milliseconds);
tracer.setTracerMaxTraceRecords(nrecords);
tracer.setDefaultTraceFlags(flags);

First function sets default minimum execution time for a method to be included into trace. Note that due to required resolution, passed time parameter is in nanoseconds (not milliseconds as usual). Second function sets default minimum execution time for a trace to be further processed after completion. Third function sets limit for a number of records included in a single trace. This limit is necessary to prevent tracer from overruning host memory in cases there traced method calls lots and lots of other traced methods (and all become logged for some reason).