How to collect debug logs from your Azure IoT devices
To troubleshoot device issues, it's sometimes useful to collect low-level debug logs from the devices. This article shows how to capture debug logs from the device SDKs. The steps outlined in this article assume you have either direct or remote access the device.
Caution
If you're sharing logs with a support engineer or adding them to a GitHub issue, be sure to remove any confidential information such as connection strings.
Capture trace logs
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.
Capture trace data on Windows
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.
Capture trace data on Linux
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*
Tip
If you're using the AMQP protocol, use rhea* to capture trace information from the low-level library.
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.
Next steps
If you need more help, you can contact the Azure experts on the Microsoft Q&A and Stack Overflow forums. Alternatively, you can file an Azure support incident. Go to the Azure support site and select Get Support.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for