Skip to content

Simple C/C++ library for producing JSON traces suitable for Chrome's built-in trace viewer (about:tracing).

License

Notifications You must be signed in to change notification settings

hrydgard/minitrace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

242da50 · Oct 21, 2024

History

81 Commits
Apr 22, 2019
Mar 19, 2021
Apr 23, 2023
Apr 23, 2023
Mar 26, 2014
Jun 25, 2018
Apr 4, 2020
Oct 21, 2024
Apr 23, 2023
Jun 25, 2018
Jun 25, 2018

Repository files navigation

minitrace

by Henrik Rydgård 2014 (hrydgard+minitrace@gmail.com)

MIT licensed, feel free to use however you want. If you use it for something cool, I'd love to hear about it!

This is a C library with C++ helpers for producing JSON traces suitable for Chrome's excellent built-in trace viewer (chrome://tracing).

Extremely simple to build and use. Tested on Mac and Windows, but should compile anywhere you can use ANSI C with few or no changes.

Sample output (see example code below):

minitrace

Remember to be careful when interpreting the output. This is not a sampling profiler, so it only records start and stop times for blocks. This means that blocks grow even when the CPU is off running another thread, and that it can look like work is being done on more blocks at a time than you have CPUs.

How to use

  1. Include minitrace.c and minitrace.h in your project. #include minitrace.h in some common header.

  2. In your initialization code:

    mtr_init("trace.json");
  3. In your exit code:

    mtr_shutdown();
  4. Make sure MTR_ENABLED is defined globally when you want to profile, for example -DMTR_ENABLED

  5. In all functions you want to profile:

    // C
    MTR_BEGIN("GFX", "RasterizeTriangle")
    ...
    MTR_END("GFX", "RasterizeTriangle")
    // C++
    MTR_SCOPE("GFX", "RasterizeTriangle")
  6. In Google Chrome open "about:tracing"

  7. Click Open, and choose your trace.json

  8. Navigate the trace view using the WASD keys, and Look for bottlenecks and optimize your application.

  9. In your final release build, don't forget to remove -DMTR_ENABLED or however you set the define.

By default, it will collect 1 million tracepoints and then stop. You can change this behaviour, see the top of the header file.

Note: Please only use string literals in MTR statements.

Example code

int main(int argc, const char *argv[]) {
  int i;
  mtr_init("trace.json");

  MTR_META_PROCESS_NAME("minitrace_test");
  MTR_META_THREAD_NAME("main thread");

  int long_running_thing_1;
  int long_running_thing_2;

  MTR_START("background", "long_running", &long_running_thing_1);
  MTR_START("background", "long_running", &long_running_thing_2);

  MTR_BEGIN("main", "outer");
  usleep(80000);
  for (i = 0; i < 3; i++) {
    MTR_BEGIN("main", "inner");
    usleep(40000);
    MTR_END("main", "inner");
    usleep(10000);
  }
  MTR_STEP("background", "long_running", &long_running_thing_1, "middle step");
  usleep(80000);
  MTR_END("main", "outer");

  usleep(50000);
  MTR_INSTANT("main", "the end");
  usleep(10000);
  MTR_FINISH("background", "long_running", &long_running_thing_1);
  MTR_FINISH("background", "long_running", &long_running_thing_2);

  mtr_flush();
  mtr_shutdown();
  return 0;
}

The output will result in something looking a little like the picture at the top of this readme.

Future plans:

  • Builtin background flush thread support with better synchronization, no more fixed limit
  • Support for more trace arguments, more tracing types

If you use this, feel free to tell me how, and what issues you may have had. hrydgard+minitrace@gmail.com

About

Simple C/C++ library for producing JSON traces suitable for Chrome's built-in trace viewer (about:tracing).

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published