AWS IoT Device SDK C  202009.00
SDK for connecting to AWS IoT from a device using embedded C.
Logging Infrastructure

This page contains an overview of the logging infrastructure used by the C-SDK Libraries.

The C-SDK libraries utilize one of the following 4 logging macro interfaces, each with a different verbosity level:

  • LogError for Error level
  • LogWarn for Warning level
  • LogInfo for Info level
  • LogDebug for Debug level
By default, each library contains empty definitions for the above logging macros, thereby generating no code for logging calls.

To enable logging within the libraries, your application should implement these macros through the library-specific config file (for example, the core_mqtt_config.h file for MQTT library). The implementation of these macros can be provided as a mapping to the your platform-specific logging framework.

Design Architecture

The logging infrastructure architecture follows a dependency inversion design principle of allowing your application to inject an implementation of logging interface macros through the library-specific config file (like core_mqtt_config.h).

Reference Implementation

For reference example of a POSIX-specific logging implementation, refer to the demos/logging-stack folder from the root directory of the C-SDK repository.

The logging_stack.h file contains the definition of all the logging interface macros (LogError, LogWarn, LogInfo, LogDebug) that eventually map to the standard C function, printf.

The file contains the following features:

  • Ability to define logging verbosity level for a library through the LIBRARY_LOG_LEVEL macro. (All the logging levels are defined in logging_levels.h). This allows logging macros to be conditionally enabled depending on the configured logging level. For example, for the LOG_INFO verbosity configuration, only the LogError, LogWarn, LogInfo macros are enabled but the LogDebug macro is disabled.
  • With the above ability, the compiler does not generate code for library logging calls to disabled logging macros. For example, a LOG_ERROR verbosity configuration does not generate code for logging calls for the LogWarn, LogInfo, or LogDebug macros, ONLY for LogError macro.
  • Ability to set the library name as metadata in library logs through the LIBRARY_LOG_NAME macro.
  • Ability to add metadata as a prefix in log messages through the LOG_METADATA_ARGS and LOG_METADATA_FORMAT macros. By default, it adds the metadata of the format:[<Logging-Level>] [<Library-Name>] [<File-Name>:<Line-Number>]. Here is an example snippet of log messages from the MQTT Basic TLS demo:
    [INFO] [MQTT] [core_mqtt.c:854] Packet received. ReceivedBytes=2.
    [INFO] [MQTT] [core_mqtt_serializer.c:969] CONNACK session present bit not set.
    [INFO] [MQTT] [core_mqtt_serializer.c:911] Connection accepted.
    [INFO] [MQTT] [core_mqtt.c:1525] Received MQTT CONNACK successfully from broker.
    [INFO] [MQTT] [core_mqtt.c:1791] MQTT connection established with the broker.

For an example of how the demo projects utilize the logging stack, refer to any core_mqtt_config.h file in the MQTT demos folder of the C-SDK repository.