Tracer API: trace attributes

Trace attributes can be added by adding attribute setting spy processor into method instrumentation or directly from BSH code.

Spy processors

Spy processors can be created using the following functions:

tracer.attr(attrName, fieldName)
tracer.attr(attrName, tag, fieldName)

This processor will add value from given spy record field fieldName as an attribute named attrName to trace record representing currently running method. It can be invoked at any method not only trace beginning. Attributes will be attached to this method’s trace record (so the same attribute can appear at many records in the same trace). Optional argument tag will result in tagged attribute (that can be recognized by collector and interpreted in specific way).

tracer.formatAttr(attrName, srcFormat)
tracer.formatAttr(attrName, tag, srcFormat)

Another variants of above methods add attributes to traces instead of current methods (i.e. root methods of current trace):

tracer.traceAttr(traceName, attrName, srcField)
tracer.traceAttr(traceName, attrName, tag, srcField)

tracer.formatTraceAttr(traceName, attrName, srcFormat)
tracer.formatTraceAttr(traceName, attrName, tag, srcFormat)

Additional argument traceName can be null, so agent will look upwards the call stack and add new attribute to method that marks beginning of any trace or it can contain actual name. In latter case it agent will look upwards call stack and new attribute will be added to method marking beginning of trace of this name. If no appropriate trace exists, attribute won’t be attached anywhere.

Adding attributes manually

Attributes can be added manually from BSH functions. This is useful for implementing custom handling code called from instrumented methods (eg. manual parameter extraction from HTTP requests etc.).

tracer.newAttr(attrName, value)
tracer.newAttr(attrName, tag, value)

tracer.newTraceAttr(traceName, attrName, value)
tracer.newTraceAttr(traceName, attrName, tag, value)

Above functions immediately add value as attribute named attrName. Arguments attrName, traceName and tag have the same meaning as in spy processor creating functions.