Debug.Trace.ByteString

ByteString variant of the tracing functions in Debug.Trace.

Eventlog tracing

Eventlog tracing is a performance profiling system. These functions emit extra events into the eventlog. In combination with eventlog profiling tools these functions can be used for monitoring execution and investigating performance problems.

Currently only GHC provides eventlog profiling, see the GHC user guide for details on how to use it. These function exists for other Haskell implementations but no events are emitted.

traceEvent :: ByteString -> a -> a

ByteString variant of traceEvent.

\(O(n)\) This function copies the ByteString to convert it to a null-terminated CString.

Note that this function doesn't evaluate the ByteString if user tracing in eventlog is disabled.

The input should be shorter than \(2^{16}\) bytes. Otherwise the RTS generates a broken eventlog.

traceEventIO :: ByteString -> IO ()

ByteString variant of traceEventIO.

\(O(n)\) This function copies the ByteString to convert it to a null-terminated CString.

Note that this function doesn't evaluate the ByteString if user tracing in eventlog is disabled.

The input should be shorter than \(2^{16}\) bytes. Otherwise the RTS generates a broken eventlog.

unsafeTraceEvent :: ByteString -> a -> a

ByteString variant of traceEvent.

\(O(1)\) This function is unsafe in the way that it doesn't ensure the input string to be null-terminated. It is user's responsibility to null-terminate the input.

Note that this function doesn't evaluate the ByteString if user tracing in eventlog is disabled.

The input should be shorter than \(2^{16}\) bytes. Otherwise the RTS generates a broken eventlog.

unsafeTraceEventIO :: ByteString -> IO ()

ByteString variant of traceEventIO.

\(O(1)\) This function is unsafe in the way that it doesn't ensure the input string to be null-terminated. It is user's responsibility to null-terminate the input.

Note that this function doesn't evaluate the ByteString if user tracing in eventlog is disabled.

The input should be shorter than \(2^{16}\) bytes. Otherwise the RTS generates a broken eventlog.

Execution phase markers

When looking at a profile for the execution of a program we often want to be able to mark certain points or phases in the execution and see that visually in the profile.

For example, a program might have several distinct phases with different performance or resource behaviour in each phase. To properly interpret the profile graph we really want to see when each phase starts and ends.

Markers let us do this: we can annotate the program to emit a marker at an appropriate point during execution and then see that in a profile.

Currently this feature is only supported in GHC by the eventlog tracing system, but in future it may also be supported by the heap profiling or other profiling tools. These function exists for other Haskell implementations but they have no effect.

traceMarker :: ByteString -> a -> a

ByteString variant of traceMarker.

\(O(n)\) This function copies the ByteString to convert it to a null-terminated CString.

Note that this function doesn't evaluate the ByteString if user tracing in eventlog is disabled.

The input should be shorter than \(2^{16}\) bytes. Otherwise the RTS generates a broken eventlog.

traceMarkerIO :: ByteString -> IO ()

ByteString variant of traceMarkerIO.

\(O(n)\) This function copies the ByteString to convert it to a null-terminated CString.

Note that this function doesn't evaluate the ByteString if user tracing in eventlog is disabled.

The input should be shorter than \(2^{16}\) bytes. Otherwise the RTS generates a broken eventlog.

unsafeTraceMarker :: ByteString -> a -> a

ByteString variant of traceMarker.

\(O(1)\) This function is unsafe in the way that it doesn't ensure the input string to be null-terminated. It is user's responsibility to null-terminate the input.

Note that this function doesn't evaluate the ByteString if user tracing in eventlog is disabled.

The input should be shorter than \(2^{16}\) bytes. Otherwise the RTS generates a broken eventlog.

unsafeTraceMarkerIO :: ByteString -> IO ()

ByteString variant of traceMarkerIO.

\(O(1)\) This function is unsafe in the way that it doesn't ensure the input string to be null-terminated. It is user's responsibility to null-terminate the input.

Note that this function doesn't evaluate the ByteString if user tracing in eventlog is disabled.

The input should be shorter than \(2^{16}\) bytes. Otherwise the RTS generates a broken eventlog.