Crate tracy_gizmos

Crate tracy_gizmos 

Source
Expand description

Bindings for the client library of the Tracy profiler.

Refer to the Tracy manual for details and profiler server usage.

§How to use

Add tracy-gizmos to your Cargo.toml:

[dependencies]
tracy-gizmos = { version = "0.0.1", features = ["enabled"] }

Note that instrumentation is disabled by default.

The usage is pretty straight-forward (for more details read the docs):

fn main() {
    let tracy = tracy_gizmos::start_capture();
    tracy_gizmos::zone!("main");
    work();
}

The #[instrument] attribute provies an easy way to add Tracy zones to functions. A function annotated with #[instrument] will create and enter a zone with that function’s name everytime the function is called.

For example:

ⓘ
#[tracy_gizmos::instrument]
fn work() {
    // do stuff
}

You can find more examples showing how to use this crate here.

§Features

  • enabled - enables the instrumentation and everything related to it.
  • attributes - includes support for the #[instrument] attribute.
  • unstable-function-names (nightly only) - includes the enclosing function name into every zone without additional runtime overhead.

§Tracy features

Tracy client functionality can be controlled pretty granularly. Refer to the Tracy’s manual for more details. A corresponding define is listed for each feature, which can be used to search the Tracy’s documentation or source code, if needed.

The following features are available:

  • crash-handler - enables Tracy’s crash handler, which intercepts application crashes and ensures the remaining profiling data is sent to the server together with a crash report details. Influences TRACY_NO_CRASH_HANDLER.
  • system-tracing - enables system-level tracing information collection (assuming that the profiled program was granted the priveleges needed, e.g. run as root or Administrator). Influences TRACY_NO_SYSTEM_TRACING.
  • context-switch - enables context switch information collection (assuming having the privelege, as above), which allows to see when a zone was actually executed or was waiting to be resumed. Influences TRACY_NO_CONTEXT_SWITCH.
  • sampling - enables the callstack sampling to augment instrumented data (requires privelege escalation on Windows). Influences TRACY_NO_SAMPLING.
  • callstack-inlines - enables the inline frames retrieval in callstacks, which provides more precise information but is magnitude slower. Influences TRACY_NO_CALLSTACK_INLINES.
  • hw-counters - enables the hardware performance counters sampling (available only on Linux or WSL): IPC, branch mispredicts, cache misses. Influences TRACY_NO_SAMPLE_RETIREMENT, TRACY_NO_SAMPLE_BRANCH and TRACY_NO_SAMPLE_CACHE.
  • code-transfer - enables the executable code retrieval, which captures parts of the application code for further analysis in Tracy. Be extra careful when working with non-public code! Influences TRACY_NO_CODE_TRANSFER.
  • vsync - enables the hardware Vsync events capture (assuming having the privilege), which will be reported as frame events per monitor. Influences TRACY_NO_VSYNC_CAPTURE.
  • no-exit - enables the short-lived application profiling improvement. When TRACY_NO_EXIT environment variable is set to 1, profiled application will wait for the server connection to transfer the data, even if it has already finished executing. Influences TRACY_NO_EXIT.
  • broadcast - enables the local network announcement, so profiling servers can find the client. Influences TRACY_NO_BROADCAST.
  • only-localhost (enabled by default) - restricts Tracy to only listening on the localhost network interface. Influences TRACY_ONLY_LOCALHOST.
  • only-ipv4 - restricts Tracy to only listenting on IPv4 network interfaces. Influences TRACY_ONLY_IPV4.

Macros§

emit_allocenabled
Marks a memory allocation event.
emit_freeenabled
Marks a memory freeing event.
frameenabled
Marks the completed frame end moment.
make_plotenabled
Creates and configures the plot.
messageenabled
Sends a message to Tracy’s log.
plot
Takes a value, emits it into the specific plot and returns the value back.
set_thread_nameenabled
Sets the current thread’s name.
zoneenabled
Instruments the current scope with a profiling zone.

Structs§

Color
Represents a color.
Frame
Discontinuous frame.
Plot
Plotting mechanism.
PlotConfig
A plot configuration, which controls the way plot will be displayed.
TracyCapture
Represents an active Tracy capture.
Zone
Profiling zone.

Enums§

PlotFormat
An enum representing the plot values display format.
PlotStyle
An enum representing the plot style.

Traits§

PlotEmit
The PlotEmit trait allows for value emission into a plot.

Functions§

app_info
Tracy can collect additional information about the profiled application, which will be available in the trace description. This can include data such as the source repository revision, crate version, application’s environment, etc.
start_capture
Starts the Tracy capture.

Attribute Macros§

captureattributes
Instruments a function to create and start a profiling capture session.
instrumentattributes
Instruments a function to create and enter a zone every time the function is called.