atobase  3.2.0
ATOMAS atobase
Logging

Overview

The SDK logs appropriate information to support the software if issues arise. As the SDK may be located on non-secure hardware and may be submitted to a help desk for analysis, the log files should contain no sensitive information, such as passwords.

The initialization process will initialise all library modules to a default log level of warning. If overriding log levels, do this after the initialization methods have been called.

Controlling logging output

The SDK code makes various logging calls that can be controlled, separately, by the logging level of individual SDKs (libraries) and their modules. The level of each library/module can be set using:

void ato_setloglevel(const char *library, unsigned short moduleidmask, ato_eLoglevel level);
e.g.
// Set all registered libraries and modules
ato_setloglevel(NULL, 0, ATO_LOG_WARN);
// Turn off logging in crypto library
ATO_EXPORT void ato_setloglevel(const char *library, unsigned long moduleidmask, ato_eLoglevel level)
Set the loglevel for individual registered libraries/modules.
#define ATO_BASE_LIBRARY
The name of the library.
Definition: types.h:104
#define ATO_BASE_MODULEID_CRYPTO
The crypto module id.
Definition: types.h:136
ato_eLoglevel
Loglevels.
Definition: types.h:76
@ ATO_LOG_WARN
Usually a business level error such as wrong password.
Definition: types.h:80
@ ATO_LOG_OFF
Do not log.
Definition: types.h:77

Log function

The default logging function is controlled by some settings in the configuration file. However the entire logging function can be replaced by setting a callback using:

where ato_logfunction is:
typedef bool (ato_logfunction)(ato_Log *log, ato_eLoglevel loglevel, ato_eLogState logstate, const char *library, const char *module, const char *function, const char *format, va_list args);
ATO_EXPORT void ato_log_setlogfn(ato_logfunction logfunction)
Override the default logging function.
ato_eLogState
Controls the state/type of logging - e.g.
Definition: log.h:73
struct _ato_Log ato_Log
The log object.
Definition: log.h:57
bool() ato_logfunction(ato_Log *log, ato_eLoglevel loglevel, ato_eLogState logstate, const char *library, const char *module, const char *function, const char *format, va_list args)
The signature for the logging function - see ato_log_setlogfn()
Definition: log.h:82

For example:

bool customlogger(ato_Log *log, ato_eLoglevel loglevel, ato_eLogState logstate, const char *library, const char *module, const char *function, const char *format, va_list args);
ato_log_setlogfn(customlogger);

Log Levels

The log levels are defined in ato_eLoglevel.

This is a general rational for the logging levels.

Logging LevelIntended AudienceBest Practice
OffDeveloperUseful for targetting logging for individual submodules
Fatal, Error, WarningEnd-UserEvents logged at this level are for messages reported back to an end-user when something has gone wrong. These correspond to the severity codes in @ref atobase_error "error handling"
InformationTesting, Tech SupportUse events logged at this level to debug issues during testing, and to provide technical support to external clients. Log all operations supporting business functionality, including progress and status type information as Information messages
Debug, TraceDeveloperThis is for development use. Log full parameter lists, extra information and, in the case of Trace, method entry/exit
AllDeveloperUseful for targetting logging for individual submodules