tracy(1)

Tracy is a frame profiler, supporting manual code instrumentation +and providing a sampling profiler.

One can either record and visualize the profiling data live using +tracy-profiler or record the profiling data to a file using tracy-capture.

tracy-profiler [file] [-p port]
+
+tracy-capture -o file [-f] [-p port]
+    -f   overwrite <file> if it exists
+

Example

The example showcases different cases:

Use tracy from a single binary. In that case the TracyClient.cpp can be +directly linked / included in the instrumented binary.
Use tracy from different binaries (eg main executable + shared library). In +this case the TracyClient.cpp should be compiled into its own shared +library, such that there is a single tracy client.
Use tracy from different binaries on windows. In this case the +TracyClient.cpp must be compiled again into a separate shared library, +while defining TRACY_EXPORTS. The code being instrumented must be compiled +with TRACY_IMPORTS defined.

An instrumented c++ example:

#include <chrono>
+#include <thread>
+
+#include <tracy/Tracy.hpp>
+
+#ifdef USE_FOO
+extern "C" void foo_comp_hook(int64_t);
+#endif
+
+void init() {
+  // Create a named zone (active for the current scope).
+  // Name will be used when rendering the zone in the thread timeline.
+  ZoneScopedN("init()");
+  // Set explicit color for the rendered zone.
+  ZoneColor(0xff0000);
+
+  std::this_thread::sleep_for(std::chrono::seconds(1));
+}
+
+void comp(const char* name) {
+  // Track call count.
+  static int64_t ccnt = 0;
+  ccnt += 1;
+
+  // Create an unnamed zone for the current scope.
+  ZoneScoped;
+  // Name the zone by formatting the name dynamically.
+  // This name is shown for the zone in the thread timeline, however
+  // in the zone statistics they are all accounted under one common
+  // zone "comp".
+  ZoneNameF("comp(%s)", name);
+  // Additional text to attach to the zone.
+  ZoneTextF("text(%s)", name);
+  // Additional value to attach to the zone measurement.
+  ZoneValue(ccnt);
+
+  // Statistics for dynamic names, text and values can be looked at in the zone
+  // statistics.There measurements can be grouped by different categories.
+
+  // Add a simple plot.
+  TracyPlot("comp-plot", ccnt % 4);
+
+  std::this_thread::sleep_for(std::chrono::milliseconds(100));
+
+#ifdef USE_FOO
+  foo_comp_hook(ccnt);
+#endif
+}
+
+void post_comp() {
+  // Create an unnamed zone for the current scope and capture callstack (max
+  // depth 10). Capturing callstack requires platform with TRACY_HAS_CALLSTACK
+  // support.
+  ZoneScopedS(10);
+  // Name the zone, w/o formatting.
+  const char name[] = "post_comp()";
+  ZoneName(name, sizeof(name));
+
+  // Add trace messages to the timeline.
+  TracyMessageL("start sleep in post_comp()");
+  std::this_thread::sleep_for(std::chrono::milliseconds(50));
+  TracyMessageL("end sleep in post_comp()");
+}
+
+void fini() {
+  // Create a named zone with an explicit color.
+  ZoneScopedNC("fini()", 0x00ff00);
+  std::this_thread::sleep_for(std::chrono::seconds(1));
+}
+
+int main() {
+  // Create a named zone.
+  ZoneScopedN("main()");
+
+  init();
+
+  int step = 0;
+  while (step++ < 10) {
+    // Create a frame message, this start a new frame with the name
+    // "step" and end the previous frame with the name "step".
+    FrameMarkNamed("step");
+    // Create a named scope.
+    ZoneScopedN("step()");
+    comp("a");
+    comp("b");
+    comp("c");
+    post_comp();
+  }
+
+  fini();
+}
+

An instrumented c example:

#include <stdint.h>
+#include <inttypes.h>
+#include <stdio.h>
+
+#include <tracy/TracyC.h>
+
+static void comp_helper(int64_t i) {
+  char buf[64];
+  int cnt = snprintf(buf, sizeof(buf), "helper(%" PRId64 ")", i);
+
+  // Create an active unnamed zone.
+  TracyCZone(ctx, 1);
+
+  // Name the zone.
+  TracyCZoneName(ctx, buf, cnt);
+  // Add custom text to the zone measurement.
+  TracyCZoneText(ctx, buf, cnt);
+  // Add custom value to the zone measurement.
+  TracyCZoneValue(ctx, i);
+
+  for (int ii = 0; ii < i * 100000; ++ii) {
+    /* fake work */
+  }
+
+  // End the zone measurement.
+  TracyCZoneEnd(ctx);
+}
+
+void foo_comp_hook(int64_t cnt) {
+  // Create an active named zone.
+  TracyCZoneN(ctx, "foo", 1);
+
+  for (int i = 0; i < cnt; ++i) {
+    // Plot value.
+    TracyCPlot("foo_comp_hook", cnt + i);
+
+    comp_helper(i);
+  }
+
+  // Configure plot "foo", probably best done once during initialization..
+  TracyCPlotConfig("foo", TracyPlotFormatNumber, 1 /* step */, 1 /* fill */,
+                   0xff0000);
+  // Plot value.
+  TracyCPlot("foo", cnt);
+
+  // End the zone measurement.
+  TracyCZoneEnd(ctx);
+}
+

Raw build commands to demonstrate compiling tracy w/o cmake, in case we need +to integrate it into a different build system.

B := BUILD
+
+main: $(B)/main-static $(B)/main-dynamic $(B)/main-dynamic-win
+tracy: $(B)/tracy
+.PHONY: main tracy
+
+# -- TRACY STATIC ---------------------------------------------------------------
+
+$(B)/main-static: main.cpp | $(B)
+	clang++ -DTRACY_ENABLE -I$(B)/tracy/public -o $@ $^ $(B)/tracy/public/TracyClient.cpp
+
+# -- TRACY DYNAMIC --------------------------------------------------------------
+
+$(B)/main-dynamic: main.cpp $(B)/foo.so $(B)/TracyClient.so | $(B)
+	clang++ -DTRACY_ENABLE -I$(B)/tracy/public -DUSE_FOO -o $@ $^
+
+$(B)/foo.so: foo.c $(B)/TracyClient.so
+	clang -DTRACY_ENABLE -I$(B)/tracy/public -fPIC -shared -o $@ $^
+
+$(B)/TracyClient.so: $(B)/tracy/public/TracyClient.cpp
+	clang++ -DTRACY_ENABLE -I$(B)/tracy/public -fPIC -shared -o $@ $^
+
+# -- TRACY DYNAMIC WINDOWS ------------------------------------------------------
+
+$(B)/main-dynamic-win: main.cpp $(B)/foo.dll $(B)/TracyClient.dll
+	@# eg run with wine
+	zig c++ -target x86_64-windows -DTRACY_ENABLE -DTRACY_IMPORTS -DUSE_FOO -o $@ $^ -I $(B)/tracy/public
+
+$(B)/foo.dll: foo.c $(B)/TracyClient.dll
+	zig c++ -target x86_64-windows -DTRACY_ENABLE -DTRACY_IMPORTS -fPIC -shared -o $@ $^ -I $(B)/tracy/public
+
+$(B)/TracyClient.dll: $(B)/tracy/public/TracyClient.cpp
+	@# win libs from 'pragma comment(lib, ..)'
+	zig c++ -target x86_64-windows -DTRACY_ENABLE -DTRACY_EXPORTS -fPIC -shared -o $@ $^ -lws2_32 -ldbghelp -ladvapi32 -luser32
+
+# -- TRACY ----------------------------------------------------------------------
+
+# Get latest tracy and build profiler.
+$(B)/tracy: $(B)
+	cd $(B); bash $(CURDIR)/get-tracy.sh
+.PHONY: $(B)/tracy
+
+$B:
+	mkdir -p $(B)
+.PHONY: $(B)
+
+# -- CLEAN ----------------------------------------------------------------------
+
+clean:
+	$(RM) $(B)/*.so $(B)/*.dll $(B)/*.pdb $(B)/*.lib $(B)/main*
+
+distclean:
+	rm -rf $(B)
+

+
Find get-tracy.sh here.
+

+ +

Notes

tracy(1)

Example