日志记录功能
以下 FreeRTOS 库使用此日志记录功能:
日志记录宏
FreeRTOS 库使用了以下 4 个日志宏,按详细级别排列。 例如,只有在出现错误时才会调用 LogError(),因此是最不详细的,而 LogDebug()
的调用更频繁,以提供调试级别信息,因此是最详细的。
- LogError
- LogWarn
- LogInfo
- LogDebug
日志记录宏在使用时,实参的数量是可变的,就像 printf() 一样(但它们使用双括号)。 例如,库以如下方式调用日志记录宏:
LogInfo( ( “This prints an integer %d”, 100 ) );
您无需单独定义这四个日志记录宏。 通过包含 FreeRTOS-Plus/Source/Utilities/logging/
logging_stack.h 头文件,您可以定义一个名为 SdkLog()
的宏,它将被应用于所有的四个详细级别。 完成此操作后,通过定义 LIBRARY_LOG_LEVEL 单独设置详细级别,如下所述。
注意此页面末尾代码片段中的头文件排序。
定义 SdkLog 宏
应包含 logging_stack.h
头文件,应在使用的库的配置文件中定义日志配置宏。 例如,要从 coreMQTT 库获取日志输出,请包含 logging_stack.h
并在 core_mqtt_config.h
中定义日志记录宏。
若要获取日志记录,必须定义 SkdLog() 以调用线程安全平台特定的打印函数。 例如,打印函数可将字符输出到串行端口或 TCP 套接字。 由于日志记录宏接受的参数数量可变,并且与 printf() 一样使用,平台特定的打印函数必须具有与 printf() 相同的原型(参数列表)。 例如,如果您的应用程序具有对串行端口写入的 printf() 的线程安全版本,则可以将 SdkLog 定义为:
#define SdkLog( X ) printf X
未定义的日志记录宏默认为空宏,不生成任何代码。
注意:如果您不使用 FreeRTOS-Plus/Source/Utilities/logging/ 中的日志记录实用程序标头,则可以通过在您的应用程序中定义宏来为您想要的日志记录级别单独定义四个日志记录宏,但不推荐这种方法,因为这样做会阻止 LIBRARY_LOG_LEVEL 和 LIBRARY_LOG_NAME 产生任何效果。
设置详细级别
若要设置详细级别,在用于定义 SdkLog() 的同一配置文件中,将 LIBRARY_LOG_LEVEL 宏定义为以下值之一: LIBRARY_LOG_LEVEL 的有效值有:
- LOG_NONE (关闭日志记录)
- LOG_ERROR
- LOG_WARN
- LOG_INFO
- LOG_DEBUG
例如:
#define LIBRARY_LOG_LEVEL LOG_NONE
设置文本名称
若要设置文本名称,在用于定义 SdkLog() 的同一配置文件中,将 LIBRARY_LOG_NAME 宏定义为字符串。 每条日志消息都会打印名称,因此,将名称设置为库的名称是正常的。 例如:
#define LIBRARY_LOG_NAME “MQTT”
将名称设置为空字符串将节省程序空间。
设置日志中的元数据
要在日志消息中添加元数据(如日志消息的源代码位置),可以定义 LOG_METADATA_FORMAT 和 LOG_METADATA_ARGS 宏。
LOG_METADATA_FORMAT 宏应被定义为表示元数据格式字符串,而 LOG_METADATA_ARGS 宏应被定义为传递格式字符串的元数据实参。在传递给为 SdkLog 宏定义的平台特定打印函数的日志消息中,这两个宏都有前缀。
例如,以下定义添加了发出日志消息的源文件的函数名称和行号文件。
- #define LOG_METADATA_FORMAT “[%s:%d]”
- #define LOG_METADATA_ARGS __FUNCTION__, __LINE__
将元数据宏设置为空值将节省程序空间。
参考示例
请注意,在下面的示例链接和模板代码中,日志记录宏定义周围有 #ifndef
保护符。这些都是为了避免在包含多个配置文件的转换单元中对相同宏进行多重定义。(例如,MutualAuthMQTTExample.c 包含 demo_config.h
(通过直接包含)和 core_mqtt_config.h (通过间接包含 core_mqtt.h)。对于应用程序代码中的这种情况,重要的是将包含受影响的转换单元文件的日志记录配置的配置文件包含在文件的顶部(即在其他标头包含之前) ,以便应用正确的配置。
有关 FreeRTOS 代码库中用于日志记录配置的示例,请参阅 经由 TLS 相互身份验证的 MQTT 演示,该演示配置了 demo_config.h 文件中的演示应用程序任务(定义见 MutualAuthMQTTExample.c)的日志记录,以及 core_mqtt_config.h 文件中的 coreMQTT 库的日志记录。
以下是使用日志记录配置的模板。
#include "logging_levels.h"
#ifndef LIBRARY_LOG_NAME
LIBRARY_LOG_NAME "MyApplication"
#endif
#if !defined( LOG_METADATA_FORMAT ) && !defined( LOG_METADATA_ARGS )
#define LOG_METADATA_FORMAT "[%s:%d]"
#define LOG_METADATA_ARGS __FILE__, __LINE__
#endif
#ifndef SdkLog
#define SdkLog( message ) MyLogger message
#endif
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.