How to collect debug logs from your Azure IoT devices

To capture trace data from the Azure IoT Hub client connection, you use the client logtrace option.

You can set the option by using either the convenience layer or low-level layer:

// Convenience layer for device client
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_SetOption(IOTHUB_DEVICE_CLIENT_HANDLE iotHubClientHandle, const char* optionName, const void* value);

// Lower layer for device client
IOTHUB_CLIENT_RESULT IoTHubDeviceClient_LL_SetOption(IOTHUB_DEVICE_CLIENT_LL_HANDLE iotHubClientHandle, const char* optionName, const void* value);

The following example from the pnp_temperature_controller.c sample shows how to enable trace capture by using the convenience layer:

static bool g_hubClientTraceEnabled = true;

...

else if ((iothubClientResult = IoTHubDeviceClient_LL_SetOption(deviceClient, OPTION_LOG_TRACE, &g_hubClientTraceEnabled)) != IOTHUB_CLIENT_OK)
{
    LogError("Unable to set logging option, error=%d", iothubClientResult);
    result = false;
}

The trace output is written to stdout.

To learn more about capturing and viewing trace data from the C SDK, see IoT Hub device and module client options.

On Windows, the Azure IoT SDK for .NET exports trace data by using Event Tracing for Windows (ETW). The SDK repository includes PowerShell scripts to start and stop a capture.

Run the following scripts in an elevated PowerShell prompt on the device. The iot_providers.txt file lists the GUIDs for the IoT SDK providers. To start capturing trace data in a file called iot.etl:

.\iot_startlog.ps1 -Output iot.etl -ProviderFile .\iot_providers.txt -TraceName IotTrace

To stop the capture:

 .\iot_stoplog.ps1 -TraceName IotTrace

To learn more about capturing and viewing trace data from the .NET SDK, see Capturing Traces.

On Linux, you can use the dotnet-trace tool to capture trace data. To install the tool, run the following command:

dotnet tool install --global dotnet-trace

Before you can collect a trace, you need the process ID of the device client application. To list the processes on the device, run the following command:

dotnet-trace ps

The following example output includes the TemperatureController device client process with process ID 24987:

24772  dotnet                 /usr/share/dotnet/dotnet                 dotnet run
25206  dotnet                 /usr/share/dotnet/dotnet                 dotnet trace ps
24987  TemperatureController  /bin/Debug/net6.0/TemperatureController

To capture trace data from this process to a file called device.nettrace, run the following command:

dotnet-trace collect --process-id 24987 --output device.nettrace --providers Microsoft-Azure-Devices-Device-Client

The providers argument is a comma-separated list of event providers. The following list shows the Azure IoT SDK providers:

• Microsoft-Azure-Devices-Device-Client
• Microsoft-Azure-Devices-Service-Client
• Microsoft-Azure-Devices-Provisioning-Client
• Microsoft-Azure-Devices-Provisioning-Transport-Amqp
• Microsoft-Azure-Devices-Provisioning-Transport-Http
• Microsoft-Azure-Devices-Provisioning-Transport-Mqtt.
• Microsoft-Azure-Devices-Security-Tpm

To learn more about capturing and viewing trace data from the .NET SDK, see Capturing Traces.

The Azure IoT SDK for Java exports trace data by using SLF4j. The samples included in the SDK configure SLF4j by using a property file: src/main/resources/log4j2.properties. The property file in each sample configures logging to the console:

status = error
name = Log4j2PropertiesConfig

appenders = console

appender.console.type = Console
appender.console.name = LogToConsole
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %d %p (%t) [%c] - %m%n

rootLogger.level = debug
rootLogger.appenderRefs = stdout
rootLogger.appenderRef.stdout.ref = LogToConsole

To log just debug messages from the SDK to a file, you can use the following configuration:

status = error
name = Log4j2PropertiesConfig

# Log file location - choose a suitable path for your OS
property.filePath = c/temp/logs

appenders = console,file

appender.console.type = Console
appender.console.name = LogToConsole
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %d %p (%t) [%c] - %m%n

appender.file.type = File
appender.file.name = LogToFile
appender.file.fileName = ${filePath}/device.log
appender.file.layout.type = PatternLayout
appender.file.layout.pattern = %d %p (%t) [%c] - %m%n

loggers.file
logger.file.name = com.microsoft.azure.sdk.iot
logger.file.level = debug
logger.file.appenderRefs = logfile
logger.file.appenderRef.logfile.ref = LogToFile

rootLogger.level = debug
rootLogger.appenderRefs = stdout
rootLogger.appenderRef.stdout.ref = LogToConsole

To learn more about capturing and viewing trace data from the Java SDK, see Azure IoT SDK logging.

The Azure IoT SDK for Node.js uses the debug library to capture trace logs. You control the trace by using the DEBUG environment variable.

To capture trace information from the SDK and the low-level MQTT library, set the following environment variable before you run your device code:

export DEBUG=azure*,mqtt*

To capture just the trace data to a file called trace.log, use a command such as:

node pnp_temperature_controller.js 2> trace.log

To learn more about capturing and viewing trace data from the Node.js SDK, see Troubleshooting guide - devices.

The Azure IoT SDK for Python uses the logging module to capture trace logs. You control the trace by using a logging configuration file. If you're using one of the samples in the SDK, you may need to modify the code to load a logging configuration from a file:

Replace the following line:

logging.basicConfig(level=logging.ERROR)

With this line:

logging.config.fileConfig('logging.conf')

Create a file called logging.conf. The following example captures debug information from all modules with a prefix azure.iot.device in the file:

[loggers]
keys=root,azure

[handlers]
keys=consoleHandler,fileHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=ERROR
handlers=consoleHandler

[logger_azure]
level=DEBUG
handlers=fileHandler
qualname=azure.iot.device
propagate=0

[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)

[handler_fileHandler]
class=FileHandler
level=DEBUG
formatter=simpleFormatter
args=('device.log', 'w')

[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s

To learn more about capturing and viewing trace data from the Python SDK, see Configure logging in the Azure libraries for Python.

To capture trace information from the Azure SDK for Embedded C library for embedded IoT devices, add a callback function to your device code that handles the trace messages. For example, your callback function could write to the console and save the messages to a file.

The following example shows how you could modify the paho_iot_hub_sas_telemetry_sample.c to capture trace information and write it to the console:

#include <azure/core/az_log.h>

...

static void write_log_message(az_log_classification, az_span);

...

int main(void)
{
  az_log_set_message_callback(write_log_message);

  ...
}

static void write_log_message(az_log_classification classification, az_span message)
{
   (void)classification;
   printf("TRACE:\t\t%.*s\n", az_span_size(message), az_span_ptr(message));
}

To learn more about capturing and filtering trace data in the Embedded C SDK, see Logging SDK operations.