Device log reporting - IoT Platform - Alibaba Cloud Documentation Center

IoT Platform allows devices to report on-premises logs to the cloud. You can query device logs and troubleshoot issues in the console.

Note

Devices that use the following Link SDKs can report on-premises logs to IoT Platform. You can develop your own SDK that enables the feature of reporting on-premises logs.
- Link SDK for Android
- Link SDK for C: Log Reporting
To report logs of a device, you must go to the Device Details page of the device and turn on the Device local log reporting switch.

For more information about how to query on-premises device logs, see Local device logs.

Devices request log configurations from IoT Platform

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

Request topic: /sys/${productKey}/${deviceName}/thing/config/log/get
Response topic: /sys/${productKey}/${deviceName}/thing/config/log/get_reply

Sample request in the Alink JSON format:

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
    },
    "params" : {
        "configScope":"device",  
        "getType":"content"
     },
    "method":"thing.config.log.get"
}

Table 1. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version of the protocol. Valid value: `1.0`.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values: 1: IoT Platform needs to return response data. 0: IoT Platform does not need to return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
configScope	String	The scope of log configurations. IoT Platform supports only device-level log configurations. Default value: `device`.
getType	String	The format in which the configurations are returned. Default value: `content`. By default, the content of log configurations is small in size and is directly returned in the text format.
method	String	The request method. Valid value: `thing.config.log.get`.

Sample response in the Alink JSON format:

{
    "id":"123",
    "version":"1.0",
    "code":200,
    "data" :{ 
        "getType":"content",
        "content":{
            "mode":0 
        }
    }
}

Table 2. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version of the protocol. Valid value: `1.0`.
code	Integer	The HTTP status code in the response. If 200 is returned, the request was successful. If other status codes are returned, the request failed. For more information about the HTTP status codes `6717` and `6718`, see the following table. For more information about other HTTP status codes, see Common codes on devices.
data	Object	The data that is returned by IoT Platform.
getType	String	The format in which the configurations are returned. Default value: `content`. By default, the content of log configurations is small in size and is directly returned in the text format.
content	String	The content of log configurations in the text format.
mode	Integer	The mode that is used to report device logs. A value of 0 indicates that the device SDK is not used to report logs. A value of 1 indicates that the device SDK is used to report logs.

Table 3. Error codes
HTTP status code	Cause	Troubleshooting
6717	The getType request parameter is invalid. To report device logs, you must set this parameter to `content`.	Log on to the IoT Platform console. In the left-side navigation pane, choose Maintenance > Device Log. On the Device local log tab, check the value of the getType parameter. Alternatively, check the parameter value in on-premises device logs.
6718	The configScope request parameters is invalid. To report device logs, you must set this parameter to `device`.	Log on to the IoT Platform console. In the left-side navigation pane, choose Maintenance > Device Log. On the Device local log tab, check the value of the configScope parameter. Alternatively, check the parameter value in on-premises device logs.

Devices receive log configurations from IoT Platform

The following topic is used when IoT Platform sends requests to a device and the device sends responses to IoT Platform:

Topic: /sys/${productKey}/${deviceName}/thing/config/log/push.

Configuration data that is sent in the Alink JSON format:

{
    "id":"123",
    "version":"1.0",
    "params" :{ 
        "getType":"content",
        "content":{
            "mode":0
        }
    }
}

Table 4. Parameter descriptions
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version of the protocol. Valid value: `1.0`.
getType	String	The format in which the configurations are returned. Default value: `content`. By default, the content of log configurations is small in size and is directly returned in the text format.
content	String	The content of log configurations in the text format.
mode	Integer	The mode that is used to report device logs. A value of 0 indicates that the device SDK is not used to report logs. A value of 1 indicates that the device SDK is used to report logs.

Devices report logs

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

Request topic: /sys/${productKey}/${deviceName}/thing/log/post
Response topic: /sys/${productKey}/${deviceName}/thing/log/post_reply

Sample request in the Alink JSON format:

{
    "id" : "123",
    "version":"1.0",
    "sys":{
      "ack":0
    },
    "params" :[{
          "utcTime":  "2020-03-06T15:15:27.464+0800",  
          "logLevel": "ERROR",          
          "module": "ModuleA",         
          "code" :"4103",                       
          "traceContext": "123456",    
          "logContent" : "some log content" 
         }], 
    "method" : "thing.log.post"
}

Table 5. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version of the protocol. Valid value: `1.0`.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values: 1: IoT Platform needs to return response data. 0: IoT Platform does not need to return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
params	List	The request parameters. The params parameter can contain up to 40 elements in an array.
utcTime	String	The time when the device collects the log. The time is in UTC and includes the time zone. Unit: milliseconds. Data format: yyyy-MM-dd'T'HH:mm:ss.SSSZ. You can use other data formats. However, we recommend that you use this data format to facilitate troubleshooting.
logLevel	String	The log level. You can use a default log level or customize a log level. The following default log levels are listed by severity from high to low: FATAL ERROR WARN INFO DEBUG
module	String	The name of the module. If the device uses the SDK for Android, the module name is ALK-LK. If the device uses the SDK for C, customize a module name. If the device uses the SDK that is developed by you, customize a module name.
code	String	The HTTP status code in the response. The HTTP status code may be generated by the device SDK or customized by the user. For more information about the status codes that may be returned if the device uses the SDK for Android, see Error codes. For more information about the status codes that may be returned if the device uses the SDK for C, see Common error codes.
traceContext	String	Optional. The content to be traced in the context. For devices, set this parameter to the value of the id parameter in Alink messages. For applications, set this parameter to the value of the TraceId parameter.
logContent	String	The content of the log.
method	String	The request method. Valid value: `thing.log.post`.

Sample response in the Alink JSON format:

{
    "id" : "123",
    "code":200,
    "data" : {}
}

Table 6. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The HTTP status code in the response. If 200 is returned, the request was successful. If other status codes are returned, the request failed. For more information, see Common codes on devices.
data	Object	The data that is returned by IoT Platform. In the response to a request to report logs, no data is returned.