Log Management

Last Updated on : 2024-06-25 09:30:54download

TuyaOS allows you to set the logging level and logging destination (such as serial port, file, terminal, and network). On the device management platform, you can get the local logs of devices for troubleshooting.

Local logging is one of the most important features of an IoT gateway. It is used to log information about devices in the field, helping you identify problems. It is recommended to enable this feature for your gateway products.

Log management

Adapt to logging interfaces

TuyaOS provides the TuyaOS Kernel interface tkl_output.h for formatting the log messages. The application implements where to output the logs.

The default output terminal calls tkl_log_output. The application should implement log output in this interface.

For example:

  • Output logs to the terminal:

    VOID_T tkl_log_output(IN CONST CHAR_T *str, ...)
    {
    	printf("%s", str);
    	fflush(stdout);
    	return;
    }
    
  • Output logs to a file:

    VOID_T tkl_log_output(IN CONST CHAR_T *str, ...)
    {
    	uFILE * fp = NULL;
    
    	// Open file
    	fp = ufopen("log.txt", "w+");
    	if(NULL == fp) {
    		return ;
    	}
    
    	// Write to file
    	uiWriteCnt = ufwrite(fp, str, strlen(str));
    	if(uiWriteCnt != strlen(str)) {
    		TAL_PR_ERR("log uf file write data error!");
    		return ;
    	}
    
    	// Close file
    	ufclose(fp);
    
    	return;
    }
    

Set logging level

After TuyaOS is run, call tal_log_set_manage_attr to set a logging threshold. The message is logged only if its logging level is less than or equal to the threshold. The following table lists the logging levels.

Macro definition Description
TAL_LOG_LEVEL_ERR Logs a message with the ERROR level.
TAL_LOG_LEVEL_WARN Logs a message with the WARN level.
TAL_LOG_LEVEL_NOTICE Logs a message with the NOTICE level.
TAL_LOG_LEVEL_INFO Logs a message with the INFO level.
TAL_LOG_LEVEL_DEBUG Logs a message with the DEBUG level.
TAL_LOG_LEVEL_TRACE Logs a message with the TRACE level.

Example:

#include "tal_log.h"

int main(int argc, char **argv)
{
	OPERATE_RET rt = OPRT_OK;

	// Initialize TuyaOS
	TUYA_CALL_ERR_RETURN(tuya_iot_init("./"));

	// Set logging level to DEBUG
	tal_log_set_manage_attr(TAL_LOG_LEVEL_DEBUG);

	// ...

	return 0;
}

Log output macros

TuyaOS provides interfaces to output application logs with different severity levels.

Macro definition Description
PR_DEBUG Outputs DEBUG logs.
PR_DEBUG_RAW Outputs DEBUG logs (RAW data without formatting).
PR_ERR Outputs ERROR logs.
PR_WARN Outputs WARN logs.
PR_INFO Outputs INFO logs.
PR_TRACE Outputs TRACE logs.

Example:

VOID test_log(VOID)
{
	BYTE_T test_buf[8] = {0};

	tal_log_set_manage_attr(TAL_LOG_LEVEL_TRACE);
	PR_TRACE("This is a trace message");

	tal_log_set_manage_attr(TAL_LOG_LEVEL_DEBUG);
	PR_DEBUG("This is a debug message");
	PR_ERR("This is an error message");
	PR_WARN("This is a warning message");
	PR_INFO("This is an info message");

	PR_DEBUG("PR_DEBUG_RAW:");
	for (INT_T i = 0; i < sizeof(test_buf); i++) {
		PR_DEBUG_RAW("%02x ", test_buf[i]);
	}
	PR_DEBUG_RAW("\r\n");

    return;
}

Log upload

Upload logs stored on the device to the Tuya Developer Platform. When anomalies occur on the device, device logs can help you troubleshoot problems.

If your application logs all messages, there will be insufficient storage space on the device as the logs grow.

It is recommended to allocate some persistent storage, such as 2 MB, to store logs. For storage efficiency, log files can be sliced. When the log files exceed the specified value, such as 128 KB or 256 KB, compress and back up them. When the total size of all log files exceeds a threshold, delete the oldest backup to create room for storing new logs.

Log upload can be triggered by the platform or the user.

Platform triggered

Trigger log upload through the Tuya Operations Platform. To trigger log upload, the device must be online. Otherwise, this feature is not available.

tuya_iot_reg_gw_app_cb registers the callback for retrieving logs. In the callback, compress log files and notify TuyaOS of the full path to the compressed file. TuyaOS will upload the file to the Tuya Developer Platform.

Example:

STATIC VOID __gw_log_path_cb(OUT CHAR_T *path, IN CONST INT_T len)
{
    CHAR_T cmd[128] = {0};
    snprintf(cmd, SIZEOF(cmd), "cp -fr /tmp/tuya.log ./log_dir/; tar zcvf /tmp/tuya_log.tgz ./log_dir/*");
    system(cmd);

    strncpy(path, "/tmp/tuya_log.tgz", len);
}

VOID test_get_log_file(VOID)
{
    TY_GW_APP_CBS_S __gw_app_cbs = {
        .gw_log_path_cb = __gw_log_path_cb,
    };
    tuya_iot_reg_gw_app_cb(&__gw_app_cbs);
}

User triggered

Users initiate log upload using the mobile app.

  • When the device is online, the log files will be directly uploaded to the Tuya Developer Platform.
  • When the device is offline but connected to the mobile app over LAN, the log files are sent to the Tuya Developer Platform through the mobile app. This ensures that logs can be uploaded even if there is an issue with the device.

It is recommended to use the user-triggered approach, as it allows for log upload even when the device is offline.

tuya_log_upd_set_cb registers the callback for retrieving logs. In the callback, compress log files and notify TuyaOS of the full path to the compressed file.

tuya_log_upd_set_cb must be called after tuya_iot_init.

Example:

STATIC OPERATE_RET __log_upg_get_name_cb(CHAR_T *log_name, UINT_T max_name_len)
{
    PR_DEBUG("log upd get name");

    CHAR_T cmd[128] = {0};
    snprintf(cmd, SIZEOF(cmd), "cp -fr /tmp/tuya.log ./log_dir/; tar zcvf /tmp/tuya_log.tgz ./log_dir/*");
    system(cmd);

    strncpy(log_name, "/tmp/test_log.tgz", max_name_len);

    return OPRT_OK;
}

STATIC VOID __log_upg_fin_cb(VOID)
{
    PR_DEBUG("log upd finished");
}

int main(int argc, char **argv)
{
    TY_LOG_UPD_CB_S log_upg_cbs = {
        .get_name          = __log_upg_get_name_cb,
        .fin_upd           = __log_upg_fin_cb,
    };

    tuya_iot_init("./");

    tuya_log_upd_set_cb(&log_upg_cbs);

    ...
}

Log upload procedure

Upload logs using the mobile app:

  1. Open the gateway panel and tap the pencil icon in the top right corner.

    Log Management
  2. Tap Check Device Network.

    Log Management
  3. After the check is completed, tap Upload Log.

    Log Management

Log download procedure

Download logs from the Tuya Developer Platform:

  1. Log in to the Tuya Developer Platform. Choose Product > Device > Device Management.

    Log Management
  2. Find the target device by device ID and click Details.

    Log Management
  3. Find Device Local Log File and click Download.

    Log Management