Macro-based debug trace system with optional SD file logging. More...

#include <cstdio>
#include <cstdarg>
#include <ctime>
#include <string>
#include <cstring>
#include "framework_config.h"
#include "storage/StorageManager.h"
#include "framework/AppContext.h"
#include "time/TimeManager.h"

Include dependency graph for DebugTrace.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	TRACE_LVL_INFO 0

#define	TRACE_LVL_WARN 1

#define	TRACE_LVL_ERROR 2

#define	TRACE_INCLUDE_TIMESTAMP 1

#define	TRACE_INIT(MODULE_NAME)
	Declare trace usage in a source file for a given module.

#define	TRACEF(level, ...)
	Core trace macro with level support.

#define	TRACE(...) TRACEF(TRACE_LVL_INFO, __VA_ARGS__)
	Default trace (INFO level).

#define	TRACE_WARN(...) TRACEF(TRACE_LVL_WARN, __VA_ARGS__)
	WARN level trace.

#define	TRACE_ERROR(...) TRACEF(TRACE_LVL_ERROR, __VA_ARGS__)
	ERROR level trace.

Enumerations
enum	TraceTimeFormat { TRACE_TIME_UTC , TRACE_TIME_LOCAL }

Functions
void	setTraceOutputToFile (StorageManager *sm, const std::string &path)
	Set trace output to SD file using FatFsStorageManager.

const char *	traceLevelToString (int level)
	Convert trace level to string.

void	shortenFilePath (const char fullPath, char buffer, size_t maxLen)
	Strip file path to filename only.

std::string	getFormattedTimestamp ()
	Internal trace log handler.

void	traceLog (const char module, int level, const char file, int line, const char func, const char format,...)
	Internal trace log function.

Variables
static std::string	tracePath

static bool	traceToFile = false

static TraceTimeFormat	traceTimeFormat = TRACE_TIME_LOCAL

Detailed Description

Author: Ian Archbell

Part of the PicoFramework application framework. Provides compile-time enabled, level-filtered trace logging for embedded applications. Features:

Per-module control (TRACE_<MODULE> in framework_config.h)
Level filtering (TRACE_LEVEL_MIN)
Optional timestamp
Optional SD file redirection via FatFsStorageManager

Controlled via framework_config.h. SD output is enabled if TRACE_USE_SD is set to 1.

Version: 0.3

Date: 2025-03-31

License:\n MIT License

Copyright: Copyright (c) 2025, Ian Archbell

Definition in file DebugTrace.h.

Macro Definition Documentation

◆ TRACE

#define TRACE ( ... ) TRACEF(TRACE_LVL_INFO, __VA_ARGS__)

Definition at line 187 of file DebugTrace.h.

◆ TRACE_ERROR

#define TRACE_ERROR ( ... ) TRACEF(TRACE_LVL_ERROR, __VA_ARGS__)

Definition at line 197 of file DebugTrace.h.

◆ TRACE_INCLUDE_TIMESTAMP

#define TRACE_INCLUDE_TIMESTAMP 1

Definition at line 39 of file DebugTrace.h.

◆ TRACE_INIT

#define TRACE_INIT ( MODULE_NAME )

Value:

static constexpr const char *TRACE_MODULE = #MODULE_NAME; \

static constexpr int TRACE_ENABLED = TRACE_##MODULE_NAME;

Definition at line 170 of file DebugTrace.h.

    {                                                                                 \
        if (TRACE_ENABLED && (level) >= TRACE_LEVEL_MIN)                              \
            traceLog(TRACE_MODULE, level, __FILE__, __LINE__, __func__, __VA_ARGS__); \
    } while (0)
 
#define TRACE(...) TRACEF(TRACE_LVL_INFO, __VA_ARGS__)
 
#define TRACE_WARN(...) TRACEF(TRACE_LVL_WARN, __VA_ARGS__)
 
#define TRACE_ERROR(...) TRACEF(TRACE_LVL_ERROR, __VA_ARGS__)

◆ TRACE_LVL_ERROR

#define TRACE_LVL_ERROR 2

Definition at line 36 of file DebugTrace.h.

◆ TRACE_LVL_INFO

#define TRACE_LVL_INFO 0

Definition at line 34 of file DebugTrace.h.

◆ TRACE_LVL_WARN

#define TRACE_LVL_WARN 1

Definition at line 35 of file DebugTrace.h.

◆ TRACE_WARN

#define TRACE_WARN ( ... ) TRACEF(TRACE_LVL_WARN, __VA_ARGS__)

Definition at line 192 of file DebugTrace.h.

◆ TRACEF

#define TRACEF	(	level,
		...
	)

Value:

    do                                                                                \
    {                                                                                 \
        if (TRACE_ENABLED && (level) >= TRACE_LEVEL_MIN)                              \
            traceLog(TRACE_MODULE, level, __FILE__, __LINE__, __func__, __VA_ARGS__); \
    } while (0)

Definition at line 177 of file DebugTrace.h.

    {                                                                                 \
        if (TRACE_ENABLED && (level) >= TRACE_LEVEL_MIN)                              \
            traceLog(TRACE_MODULE, level, __FILE__, __LINE__, __func__, __VA_ARGS__); \
    } while (0)

Enumeration Type Documentation

◆ TraceTimeFormat

enum TraceTimeFormat

Enumerator
TRACE_TIME_UTC
TRACE_TIME_LOCAL

Definition at line 84 of file DebugTrace.h.

{
    TRACE_TIME_UTC,
    TRACE_TIME_LOCAL
};

Function Documentation

◆ getFormattedTimestamp()

std::string getFormattedTimestamp ( )

inline

Formats and dispatches output.

Definition at line 95 of file DebugTrace.h.

{
    static bool timeAvailable = false;
    static const TimeManager *tm = nullptr;
 
    if (!timeAvailable)
    {
        tm = AppContext::getInstance().getService<TimeManager>();
        timeAvailable = tm != nullptr;
    }
 
    if (tm)
    {
        std::string formatted = tm->currentTimeForTrace();
        return tm->currentTimeForTrace();
    }
    else
    {
 
        return std::string("");
    }
}

References TimeManager::currentTimeForTrace(), AppContext::getInstance(), and AppContext::getService().

Referenced by traceLog().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setTraceOutputToFile()

void setTraceOutputToFile	(	StorageManager *	sm,
		const std::string &	path
	)

inline

Parameters

sm	Storage manager (or nullptr for console only)
path	File path (e.g. "/log/trace.txt")

Definition at line 51 of file DebugTrace.h.

{
    tracePath = path;
    traceToFile = (sm != nullptr && !path.empty());
}

References tracePath, and traceToFile.

Referenced by FrameworkManager::setupTraceFromConfig().

Here is the caller graph for this function:

◆ shortenFilePath()

void shortenFilePath	(	const char *	fullPath,
		char *	buffer,
		size_t	maxLen
	)

inline

Definition at line 78 of file DebugTrace.h.

{
    const char *slash = strrchr(fullPath, '/');
    snprintf(buffer, maxLen, "%s", slash ? slash + 1 : fullPath);
}

Referenced by traceLog().

Here is the caller graph for this function:

◆ traceLevelToString()

const char * traceLevelToString ( int level )

inline

Definition at line 60 of file DebugTrace.h.

{
    switch (level)
    {
    case TRACE_LVL_INFO:
        return "INFO";
    case TRACE_LVL_WARN:
        return "WARN";
    case TRACE_LVL_ERROR:
        return "ERROR";
    default:
        return "???";
    }
}

References TRACE_LVL_ERROR, TRACE_LVL_INFO, and TRACE_LVL_WARN.

Referenced by traceLog().

Here is the caller graph for this function:

◆ traceLog()

void traceLog	(	const char *	module,
		int	level,
		const char *	file,
		int	line,
		const char *	func,
		const char *	format,
			...
	)

inline

Parameters

module	Module name (e.g. "Network")
level	Trace level (TRACE_LVL_INFO, TRACE_LVL_WARN, TRACE_LVL_ERROR)
file	Source file name
line	Source line number
func	Function name
format	Format string for the message

Definition at line 127 of file DebugTrace.h.

{
    if (level < TRACE_LEVEL_MIN)
        return;
 
    char fileBuf[64];
    shortenFilePath(file, fileBuf, sizeof(fileBuf));
 
    char msgBuf[256];
    va_list args;
    va_start(args, format);
    vsnprintf(msgBuf, sizeof(msgBuf), format, args);
    va_end(args);
    std::string formatted;
    std::string timestamp = "";
 
#if TRACE_INCLUDE_TIMESTAMP
    timestamp = getFormattedTimestamp();
 
    formatted = timestamp + "[" + traceLevelToString(level) + "] [" +
                module + "] " + fileBuf + ":" + std::to_string(line) +
                " (" + func + "): " + msgBuf + "\n";
 
#endif
    if (traceToFile)
    {
        auto *storage = AppContext::getInstance().getService<StorageManager>();
        if (storage)
        {
            storage->appendToFile(tracePath, reinterpret_cast<const uint8_t *>(formatted.c_str()), formatted.length());
        }
    }
    else
    {
 
        fputs(formatted.c_str(), stdout);
        fflush(stdout);
    }
}

References StorageManager::appendToFile(), getFormattedTimestamp(), AppContext::getInstance(), AppContext::getService(), shortenFilePath(), TRACE_LEVEL_MIN, traceLevelToString(), tracePath, and traceToFile.

Here is the call graph for this function:

Variable Documentation

◆ tracePath

std::string tracePath

inlinestatic

Definition at line 43 of file DebugTrace.h.

Referenced by setTraceOutputToFile(), and traceLog().

◆ traceTimeFormat

TraceTimeFormat traceTimeFormat = TRACE_TIME_LOCAL

static

Definition at line 89 of file DebugTrace.h.

◆ traceToFile

bool traceToFile = false

inlinestatic

Definition at line 44 of file DebugTrace.h.

Referenced by setTraceOutputToFile(), and traceLog().

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ TRACE

◆ TRACE_ERROR

◆ TRACE_INCLUDE_TIMESTAMP

◆ TRACE_INIT

◆ TRACE_LVL_ERROR

◆ TRACE_LVL_INFO

◆ TRACE_LVL_WARN

◆ TRACE_WARN

◆ TRACEF

Enumeration Type Documentation

◆ TraceTimeFormat

Function Documentation

◆ getFormattedTimestamp()

◆ setTraceOutputToFile()

◆ shortenFilePath()

◆ traceLevelToString()

◆ traceLog()

Variable Documentation

◆ tracePath

◆ traceTimeFormat

◆ traceToFile