Profiling with Tracy

⚠️ This wiki is under construction. Pages are being populated incrementally.

Profiling with Tracy

Nodens integrates Tracy Profiler for real-time frame profiling, memory tracking, and lock contention analysis.

Overview

Enabling Profiling in a Build

Tracy instrumentation is compiled in only for the Profiling configuration. Debug and Release leave every Tracy macro as a no-op, so a build in those configurations produces no profiling data.

Profiling mirrors Release code generation and adds debug symbols (-g) and frame pointers (-fno-omit-frame-pointer). Timings therefore transfer to the shipped build, and callstacks resolve.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Profiling
cmake --build build

To build the profiler GUI from the vendored Tracy source, configure with ND_BUILD_TRACY_PROFILER=ON and build the tracy-profiler target:

cmake -S . -B build -G Ninja \
    -DCMAKE_BUILD_TYPE=Profiling \
    -DND_BUILD_TRACY_PROFILER=ON
cmake --build build
cmake --build build --target tracy-profiler

The profiler GUI is a separate CMake project that vendors its own dependencies, so it is driven by ExternalProject and excluded from the default build; build it by target name. The build also needs capstone and the thin-LTO archiving tools (llvm-ar, llvm-ranlib).

The client and the profiler must be the same Tracy version. The pinned revision lives in cmake/NodensDependencies.cmake, currently v0.14.1.

Connecting the Tracy Profiler

What Nodens Instruments by Default

• Frame marks. FrameMark at the end of Application::Run(), so the profiler shows a frame timeline.
• CPU zones. ZoneScoped on the framework's hot paths: Application construction, teardown, and the main loop; EventBus dispatch and flush; the ImGuiLayer frame; and each JobSystem worker task. Named worker threads appear as separate tracks.
• Plots and locks. TracyPlot("Job Queue Size", ...) tracks the pending task count, and the job queue mutex uses TracyLockable for contention views.
• Vulkan GPU timing. VulkanContext owns one TracyVkCtx per frame-in-flight command buffer. The ImGui pass records a TracyVkZone; collection happens after the frame fence. Validation layers are Debug-only, so they never serialize GPU work during a Profiling capture.

Adding Custom Zones

Custom Plots

Reading the Tracy UI

See Also

• Concurrency and JobSystem — Thread pool profiling.
• Examples Guide — The asyncevent example includes a profiling showcase.
• Tracy Documentation