Tracy.jl

@tracepoint "name" color=<color> enabled=<expr> <expression>

Code you'd like to trace should be wrapped with @tracepoint

@tracepoint "name" <expression>

Typically the expression will be a begin-end block:

@tracepoint "data aggregation" begin
    # lots of compute here...
end

The name of the tracepoint must be a literal string, and it cannot be changed at runtime. The tracepoint can be dynamically disabled or enabled by using the enabled keyword argument which should be a boolean expression.

The (default) color of the zone can be configured with the color keyword argument to the macro which should be a literal that can either be:

• An integer: The hex code of the color as 0xRRGGBB.
• A symbol: Can take the value :black, :blue, :green, :cyan, :red, :magenta, :yellow, :white, :light_black, :light_blue, :light_green, :light_cyan, :light_red, :light_magenta, :light_yellow, :light_white.
• A tuple of three integers: The RGB value (R, G, B) where each value is in the range 0..255.

You can also trace function definitions where name of the tracepoint will be the name of the function unless it is explicitly provided:

@tracepoint function f(x)
    x^2
end

@tracepoint "calling g" g(x) = x^2

h = @tracepoint x -> x^2

If you don't have Tracy installed, you can install TracyProfiler_jll and start it with run(TracyProfiler_jll.tracy(); wait=false).

julia> x = rand(10,10);

julia> @tracepoint "multiply" x * x;

julia> @tracepoint "pow2" color=:green x^2; # green

julia> @tracepoint "pow3" color=:0xFF0000 x^3; # red

julia> @tracepoint "pow4" color=(255, 165, 0) x^4; # orange

julia> timings_enabled() = rand() < 0.5;

julia> @tracepoint "pow5" enabled=timings_enabled() x^5; # enabled only if timings_enabled() is true

If you don't have Tracy installed, you can install TracyProfiler_jll and start it with run(TracyProfiler_jll.tracy(); wait=false).

tracymsg(msg::AbstractString; color::Union{Integer,Symbol,NTuple{3, Integer}, Nothing}=nothing, callstack_depth::Integer=0)

Send a message to Tracy that gets shown in the "Message" window. If color is nothing, the default color is used. Otherwise, the color argument can be given as:

• An integer: The hex code of the color as 0xRRGGBB.
• A symbol: Can take the value :black, :blue, :green, :cyan, :red, :magenta, :yellow, :white, :light_black, :light_blue, :light_green, :light_cyan, :light_red, :light_magenta, :light_yellow, :light_white.
• A tuple of three integers: The RGB value (R, G, B) where each value is in the range 0..255.

The callstack_depth argument determines the depth of the callstack that is collected.

Register this module's @tracepoint callsites with Tracy.jl

This will allow tracepoints to appear in Tracy's Enable/Disable window, even if they haven't been run yet. Using this macro is optional, but it's recommended to call it from within your module's __init__ method.

enable_tracepoint

Enable/disable a set of tracepoint(s) in the provided modules, based on whether they match the filters provided for name/func/file.

configure_tracepoint

Enable/disable a set of tracepoint(s) in the provided modules by invalidating any existing code containing the tracepoint(s).

wait_for_tracy(;timeout::Float64 = 20.0)

Waits up to timeout seconds for libtracy to connect to a listening capture agent. If a timeout occurs, throws an InvalidStateException.

capture(outfile::String; port::Integer = 9001)
gui(; port::Integer = 9001)

Starts a Tracy capture agent running in the background. Returns the Cmd object for use with wait(). Note that if you are using a tracy-enabled build of Julia, you will need to ensure that the capture agent is running before the Julia executable starts, otherwise the capture agent may not see the beginning of every zone, which it considers to be a fatal error.

The recommended methodology for usage of this function is something similar to:

    port = 9000 + rand(1:1000)
    p = Tracy.capture("my_workload.tracy"; port)
    run(addenv(`$(Base.julia_cmd()) workload.jl`,
               "TRACY_PORT" => string(port),
               "JULIA_WAIT_FOR_TRACY" => "1"))
    wait(p)