Tracer - Lightweight Performance Tracing Library

Tracer is a header-only lightweight performance tracing library for recording and analyzing C++ program execution. It helps developers identify performance bottlenecks, analyze function execution times, and outputs results in Chrome Tracing compatible format for easy visualization.

Features

• Easy Integration: Just include a single header file
• Low Overhead: Designed to minimize impact on the analyzed program
• Visualization Friendly: Generates Chrome Tracing compatible JSON output
• Thread-Safe: Supports multi-threaded application analysis
• Automatic Management: Uses RAII-style C++ objects for automatic scope tracing
• Optional Compilation: Can be completely disabled at compile time via macro definition

Quick Start

1. Copy the tracer.h file to your project

2. Include the header in source files you want to trace:

   #include "tracer/tracer.h"

3. Use the provided macros to trace code execution:

   void some_function() {
     TRACE_SCOPE("some_function");  // Automatically traces function scope
   
     // Function code...
   
     TRACE_INSTANT("interesting_point");  // Records an instant event
   
     // More code...
   }

4. Save trace results at the end of your program:

   TRACE_SAVE("trace_result.json");

5. View results in Chrome browser:

   • Open Chrome
   • Visit chrome://tracing
   • Click "Load" button to load the generated JSON file

API Documentation

Macros

• TRACE_SCOPE(name): Creates a scope event that automatically records entry and exit times
• TRACE_INSTANT(name): Records an instant event
• TRACE_DATA(p_str): Gets collected trace data and saves to the specified string pointer
• TRACE_SAVE(filename): Saves trace data to a file

Disabling Tracing

Define the TRACE_DISABLED macro to disable all tracing code at compile time:

#define TRACE_DISABLED
#include "tracer/tracer.h"

Or add to your compile command:

g++ -DTRACE_DISABLED ...

Examples

Check out the example program in the example directory to see how to use Tracer in a real project:

cd example
make
./tracer_example

The trace_result.json file generated by the example program can be directly opened in Chrome's tracing page.

Performance Considerations

• Tracer uses a ring buffer to store events, with a default capacity of 10,000 events
• When capacity is reached, new events overwrite the oldest ones
• Each event includes name, timestamp, duration, thread ID, process ID, and CPU usage information
• Efficient multi-threading support is implemented via thread-local storage

License

This project is released under the MIT License. See the LICENSE file for details.

Contributing

Feedback and improvements are welcome via Issues and Pull Requests.