tracy-profiler
Haskell bindings for Tracy frame profiler.
Setup
Installing
This version of the bindings targets Tracy 0.15.
Older releases have a different C API and will fail to link or misbehave.
You can install the prebuilt package from your distribution if it ships that release:
sudo apt install libtracy-dev tracy-capture tracy-profiler
Or you can download and build one yourself and point your project to it:
# stack.yaml
extra-lib-dirs:
- upstream/_build/library
extra-include-dirs:
- upstream/tracy/public/tracy
You can use the provided Makefile that will do the thing:
make all # fetch and build stuff
make test # run the example
upstream/_build/profiler/tracy-profiler & disown # launch the profiler GUI
Everything is built in release mode.
Add DEBUG=1 to any of those make commands for a debug build in upstream/_build-debug.
Debug builds keep Tracy's assertions on.
To use the debug library in your own project, point extra-lib-dirs at upstream/_build-debug/library.
This way you can customize configuration.
Make sure you update package flags to match.
The Makefile builds the library with TRACY_NO_CRASH_HANDLER.
That means the viewer won't get crash reports.
Tracy's crash handler treats SIGPIPE as a crash.
GHC's threaded runtime sends that signal to cancel interruptible foreign calls.
With the handler in place, killThread on a thread inside such a call aborts the program while a profiler is connected.
Any library built with the handler has this problem.
Check whether a distribution package was built with it.
Either way, you have to ensure that tracy-capture/tracy-profiler is built with the same version.
Otherwise it will connect and immediately refuse to record anything.
Flags
The flags must match whatever the library has been built with.
By default all the instrumentation wrappers do nothing.
That means you don't have to ifdef your code to remove the wrappers when they're not needed.
You have to set the enable flag in your project for the data to be collected.
flags:
tracy-profiler:
enable: true
# manual_lifetime: false
# on_demand: false
# fibers: false
To use on-demand mode, set the on_demand flag and link against a library built with TRACY_ON_DEMAND.
make library-on-demand builds one in upstream/_build/library-on-demand.
Point extra-lib-dirs there to use it.
The flag has to match the library.
The C API symbols don't encode that setting.
A mismatch links fine and then misbehaves at runtime.
Instrumentation
Use the functions from System.Tracy and System.Tracy.Zone to collect data:
{-# LANGUAGE MagicHash #-} -- "static strings"#
{-# LANGUAGE OverloadedLabels #-} -- #fuchsia colors
{-# LANGUAGE OverloadedStrings #-} -- "yes"
module Main where
import Control.Monad (unless, when)
import System.Exit (die)
import System.IO (hPutStrLn, stderr)
import qualified System.Tracy as Tracy
import qualified Data.Text as Text
main :: IO ()
main = Tracy.withProfiler $ do
when Tracy.enabled do
hPutStrLn stderr "Waiting for tracy-capture or tracy-profiler to connect on port 8086"
isConnected <- Tracy.waitConnected 100000 (Just 30_000_000)
unless isConnected $ die "Nothing connected within 30 seconds"
Tracy.withSrcLoc "main.nowhereInParticular" #f0fa do
Tracy.messageL "hi there"# -- static strings require no copying to be logged
mapM_ runFrame [0..600]
runFrame :: Int -> IO ()
runFrame ix = Tracy.withSrcLoc "runFrame" #fcc do
Tracy.frameMark_
let factorial = product [1 .. toInteger ix]
let !digits = length (show factorial)
Tracy.message . Text.pack $
-- runtime strings will require some memcpy'ng around, use sparingly on hot paths
"!" <> show ix <> " has " <> show digits <> " digits"
Tracy.plotInt "digits"# digits
Other modules cover more of the C API:
System.Tracy.Memory reports allocations and frees.
System.Tracy.Section marks high-level stretches of execution, such as a game level.
Sections can overlap and aren't tied to a thread.
System.Tracy.Lock and System.Tracy.SharedLock report waiting on and holding a lock.
Give each one a location from System.Tracy.SourceLocation.newSourceLocation.
The location stays allocated for the rest of the program because Tracy reads it later.
Wait, obtain, shared release and mark events are recorded against the current OS thread.
Use a bound thread to get them on the right timeline.
Tracy 0.15's C API records a successful SharedLock.tryAcquireShared as an exclusive hold.
The matching releaseShared doesn't end that hold.
System.Tracy.Zone.withSourceLocation runs a zone from a location made once with newSourceLocation.
withSrcLoc allocates a new location for every zone instead.
System.Tracy.Gpu reports work done on the GPU.
You issue the GPU timestamp queries yourself.
Zones take an action that writes one and returns its query id.
They call it at each end of the zone.
Once the GPU has the results, pass each query id and its timestamp to Gpu.time in the order the queries were written.
After that, the id can be reused.
Tracy takes the first timestamp it gets for a zone as its start.
newContext takes the length of a GPU tick in nanoseconds and a current GPU timestamp.
Use newCalibratedContext instead for contexts that will get calibration events.
The C API doesn't hand out context ids.
Choose them from 0 to 255 yourself.
Don't reuse ids of contexts made by C++ code in the same program.
Tracy keeps one zone stack per context created through the C API.
Zones in a context have to nest even across threads.
With on_demand, a zone that starts before a viewer connects isn't recorded.
Its timestamp actions aren't called.
The module uses Tracy's serialized queue.
It works from any thread.
The unserialized GPU functions in System.Tracy.FFI are cheaper.
They need all events for a context to come from one OS thread.
frameImage pixels width height lag flipped attaches a screenshot to a frame.
The pixels are RGBA.
The width and height have to be multiples of 4.
Tracy copies the pixels before frameImage returns.
lag counts how many frames ago the image was taken.
flipped means the rows go from bottom to top, as in OpenGL.
Call stack depths are only available through System.Tracy.FFI so far.
beginSamplingProfiling and endSamplingProfiling only take effect in a library built with TRACY_SAMPLING_PROFILER_MANUAL_START.
Collecting and viewing
Start tracy-capture before running the test to avoid empty areas where nothing happens:
tracy-capture -fo output.tracy &
After running the code, upload the collected data to the viewer.
You'll see something like this:

Are those are GC pauses we're looking at? 🤔
Sampling
On Linux, Tracy also samples call stacks and records context switches when kernel.perf_event_paranoid allows it.
Otherwise it logs a series of debug messages about failing to set up system tracing and carries on without it.
Sampled call stacks show up as ghost zones on threads that have no zones of their own.
In Haskell code, only the top frame of each sample can be trusted.
Tracy has the kernel build the rest by following frame pointers.
GHC uses the frame pointer register (rbp on x86-64) as its Haskell stack pointer instead.
The frames past the top one are leftovers from the Haskell stack.
Set TRACY_NO_SAMPLING=1 in the program's environment to skip sampling while keeping context switches.
Ghost zones can also be hidden in the viewer.
Tracy names sampled frames from debug info or from the symbols an executable exports.
A GHC-built program has neither by default.
Its own frames show as [unknown].
Add -optl-rdynamic to the executable's ghc-options to export them.
That names frames in the RTS, the Tracy client and Haskell code.
Haskell names come out in GHC's encoded form, such as Main_main_info.
RTFM
You really should go read the official manual.
Yes, BEFORE you run into corrupted memory, surprising grouppings, or otherwise botched profiling runs.