Logging – Basic

Step-by-step guide to adding basic logging to your application

Step 1 – Optionally, define logging category

Category must a valid preprocessor token, more specifically a valid identifier i.e. a regular expression [_a-zA-Z][_a-zA-Z0-9]*. If not defined, then the default category is GENERIC.

#define PETR_SCRIBO_CATEGORY EXAMPLE // Define category, default is GENERIC.

Step 2 – Include logging header petr/Scribo.h

The header must be included after (not before) any category definition.

#include "petr/Scribo.h" // Include header (after optional category definition).

Step 3 – Create logging messages

Logging command SCRIBE has a number of build-time configuration settings and run-time output parameters. Few common uses are shown below.

(a) Logging entry to each function/method being executed

Systematic logging of all entry points can provide a valuable call trace (at the expense of increased code size and slower execution).

void LogFunctionEntry()
{
    SCRIBE(METHOD); // SCRIBE(METHOD, "%s", __func__)
    // ...
}

The above code will generate output similar to the following.

2019-09-02 17:29:38 #0000000000 EXAMPLE METHOD  : LogFunctionEntry

(b) Tracing execution flow throughout source code

Compact logging statements can easily be added in an ad hoc fashion to gain understanding of code branching and execution path.

void TraceExecutionFlow()
{
    // ...
    SCRIBE(); // SCRIBE(TRACE, "\"%s\" : %d", __FILE__, __LINE__)
    // ...
}

The above code will generate output similar to the following.

2019-09-02 17:29:38 #0000000001 EXAMPLE TRACE   : "test/test_Scribo_CodeSnippet.cpp" : 35

(c) Outputting any debugging data in printf-like style

Both fixed text messages and on-the-fly computed expressions can be output to aid development.

void OutputDebugging()
{
    // ...
    SCRIBE(DEBUG, "PI is circa %f", 22.0/7.0);
    // ...
}

The above code will generate output similar to the following.

2019-09-02 17:29:38 #0000000002 EXAMPLE DEBUG   : PI is circa 3.142857

Step 4 – Build and execute your application

Add PETR to your application build flow – either add its source files during compilation or link a separately-build PETR library. Execute your application. By default, logging will be output to console (stdout).

Complete example

#define PETR_SCRIBO_CATEGORY EXAMPLE // Define category, default is GENERIC.
#include "petr/Scribo.h" // Include header (after optional category definition).

void LogFunctionEntry()
{
    SCRIBE(METHOD); // SCRIBE(METHOD, "%s", __func__)
    // ...
}

void TraceExecutionFlow()
{
    // ...
    SCRIBE(); // SCRIBE(TRACE, "\"%s\" : %d", __FILE__, __LINE__)
    // ...
}

void OutputDebugging()
{
    // ...
    SCRIBE(DEBUG, "PI is circa %f", 22.0/7.0);
    // ...
}

The above code will generate output similar to the following.

2019-09-02 17:29:38 #0000000000 EXAMPLE METHOD  : LogFunctionEntry
2019-09-02 17:29:38 #0000000001 EXAMPLE TRACE   : "test/test_Scribo_CodeSnippet.cpp" : 35
2019-09-02 17:29:38 #0000000002 EXAMPLE DEBUG   : PI is circa 3.142857