Usage

Tracing your application

To trace a Python application foo.py, load it via functiontrace.

$ functiontrace foo.py <arguments_for_foo>

Alternatively, you can modify your code to start tracing at some point during its runtime.

import functiontrace
functiontrace.trace()

By default, FunctionTrace will emit a trace file (in the form of functiontrace.time.json.gz) to the current directory, though the location can be controlled via the --output-dir switch when running functiontrace. Additionally, FunctionTrace will create a symlink named functiontrace.latest.json.gz pointing to the most recently generated trace file.

$ functiontrace foo.py <arguments_for_foo>
...
$ ls -l
foo.py
functiontrace.2025-07-18-21:56:23.718.json.gz
functiontrace.latest.json.gz -> functiontrace.2025-07-18-21:56:23.718.json.gz

Viewing Traces

To view a recorded trace file, go to the Firefox Profiler and choose Load a profile from file, then select the desired trace file. This step will perform some processing, but is entirely local - your trace file never leaves your own machine!

Note: If this is your first time using the Firefox Profiler, you may want to skim the UI guide for it.

You'll likely want to start with the Stack Chart view to get an overview of your application's execution, then use the Flame Graph view if you want to dive into optimization opportunities.

Traces can also be loaded directly from the internet, which can be particularly useful when examining services on remote servers or sharing traces with others. For an example, you can play with this Live Demo.