Manage diagnostic logs

The Knox Asset Intelligence APIs provide functionalities to manage the diagnostic logs of devices. This tutorial focuses on the diagnosticsLogs endpoint, it supports two use cases — generation of diagnostic logs and retrieval of these diagnostic logs.

The generation of diagnostic logs leads to an event upload by Knox Asset Intelligence. You can receive notifications for this event, if you subscribed to it in Knox Webhook Notification.

Ensure that you have the necessary permissions to set or update the Knox Asset Intelligence settings and obtain an authentication token. For more information, see Get started.

Generate diagnostic logs

1. To request generation of diagnostic logs, make a POST request to the /diagnosticsLogs endpoint.

2. In the request body, you can make use of the following parameters:

   • deviceIds — List of the device IMEIs or serial numbers for which to generate logs, this is a required parameter.
   • silentMode — Specifies whether to retrieve logs with or without user consent, this is applicable only on fully managed devices. You can retrieve logs without the user consent by setting this parameter to true.
   • category — Category of diagnostic logs you want to generate. If set to TCPDUMPLOG, generates only TCPdump logs. Default value is ALL, which generates a comprehensive set of logs.

For example, the following request body generates the diagnostic logs for devices for which IMEIs are listed in deviceIds. This request sample doesn’t seek consent from the user and generates only TCPdump logs.

{
  "deviceIds": [
      123456789123456,123123123123123 
    ],
  "silentMode": [
      "true" 
    ],
  "category": [
      "TCPDUMPLOG" 
    ]
}

You can adjust the parameters in the request body based on your requirements. For detailed response schema, see Knox Asset Intelligence API.

You can receive notifications for these log generation events using Knox Webhook Notification, if subscribed.

Retrieve diagnostic logs

To retrieve Knox Asset Intelligence settings, make a GET request to the /diagnosticsLogs endpoint and specify query parameters in the request to get the required device diagnostic log.

The query parameter is logId which is the tracking number returned from the POST /diagnosticsLogs. A maximum of 50 log IDs can be included in a single request.

For example, the following request sample returns details, such as serial number, group name, and download link for generated diagnostic logs, for the logIDs 64e851ddc136352a60a5e1a0 and 84e051ddc136352a60a5e1a3.

GET 
/diagnosticsLogs?
logId=64e851ddc136352a60a5e1a0&
logId=84e051ddc136352a60a5e1a3

Ensure that you handle errors appropriately in your application by checking the code and the message in the response. For detailed specification, see Knox Asset Intelligence API reference.

Create a subscription in Knox Webhook Notification

To receive asynchronous notifications when a diagnostic log is generated:

1. Subscribe to the Knox Webhook Notification API using POST /kwn/v1/subscriptions operation.

2. In the request body, specify a subscription URL to receive callbacks and the KAI_DEVICE_DIAGNOSTICSLOGS event to subscribe to notifications for diagnostic log generation events.

For example, the following request body allows you to be notified on the specified subscription URL, when Knox Asset Intelligence completes log generation.

{
  "url": "https://some.domain/kwn-results",
  "events": [
    "KAI_DEVICE_DIAGNOSTICSLOGS"
  ]
}

The response message containing a specific download link and other log details is sent to the subscription URL. You can use the download link to view the log file generated by Knox Asset Intelligence.

For more information, see Knox Webhook Notification for Knox Asset Intelligence.