Exception Tracing

The Exception Tracer feature can be used to debug issues related to application exceptions in the Agent. When enabled, the agent emits a debug event every time an exception is thrown or caught. Each event records the exception instance, the caller class and a full stack trace.

When to use?

Enable exception tracing when you need to understand:

• which exception types are thrown or caught in application code,
• where in the application those events occur,
• the stack trace at the point of throw or catch.

Because instrumentation runs across loaded classes and logging happens on every matching throw/catch, this is intended for debug / troubleshooting, not continuous production use.

How to enable?

• enable the trace flag com.waratek.TraceExceptions=true
• debug logging will be written (with some other debug messages) to the file configured by the following option: com.waratek.debug.log=<path/to/debug.log>
• by default, all log categories are included, EXCEPTION_TRACER is the category used by tracer

Filter by exception type (optional)

Use com.waratek.TraceExceptionsEnable and com.waratek.TraceExceptionsDisable to control which exception classes are traced. Class names use dot notation (for example java.lang.NullPointerException).

Option	Type	Default	Effect
TraceExceptionsEnable	string array	empty	If empty, all exception types are eligible (subject to disable). If non-empty, only listed exception types are traced.
TraceExceptionsDisable	string array	empty	Listed exception types are never traced, even if they appear in TraceExceptionsEnable.

If the same type appears in both enable and disable lists, disable wins.

Examples:

# Trace only NullPointerException and IllegalArgumentException
com.waratek.TraceExceptions=true
com.waratek.TraceExceptionsEnable=java.lang.NullPointerException,java.lang.IllegalArgumentException

# Trace all except OutOfMemoryError
com.waratek.TraceExceptions=true
com.waratek.TraceExceptionsDisable=java.lang.OutOfMemoryError