DOCSEARCHbyAlgolia
Submit Docs

Tracy Profiler

repository·master·Indexed 10 days ago

https://github.com/wolfpld/tracy

A real-time, nanosecond-resolution, remote telemetry, hybrid frame and sampling profiler for games and high-performance applications. It supports CPU profiling for C, C++, Lua, Python, and Fortran, and GPU profiling for OpenGL, Vulkan, Direct3D 11/12, Metal, OpenCL, CUDA, and WebGPU. Version 0.13.1 provides capabilities for monitoring memory allocations, locks, context switches, and frame capture.

Tokens
50.3K
Snippets
104
Records
216
Agent score
96%

What's inside Tracy

  1. Overview of Tracy Profiler capabilities

    master

    Tracy is a real-time, nanosecond-resolution, remote telemetry profiler designed for games and high-performance applications. It provides a hybrid approach using both frame-based and sampling profiling.

    Key profiling capabilities include:

    • CPU Profiling: Direct support for C, C++, Lua, Python, and Fortran. Third-party bindings are available for Rust, Zig, C#, OCaml, Odin, and more.
    • GPU Profiling: Support for all major graphics and compute APIs, including OpenGL, Vulkan, Direct3D 11/12, Metal, OpenCL, CUDA, and WebGPU.
    • System Telemetry: Monitoring of memory allocations, locks, and context switches.
    • Frame Capture: Automatic attribution of screenshots to captured frames.

  2. What is Tracy Profiler?

    master

    Tracy is a real-time, nanosecond-resolution hybrid frame and sampling profiler designed for games and other interactive applications. It is used for remote or embedded telemetry and can profile:

    • CPU: Direct support for C, C++, Lua, Python, and Fortran (with third-party bindings for Rust, Zig, C#, etc.).
    • GPU: Support for OpenGL, Vulkan, Direct3D 11/12, Metal, OpenCL, CUDA, and WebGPU.
    • Other: Memory allocations, locks, context switches, and automatic screenshot attribution to captured frames.

    Unlike purely statistical profilers (like VTune or perf) that show hot spots, Tracy focuses on manual markup, allowing for frame-by-frame inspection of execution, multi-threaded interactions, and pinpointing the cause of semi-random frame stutters.

  3. Understand the Tracy Profiler Main Window

    master

    The Tracy Profiler UI is organized into three primary sections:

    1. Control Menu: The top row of buttons for managing connections, playback, and toggling specialized windows (Statistics, Flame Graphs, Memory, etc.).
    2. Frame Time Graph: A visual overview of frame durations, color-coded based on target FPS performance.
    3. Timeline Display: The core view showing the temporal flow of all captured data, including time scales, frame sets, sections, zones, locks, and plots.

    Specialized tools can be accessed via the Tools menu, which includes options like Playback (for frame images), CPU data (for context switches), Annotations, Limits, Wait stacks, and Frame statistics.

  4. Group and sort found zones

    master

    In the Find Zone window, the found zones section organizes results based on several grouping criteria. You can sort these groups by order, count, total time, or mean time per call.

    Grouping Modes

    • Thread: Shows which threads were executing the zone.
    • User text: Splits zones by custom user text (set via instrumentation).
    • Zone name: Groups by the name assigned to the zone.
    • Call stacks: Groups zones by their originating call stack. Use the and buttons to switch between stack groups and the  Select button to select a group.
    • Parent: Groups zones by their parent zone in the hierarchy (not by call stack).
    • No grouping: Displays zones in the order they appear.

    Interactions

    • Highlighting: Clicking a group name highlights that group's data on the histogram.
    • Resetting: Click the  Clear button to reset group selection.
    • Parent Navigation: In Parent mode, clicking the middle mouse button on a parent zone group switches the view to that parent zone.

  5. Estimating memory requirements for large traces

    master

    Tracy is designed to handle massive amounts of data, including traces with hundreds of millions of zones or long-running profiles (e.g., an hour of execution). However, increasing the number of zones increases both memory consumption and CPU overhead.

    When planning high-density instrumentation, use the following heuristic for memory allocation:

    • 100 million zones requires approximately 4 GB of RAM.

  6. Configure timing measurements in Instrumentation mode

    master

    In the Statistics window's Instrumentation mode, you can control how execution time is calculated via the Timing menu:

    • With children: Displays inclusive measurements (the time spent in the zone plus all its child zones).
    • Self only: Displays exclusive measurements (the time spent strictly within the zone, subtracting the time spent in child calls).
    • Non-reentrant: Displays inclusive time but only counts the first appearance of a given zone on a thread's stack.

  7. Interpret call stacks as return stacks

    master

    Crucially, call stacks are function return stacks, not call stacks. A frame in the stack represents where the current function will return to, not necessarily who called it.

    This distinction is vital for two reasons:

    1. Tail Call Optimization: If a function performs a tail call (e.g., return ComputeHash(b);), the compiler may reuse the current stack frame. The intermediate function (the caller) will be absent from the stack. The stack will show the caller of the original function, skipping the tail-called function entirely.
    2. Inlining/Optimizations: The frame below the current one is only guaranteed to be the return target. The actual call site might be in a different function or near the reported source line.

    Warning: Do not assume the frame below a function is its caller. If you see HandleRequest immediately following ComputeHash, it does not mean HandleRequest called ComputeHash directly; it means ComputeHash is returning to HandleRequest (likely because an intermediate function was tail-called or inlined).

  8. Identify and interpret wait stacks

    master

    Wait stacks represent periods where the program is paused, such as waiting for disk I/O, kernel routines, or hardware responses.

    You can identify a wait stack by looking for the wait_time field. Additional context for why the thread is waiting can be found in these optional fields:

    • wait_reason: An explanation of the wait (refer to wait_reason_hint for details).
    • wait_state: The state of the wait (refer to wait_state_hint for details).

  9. Use Symbol View modes (Source, Assembly, and Combined)

    master

    The Symbol View provides deep inspection of machine code units (functions). You can switch between three modes using the Mode selector:

    • Source: Displays only the source code. Each line that produced machine code shows an @ prefix indicating the count of associated assembly instructions. Use the Propagate inlines option (or press X) to see instruction costs attributed to inlined functions within the local call stack.
    • Assembly: Displays machine code disassembly.
      • Use Relative address to show offsets from the symbol start.
      • Use Source locations to show originating file names and line numbers next to assembly lines.
      • Use Raw code to show raw machine code bytes.
      • Use Jumps to visualize jumps as arrows.
    • Both (Combined): Displays source and assembly side-by-side. Hovering over a line in one pane highlights the corresponding line in the other. Clicking a source line repeatedly will cycle through the associated assembly instruction blocks.

  10. Handle text strings in Tracy macros

    master

    Tracy macros handle strings in two ways. Choosing the correct one depends on the lifetime of your data:

    1. Pointer-only macros (e.g., TracyMessageL(text)): The string must be a string literal or data that remains valid for the entire duration of the program (including after main exits). It must not be modified.
    2. Size-aware macros (e.g., TracyMessage(text, size)): The profiler copies the data into an internal buffer. The size parameter should be the length of the string (e.g., strlen(text)), excluding the null terminator. This is safer for dynamic strings but carries a small performance cost due to the copy.

    Constraint: Every text string passed to Tracy must be $\le$ 64 KB.

  11. Use Sampling mode to inspect inlined functions

    master

    When using Sampling mode (), the profiler displays symbols rather than just functions. Because sampling relies on call stack samples, time values are estimated. Key features for handling inlined functions include:

    • Inlining visibility: Symbols containing inlined functions show the count in parentheses. Use Show all () to expand them.
    • Aggregate (): Combines measurements for functions that are inlined multiple times within the same symbol.
    • Top inline (): Changes the Name column to display the name of the most time-consuming inline function instead of the base symbol.
    • Inlines (): Shows all functions without grouping them by symbol. Inlined functions are marked with a symbol and show their parent function in parentheses.
    • Location modes:
      • Entry: Points to the start of a non-inlined function or the compiler's insertion point for an inline.
      • Sample: Points to a random sampling point (useful for seeing where the sampler actually hit inside an inlined body).
      • Smart: Uses Entry for non-inlined functions and Sample for inlined functions.
      • @ Address: Displays the raw symbol address.

  12. Manage annotations with Annotation list and settings

    master

    Annotations allow you to mark specific points or regions on the timeline.

    Annotation List Window

    Lists all marked annotations. Actions available:

    • Visible (\u2714): Toggle visibility on the timeline.
    • Edit (\u25D8): Open the Annotation settings window.
    • Zoom (\uD83D\uDD2C): Zoom the timeline to the annotation's extent.
    • Remove (\uD83D\uDDD1): Remove the annotation (requires holding Ctrl).
    • Add annotation (\uD83D\uDCD8): Saves the current viewport as a new annotation.

    Annotation Settings Window

    Used to modify how an annotation is presented:

    • Set a custom text description.
    • Select a region highlight color.
    • Generate name (\uD83E\uDDB2): Generates a random description.