The trace module is important for analyzing problems.

It can be disabled at compile time to strip out all trace strings in situation where not enough RAM/ROM is available, but this is not recommended.

At runtime you can configure the trace information by setting the trace level and trace facility. By default the level TRACE_LEVEL_ERROR should always be enabled. For debugging you can enable more trace levels. The trace facility can be used to filter the trace output for a certain software module, e.g. TRACE_FAC_MEMORY. By default the facility filter should be disabled by using TRACE_FAC_ALL. The application can configure this by calling trace_openlog.

Note that both trace facility and trace level are bitmasks. This allows better control for filtering the trace output than simple <,> comparisons.

Trace Configuration

The trace module supports different trace backends which can be also extended by custom trace backends. The following sections describe the different available trace backends which are provided by the SDK.

The trace module and the backend to use can be selected by using CMake.

CMake Option	Default Value	Description
TRACE_ENABLED	ON	Enabled or disable the trace module.
TRACE_BACKEND	stderr	Backend selection: stderr, file, or syslog.

To add your own custom trace backends to the drop-down box of the CMake GUI you need to edit the file src/trace/CMakeLists.txt and add your backend name to the semicolon separated list of variable TRACE_BACKENDS. This name must be identical with the backend folder name inside src/trace.

STDERR Backend

This is a generic C implementation which uses fprintf and vfprintf to print nicely formatted trace information with timestamps to console (stderr). On Linux it also supports colored output which is nice to read. If you don't like color output you can disable it by setting the CMake option ENABLE_COLOR to OFF.

On embedded systems putc() can also be redirected to UART, so that all printf calls can be sent to a terminal application on a PC.

If this is not possible you can create you own trace backend.

File Backend

This is a very simple implementation which writes all traces into a file. It can create filename like e.g. "log.<pid>.<num>.txt", where pid is the current process id and num is a number that gets incremented when a new file is created. This module will create a new file when it reaches the configured maximum number of lines (max_lines). It also implements a trivial log file rotation, which means old files will be deleted automatically when max_files number of files was reached.

The file trace can be configured by creating a file "trace.conf" which is read from the current working directory. If this file is missing hard coded defaults will be used. See the example provided with the SDK in the "bin" folder.

Settings	Default Value	Description
directory	"."	The directory where the trace files should be created.
basename	"log"	The trace file basename. The default will create files name like e.g. "log.1234.1.txt".
extension	".txt"	File extension to use.
include_pid	false	Includes the PID into the filename. This is useful for multi-process configurations, but makes not much sense for single process.
max_files	5	The maximum number of trace files to keep.
max_lines	100000	The maximum number of lines per file.
force_flush	false	Force a fflush after every printed line. This can avoid data loss in case of crash, but is way slower than the normal trace.
append	false	Appends to an existing file instead of overwriting it.

Syslog Backend

This module is designed for Linux. It uses the syslog API to write all traces into the system log files, which is the expected behaviour of Linux system administrators.

See https://linux.die.net/man/3/syslog for more information.

Reducing Codesize

Traces can enlarge the codesize of your server enormously. One solution to reduce the code size is to disable the trace completely using the CMake option TRACE_ENABLED.

But normally you want at least error and warnings messages in the binary, but you can remove all debug level and info traces. To achieve this you can edit src/trace/trace.h file and make the according trace macros (TRACE_DEBUG, TRACE_INFO, etc.) empty defines. This way these trace levels get stripped from the binary without disabling the trace functionality.

This can also improve performance, because the function call to trace_log() and the according trace-filter code is not executed.