Tracer

Tracer is a simple C++ class that allows to create a trace file and write debugging information into it.

When I wrote Tracer, the most important goal was to have indenting: the output of a called function should be more indented than the output of the calling function. This is demonstrated with this small demo.

There's a set of macros that should be used when Tracer is utilised. Their behaviour is controled by setting (or unsetting) DO_TRACE. No tracefile is written if it is undefined while the trace file is written when it is defined.

Here's the code:

Tracer.h

/*
   Tracer.h

   Copyright (C) 2002-2004 René Nyffenegger

   This source code is provided 'as-is', without any express or implied
   warranty. In no event will the author be held liable for any damages
   arising from the use of this software.

   Permission is granted to anyone to use this software for any purpose,
   including commercial applications, and to alter it and redistribute it
   freely, subject to the following restrictions:

   1. The origin of this source code must not be misrepresented; you must not
      claim that you wrote the original source code. If you use this source code
      in a product, an acknowledgment in the product documentation would be
      appreciated but is not required.

   2. Altered source versions must be plainly marked as such, and must not be
      misrepresented as being the original source code.

   3. This notice may not be removed or altered from any source distribution.

   The most current version of Tracer.h can be found at
   http://www.adp-gmbh.ch/cpp/common/Tracer.html

   René Nyffenegger rene.nyffenegger@adp-gmbh.ch
*/

#ifndef TRACER_H__
#define TRACER_H__

#ifdef DO_TRACE 

#include <string>
#include <sstream>

#include <windows.h>

#define StartTrace(x)    TraceFunc_::StartTrace_(x)
#define Trace(x)         dummy_____for_trace_func______.Trace_(x)
#define Trace2(x,y)      dummy_____for_trace_func______.Trace_(x,y)
#define TraceFunc(x)     TraceFunc_ dummy_____for_trace_func______(x)
#define TraceFunc2(x,y)  TraceFunc_ dummy_____for_trace_func______(x,y)

class TraceFunc_ {
  std::string func_name_;
  public:
    /*
      Calling TraceFunc_ indents the output until the enclosing scope ( {...} )
      is left.
    */
    TraceFunc_(std::string const&);
    TraceFunc_(std::string const&, std::string const& something);
   ~TraceFunc_();

   /*
      Creates the trace output file named by filename.
      Must be called before any other tracing function.
      Use the StartTrace macro for it.
   */
   static void StartTrace_(std::string const& filename);

   template <class T>
   void Trace_(T const& t) {
     DWORD d;
     std::string indent_s;
     std::stringstream s;

     s << t;
  
     for (int i=0; i< indent; i++) indent_s += " ";
  
     ::WriteFile(trace_file_,indent_s.c_str(), indent_s.size(), &d, 0);
     ::WriteFile(trace_file_, s.str().c_str(), s.str().size() ,&d, 0);
     ::WriteFile(trace_file_,"\x0a",1,&d,0);
   }

   template <class T, class U>
   void Trace_(T const& t, U const& u) {
     std::string indent_s;
     std::stringstream s;

     s << t;
     s << u;
     Trace_(s.str());
   }

   static int indent;
   /*  trace_file_ is a HANDLE for the file in which the traced output goes.
       The file is opened (that is, created) by calling StartTrace_.
       Better yet, use the StartTrace macro
       to create the file.
   */
   static HANDLE trace_file_;
};

#else

#define StartTrace(x)
#define Trace(x)
#define Trace2(x,y)
#define TraceFunc(x)
#define TraceFunc2(x,y)

#endif

#endif  // TRACER_H__

Tracer.cpp

/*
   Tracer.cpp

   Copyright (C) 2002-2004 RenT Nyffenegger

   This source code is provided 'as-is', without any express or implied
   warranty. In no event will the author be held liable for any damages
   arising from the use of this software.

   Permission is granted to anyone to use this software for any purpose,
   including commercial applications, and to alter it and redistribute it
   freely, subject to the following restrictions:

   1. The origin of this source code must not be misrepresented; you must not
      claim that you wrote the original source code. If you use this source code
      in a product, an acknowledgment in the product documentation would be
      appreciated but is not required.

   2. Altered source versions must be plainly marked as such, and must not be
      misrepresented as being the original source code.

   3. This notice may not be removed or altered from any source distribution.

   The most current version of Tracer.cpp can be found at
   http://www.adp-gmbh.ch/cpp/common/Tracer.html

   René Nyffenegger rene.nyffenegger@adp-gmbh.ch
*/

#include "Tracer.h"

#ifdef DO_TRACE

#include <windows.h>

HANDLE TraceFunc_::trace_file_=0;

int TraceFunc_::indent = -1;

void TraceFunc_::StartTrace_(std::string const& filename) {
  trace_file_ = ::CreateFile(filename.c_str(), GENERIC_WRITE, FILE_SHARE_READ, 0, CREATE_ALWAYS, 0, 0);
}

TraceFunc_::TraceFunc_(std::string const& func_name) {
  func_name_ = func_name;

  indent++;
  Trace_( (std::string("Entered ") + func_name));
  indent++;
}

TraceFunc_::TraceFunc_(std::string const& func_name, std::string const& something) {
  func_name_ = func_name;

  indent++;
  Trace_( (std::string("Entered ") + func_name + " [" + something + "]"));
  indent++;
}

TraceFunc_::~TraceFunc_() {
  indent--;
  Trace_    (std::string("Leaving ") + func_name_);
  indent--;
}

#endif

Demonstration

The following simple program demonstrates how Tracer can be used to trace the execution flow of a programm.

The macro Trace simply writes the passed argument into the trace file. Similarly, Trace2 takes two arguments and writes its concatenation into the trace file.

The macro TraceFunc indents the output in the tracefile. The indentation lasts until the enclosing block ( {....} ) is left.

The macros StartTrace creates the output file and names it according to the passed argument.

TestTracer.cpp

#include <windows.h>

/*
  g++ -DDO_TRACE -mwindows -Wall Tracer.cpp TestTracer.cpp -oTestTracer.exe
*/

#include "Tracer.h"

void aaa(int);
void bbb(int);

void ccc(int i) {
  TraceFunc("ccc");
  Trace2("i: ", i);
  if (i > 8) {
    Trace2("going to call aaa with ", i/2);
    aaa(i/2);
  }
  else {
    Trace("going to call bbb with 6");
    bbb(6);
  }
}

void bbb(int i) {
  TraceFunc("bbb");
  Trace2("i: ", i);
  if (i > 10) {
    ccc(i/3);
  }
  else {
    aaa(i/2);
  }
  ccc(10);
}

void aaa(int i) {
  TraceFunc("aaa");
  Trace2("i: ", i);
  if (i > 5) {
    Trace("i > 5, going to call bbb");
    bbb(i/2);
  }
  else {
    Trace("i <= 5, not going to call bbb");
  }
}

int main() {
  StartTrace("Trace.out");
  TraceFunc("main");
  aaa(50);
  return 0;
}

If this programm is compiled with having DO_TRACE #defined, it creates a file named trace.out and writes the following content:

Entered main
  Entered aaa
   i: 50
   i > 5, going to call bbb
    Entered bbb
     i: 25
      Entered ccc
       i: 8
       going to call bbb with 6
        Entered bbb
         i: 6
          Entered aaa
           i: 3
           i <= 5, not going to call bbb
          Leaving aaa
          Entered ccc
           i: 10
           going to call aaa with 5
            Entered aaa
             i: 5
             i <= 5, not going to call bbb
            Leaving aaa
          Leaving ccc
        Leaving bbb
      Leaving ccc
      Entered ccc
       i: 10
       going to call aaa with 5
        Entered aaa
         i: 5
         i <= 5, not going to call bbb
        Leaving aaa
      Leaving ccc
    Leaving bbb
  Leaving aaa
Leaving main

Links

Log4cpp is library of C++ classes for flexible logging to files, syslog, IDSA and other destinations.


	René Nyffenegger's collection of things on the web
	René Nyffenegger on Oracle - Most wanted - Feedback - Follow @renenyffenegger