Support for external profilers

The page is in the process of being translated.

Julia provides explicit support for some external trace profilers, which allows you to get general information about the behavior of the runtime environment.

The following profilers are currently supported:

Adding new zones

The macro JL_TIMING is used to add new zones. To find examples in the code base, do a search for JL_TIMING'. To add a new zone type, add it to `JL_TIMING_OWNERS (and possibly `JL_TIMING_EVENTS').

Dynamic activation and deactivation of zones

Environment variable JULIA_TIMING_SUBSYSTEMS allows you to enable or disable zones for a specific Julia launch. For example, when setting a variable value to +GC,-INFERENCE', the `GC zones will be enabled and the INFERENCE zones will be disabled.

The Tracy Profiler

https://github.com/wolfpld/tracy [Tracy] is a flexible profiler that can be further integrated with Julia.

Building Julia using Tracy

To enable Tracy integration, build Julia with the additional parameter WITH_TRACY=1 in the 'Make.user` file.

Installing the Tracy Profile Viewer

The easiest way to get the profile viewer is to add the TracyProfiler_jll package and run the profiler as follows:

run(TracyProfiler_jll.tracy())

In macOS, you can set the environment variable TRACY_DPI_SCALE to 1.0 if the user interface elements in the profiler seem excessively large.

To run an instance without a user interface that saves the trace to disk, use

run(`$(TracyProfiler_jll.capture()) -o mytracefile.tracy`)

instead of her.

For information about using the Tracy user interface, see the Tracy manual.

Profiling Julia using Tracy

The standard workflow for profiling Julia using Tracy involves running Julia using an environment variable.:

JULIA_WAIT_FOR_TRACY=1 ./julia -e '...'

The environment variable ensures that Julia will wait for a successful connection to the Tracy profiler and then continue execution. After that, in the user interface of the Tracy profiler, click Connect. Julia execution should resume and profiling should begin.

Profiling pre-compilation of packages using Tracy

To profile the pre-compilation process of a package, the easiest way is to explicitly call Base.compilecache with the package that needs to be pre-compiled.:

pkg = Base.identify_package("SparseArrays")
withenv("JULIA_WAIT_FOR_TRACY" => 1, "TRACY_PORT" => 9001) do
    Base.compilecache(pkg)
end

Here we are using a custom port for Tracy to make it easier to find the right client in the Tracy user interface to connect to.

Adding metadata to zones

To add a row (or rows) to a zone, you can use the various functions jl_timing_show_* and `jl_timing_printf'. For example, the trace area for the output shows an instance of the method that is being output.

Using the 'TracyCZoneColor` function, you can set the color of a specific zone. Review the code base to understand how it is used.

Viewing Tracy files in the browser

On the website at https://topolarity.github.io/trace-viewer / you can find the (experimental) web-based tracing viewer Tracy.

You can open a local .tracy file or specify a URL from the Internet (for example, a file in the Github repository). If you download a trace file from the Internet, you can also directly share the URL of the page with other users so that they can view the same trace.

Enabling stack trace samples

To enable call stack sampling in Tracy, build Julia with the following parameters in the Make.user file:

WITH_TRACY := 1
WITH_TRACY_CALLSTACKS := 1
USE_BINARYBUILDER_LIBTRACYCLIENT := 0

You may also need to run the make -C deps clean-libtracyclient command to force the Tracy rebuild.

This feature has a significant impact on trace size and profiling costs, so it is recommended to disable call stack sampling whenever possible, especially if you intend to share trace files online.

Note that the JIT runtime in Julia has not yet been integrated to symbolize Tracy, so Julia functions will usually be unknown in these stack traces.

Intel VTune Profiler (ITTAPI)

this section has not been written yet.