# Tracing stylesheet execution

As an aid to stylesheet design and performance analysis, the library includes an execution trace facility. To enable tracing, call `set_trace_listener (a_trace_listener: XM_XSLT_TRACE_LISTENER)` on your `XM_XSLT_CONFIGURATION`.

## The default trace listener

The library provides one descendant of `XM_XSLT_TRACE_LISTENER`, namely `XM_XSLT_DEFAULT_TRACE_LISTENER`. This class writes trace records as XML text, optionally with timing information added, to the `info_file: KI_TEXT_OUTPUT_STREAM` of an `UT_ERROR_HANDLER`. A suitable `UT_ERROR_HANDLER` is available in `XM_XSLT_CONFIGURATION` as `error_reporter`.

This trace listener generates a large quantity of data for long-running transforms.

## Writing your own trace listener

If you wish to write your own trace listener, then you need to look at `XM_XSLT_TRACE_DETAILS`. In particular the feature `properties`. To find out what properties can be present in the trace details, you can search the library source code, and inspect `XM_XSLT_DEFAULT_TRACE_LISTENER`.

TODO: document these properties.

## Suspending tracing

It may be desirable to trace only parts of the execution path. In which case a mecahnism is needed to turn tracing on and off. No such mechanism is available right now. One possibility is to use XPath extension functions to pause and resume tracing (this is what Saxon does). Another possibility would be to use extension attributes, or extension instructions.