Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
:squirrel: Tracey is a lightweight and simple C++ memory leak finder with no dependencies.
C++
Branch: master

README.md

tracey :squirrel:

  • Tracey is a C++ static library that reports memory leaks and provides precise stacktraces with no false positives.
  • Tracey is simple. Just link it.
  • Tracey is easy to integrate. No source modification is required.
  • Tracey is clean. Macroless and callstack based. No new/delete macro hacks.
  • Tracey is lazy. Should work out of the box. Plenty configuration options are provided anyways.
  • Tracey is tiny. One header and one source file.
  • Tracey is handy. Generates HTML logs that can be collapsed per branch in Sublime Text 2 and related editors.
  • Tracey is cross-platform. Builds on Windows/Linux/MacosX. Compiles on g++/clang/msvc.
  • Tracey is stand-alone. OS dependencies only. No third party dependencies.
  • Tracey is zlib/libpng licensed.

cons

  • No hooks for malloc()/free(). Tracey supports new/delete C++ memory operators only (atm).
  • Slower runtime speed than regular builds (but not that much). There is room for improvement though.

sample

// tracey is callstack based. no dirty new/delete macro tricks.
// tracey is a static library. requires no source modification. just link it.

static int *static_cpp_leak = new int;

int main() {
    new int [400];
}

special notes

  • g++ users: both -std=c++0x and -lpthread may be required when compiling tracey.cpp

Possible outputs (msvc/g++/clang)

C:\tracey> rem LINUX: g++ sample.cc tracey.cpp -g -lpthread -std=c++0x
C:\tracey> rem APPLE: clang++ sample.cc tracey.cpp -g -o sample -std=c++11 -stdlib=libc++
C:\tracey> rem WINDOWS following
C:\tracey> cl sample.cc tracey.cpp /Zi
C:\tracey> sample
<tracey/tracey.cpp> says: tracey-0.22.c ready
<tracey/tracey.cpp> says: using realloc (f:\dd\vctools\crt\crtw32\heap\realloc.c, line 62) as realloc
<tracey/tracey.cpp> says: using memset (f:\dd\vctools\crt\crtw32\string\i386\memset.asm, line 61) as memset
<tracey/tracey.cpp> says: using printf (f:\dd\vctools\crt\crtw32\stdio\printf.c, line 49) as printf
<tracey/tracey.cpp> says: using FatalExit as exit
<tracey/tracey.cpp> says: using fopen (f:\dd\vctools\crt\crtw32\stdio\fopen.c, line 124) as fopen
<tracey/tracey.cpp> says: using fclose (f:\dd\vctools\crt\crtw32\stdio\fclose.c, line 43) as fclose
<tracey/tracey.cpp> says: using fprintf (f:\dd\vctools\crt\crtw32\stdio\fprintf.c, line 49) as fprintf
<tracey/tracey.cpp> says: with C++ exceptions=enabled
<tracey/tracey.cpp> says: with kTraceyBudgetOverhead=101.000000%
<tracey/tracey.cpp> says: with kTraceyMaxStacktraces=128 range[0..0]
<tracey/tracey.cpp> says: with kTraceyReportWildPointers=no
<tracey/tracey.cpp> says: with kTraceyDefineMemoryOperators=yes
<tracey/tracey.cpp> says: with kTraceyMemsetAllocations=yes
<tracey/tracey.cpp> says: with kTraceyStacktraceSkipBegin=0
<tracey/tracey.cpp> says: with kTraceyStacktraceSkipEnd=0
<tracey/tracey.cpp> says: with kTraceyReportOnExit=yes
<tracey/tracey.cpp> says: with kTraceyWebserverPort=2001
<tracey/tracey.cpp> says: with kTraceyHookLegacyCRT=0
<tracey/tracey.cpp> says: with kTraceyEnabled=1
<tracey/tracey.cpp> says: summary: highest peak: 1600 bytes total, 1600 bytes greatest peak // -8 allocs in use: 1472 bytes + overhead: 3 GB = total: 948 bytes
<tracey/tracey.cpp> says: creating report: C:\Users\MARIO~1.ROD\AppData\Local\Temp\san4xxx-tracey.html
<tracey/tracey.cpp> says: filtering leaks...
<tracey/tracey.cpp> says: found 2 leaks wasting 1604 bytes
<tracey/tracey.cpp> says: creating trees of frames...
<tracey/tracey.cpp> says: resolving 12 unique frames...
<tracey/tracey.cpp> says: converting tree of frames into tree of symbols...
<tracey/tracey.cpp> says: flattering tree of symbols...
C:\tracey>

and then in C:\Users\MARIO~1.ROD\AppData\Local\Temp\san4xxx-tracey.html log file...

<tracey/tracey.cpp> says: generated with tracey-0.22.c (https://github.com/r-lyeh/tracey)
<tracey/tracey.cpp> says: best viewed on foldable text editor (like SublimeText2) with tabs=2sp and no word-wrap
<tracey/tracey.cpp> says: error, 2 leaks found; 1604 bytes wasted ('lame' score)
<tracey/tracey.cpp> says: summary: highest peak: 1600 bytes total, 1600 bytes greatest peak // -8 allocs in use: 1472 bytes + overhead: 3 GB = total: 948 bytes
<tracey/tracey.cpp> says: report filename: C:\Users\MARIO~1.ROD\AppData\Local\Temp\san4xxx-tracey.html
[2] (100% .. 1604 bytes) begin
  [1] (100% .. 1604 bytes) RtlInitializeExceptionChain
    [1] (100% .. 1604 bytes) RtlInitializeExceptionChain
      [1] (100% .. 1604 bytes) BaseThreadInitThunk
        [2] (099% .. 1600 bytes) __tmainCRTStartup (f:\dd\vctools\crt\crtw32\startup\crt0.c, line 255)
          [1] (099% .. 1600 bytes) main (C:\tracey\sample.cc, line 7)
            [1] (099% .. 1600 bytes) operator new (C:\tracey\tracey.cpp, line 3319)
              [1] (099% .. 1600 bytes) tracey::watch (C:\tracey\tracey.cpp, line 3162)
                [1] (099% .. 1600 bytes) tracey::`anonymous namespace'::tracer (C:\tracey\tracey.cpp, line 3139)
        [2] (000% .. 4 bytes) __tmainCRTStartup (f:\dd\vctools\crt\crtw32\startup\crt0.c, line 237)
          [1] (000% .. 4 bytes) _cinit (f:\dd\vctools\crt\crtw32\startup\crt0dat.c, line 321)
            [1] (000% .. 4 bytes) _initterm (f:\dd\vctools\crt\crtw32\startup\crt0dat.c, line 954)
              [1] (000% .. 4 bytes) `dynamic initializer for 'static_cpp_leak'' (C:\tracey\sample.cc, line 4)
                [1] (000% .. 4 bytes) operator new (C:\tracey\tracey.cpp, line 3319)
                  [1] (000% .. 4 bytes) tracey::watch (C:\tracey\tracey.cpp, line 3162)
                    [1] (000% .. 4 bytes) tracey::`anonymous namespace'::tracer (C:\tracey\tracey.cpp, line 3139)
[2] (100% .. 1604 bytes) end
  [1] (100% .. 1604 bytes) tracey::`anonymous namespace'::tracer (C:\tracey\tracey.cpp, line 3139)
    [1] (100% .. 1604 bytes) tracey::watch (C:\tracey\tracey.cpp, line 3162)
      [1] (100% .. 1604 bytes) operator new (C:\tracey\tracey.cpp, line 3319)
        [2] (099% .. 1600 bytes) main (C:\tracey\sample.cc, line 7)
          [1] (099% .. 1600 bytes) __tmainCRTStartup (f:\dd\vctools\crt\crtw32\startup\crt0.c, line 255)
            [1] (099% .. 1600 bytes) BaseThreadInitThunk
              [1] (099% .. 1600 bytes) RtlInitializeExceptionChain
                [1] (099% .. 1600 bytes) RtlInitializeExceptionChain
        [2] (000% .. 4 bytes) `dynamic initializer for 'static_cpp_leak'' (C:\tracey\sample.cc, line 4)
          [1] (000% .. 4 bytes) _initterm (f:\dd\vctools\crt\crtw32\startup\crt0dat.c, line 954)
            [1] (000% .. 4 bytes) _cinit (f:\dd\vctools\crt\crtw32\startup\crt0dat.c, line 321)
              [1] (000% .. 4 bytes) __tmainCRTStartup (f:\dd\vctools\crt\crtw32\startup\crt0.c, line 237)
                [1] (000% .. 4 bytes) BaseThreadInitThunk
                  [1] (000% .. 4 bytes) RtlInitializeExceptionChain
                    [1] (000% .. 4 bytes) RtlInitializeExceptionChain

API implementation (optional)

Backend implementation in tracey.hpp. Tweak these if needed.

/*/ Default report logger
/*/ #define kTraceyPrintf           std::printf
/*/ Default memory allocator
/*/ #define kTraceyRealloc          std::realloc
/*/ Default memory setter
/*/ #define kTraceyMemset           std::memset
/*/ Default filling character
/*/ #define kTraceyMemsetChar       '\0'
/*/ All fatal exits converge to this symbol
/*/ #define kTraceyDie              $windows(FatalExit) $welse( $cpp11(std::quick_exit) $cpp03(std::exit) )
/*/ All out-of-memory runtime asserts converge to this symbol.
/*/ #define kTraceyAssert           assert
/*/ All out-of-memory runtime exceptions converge to this sysmbol.
/*/ #define kTraceyBadAlloc         std::bad_alloc
/*/ Default wrapper to std::FILE
/*/ #define kTraceyfFile            std::FILE
/*/ Default wrapper to fopen()
/*/ #define kTraceyfOpen            std::fopen
/*/ Default wrapper to fclose()
/*/ #define kTraceyfClose           std::fclose
/*/ Default wrapper to fprintf()
/*/ #define kTraceyfPrintf          std::fprintf

API configuration (optional)

Backend options in tracey.hpp. Tweak these until happy.

/*/ Tracey uses this value to simulate increased memory simulations (should be >= 1.0)
/*/ #define kTraceyBudgetOverhead          1.0
/*/ Tracey retrieves up to 128 traces by default. The longer the slower, though.
/*/ #define kTraceyMaxStacktraces          128
/*/ Tracey head position on every stacktrace. It does not skip backtraces by default.
/*/ #define kTraceyStacktraceSkipBegin     0 // $windows(4) $welse(0)
/*/ Tracey tail position on every stacktrace. It does not skip backtraces by default.
/*/ #define kTraceyStacktraceSkipEnd       0 // $windows(4) $welse(0)
/*/ Tracey linefeed character when logging.
/*/ #define kTraceyCharLinefeed            "\n"
/*/ Tracey tab character when logging.
/*/ #define kTraceyCharTab                 "\t"
/*/ When enabled, Tracey warns about deallocations on pointers that have been not allocated by Tracey (wild pointers)
/*/ #define kTraceyReportWildPointers      0
/*/ When enabled, Tracey warns about double allocations on same pointer
/*/ #define kTraceyReportDoubleAllocations 0
/*/ When enabled, Tracey memsets memory on mallocs()
/*/ #define kTraceyMemsetAllocations       1
/*/ When enabled, Tracey shows a report automatically on application exit.
/*/ #define kTraceyReportOnExit            1
/*/ When enabled, Tracey is enabled
/*/ #define kTraceyEnabled                 1
/*/ When >0, Tracey web service is enabled. Note: requires C++11
/*/ #define kTraceyWebserverPort           2001
/*/ When enabled, Tracey will hook up C CRT as well (@todo)
/*/ #define kTraceyHookLegacyCRT           0
/*/ When >0, Tracey will ignore branches of leaks that are smaller than given percentage. It does not ignore branches by default.
/*/ #define kTraceyTruncateBranchesSmallerThan 0.0 // 5.0%
/*/ When enabled, Tracey implements all new/delete operators; else user must use runtime API manually (see below).
/*/ #define kTraceyDefineMemoryOperators       1

API C++ runtime (optional)

  • tracey::watch(ptr,size) tells Tracey to watch a memory address.
  • tracey::forget(ptr) tells Tracey to forget about a memory address.
  • tracey::clear() tells Tracey to forget whole execution.
  • tracey::report() creates a report and returns its physical address.
  • tracey::view(log) views given report log.
  • tracey::badalloc() throws a bad_alloc() exception, if possible.
  • tracey::fail(msg) shows given error then fail.
  • tracey::nop() does allocate/watch/forget/free some memory.
  • tracey::summary() returns a brief summary.
  • tracey::version() returns current version.
  • tracey::url() returns project repository.
  • tracey::settings() returns current settings.
  • tracey::scope() raii scope monitoring.

API C runtime (optional)

  • tracey_watch(ptr,size) tells Tracey to watch a memory address.
  • tracey_forget(ptr) tells Tracey to forget about a memory address.
  • tracey_clear() tells Tracey to forget whole execution.
  • tracey_report() creates a report and returns its physical address.
  • tracey_view(log) views given report log.
  • tracey_badalloc() throws a bad_alloc() exception, if possible.
  • tracey_fail(msg) shows given error then fail.
  • tracey_nop() does allocate/watch/forget/free some memory.
  • tracey_summary() returns a brief summary.
  • tracey_version() returns current version.
  • tracey_url() returns project repository.
  • tracey_settings() returns current settings.
  • tracey_view_report() make report & view.

API C runtime (optional)

  • @todoc

Changelog

  • 0.24-c
    • Upgraded submodules
  • 0.23-c
    • Webserver support (w/ C++03)
  • 0.22-c
    • Source code clean up.
    • Faster implementation.
    • Better (more) documentation.
    • Safer behavior on any /MT /MTd /MD /MDd combination (MSVC).
    • Deprecated tinythread mutexes in favor of boost (only in C++03).
    • Simplified mutex locking. Requires compiler with thread-local storage support.
    • Amalgamated distribution made of code from different sublibraries: heal, oak, route66
    • Bugfixed wrong branch size on reports.
  • 0.21-b
    • Tracey requires less memory now.
    • Memory usage shown on tree reports now.
  • 0.20-b
    • Tracey behaves better in many aspects now.
    • Support for /MT and /MTd on Windows.
    • iOS support.
    • A more compatible symbol demangling on MacOs/iOS.
    • Faster report generation.
    • New smaller hierarchical tree reports that provide also more information than before.
    • Bugfixed symbol retrieval when other memory managers are present.
    • Improved symbol retrieval on windows.
    • Experimental webserver (to be improved).
    • New compiler tweaks.
    • Many new options and settings (unwinding stack size, truncation, etc...)
    • Bugfixed recursive deadlocks on tinythread.
    • A bunch of other minor bugfixes and tweaks.
    • Tracey throws exceptions only if they are enabled on your compiler now.
    • API upgraded.
    • Many things I have forgotten.
Something went wrong with that request. Please try again.