Selecting classes and methods 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).
Marking trace flags
Trace flags modify trace-level behavior - that is, whole method call tree from top trace record down. For modifying trace behavior on individual record level, see trace record flags in next section.
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);
Marking trace record flags
Those flags adhere only to trace record corresponding to current method call. For creating processor modifying trace flags, use tracer.recordFlags() function:
tracer.recordFlags(flags)Following flags are present at the moment:
trace.TR_FORCE_TRACE- enforces submission of record regardless of execution time and/or errors occurence;
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).