SmartInspect Logging Configuration
The SmartInspectPython package (installed with this integration) can be used to easily debug the integration; furthermore, you can see the logged events as they happen if you have the SmartInspect Redistributable Console application installed.
Use the index to learn more about SmartInspect tracing.
SmartInspect logging is controlled for the integration by creating a configuration file in the Home Assistant config folder. The file contains the logging level (e.g. Debug, Verbose, Message, Warning, Error), the type of connection to log to (e.g. a local file, another computer on the network running the SI Console, both, etc), as well as session-specific colors and logging levels. If logging to a local file, the connection settings can control the rotation of the log (e.g. only keep 3 log files) as well as the frequency of rotation (e.g. hourly, daily, weekly, etc). This ensures that your file system is not filled with endless log files if you forget to turn tracing off.
SmartInspect logging CANNOT log data from other applications or Home Assistant base code. The information logged by the integration is controlled by lines of code embedded in the integration source code. It's the same thing as using a standard Python logger - it won't log anything unless you tell it to via coding.
A SmartInspect Console Viewer is required to view SmartInspect Log (.sil) formatted log files, as well capture packets that are sent over the network. The SI Console Viewer can accept connections from multiple machines, so you can capture logging information from many sources simultaneously. Note that a Console Viewer is NOT required to view plain text (non .sil) formatted log files.
An SI Console Viewer can be downloaded from the Code-Partners Software Downloads page. Note that the "Redistributable Console Viewer" is a free product, while the "SmartInspect Full Setup" is the Professional level Console Viewer that adds a few more bells and whistles for a fee.
As of this writing, the SI Console Viewers can only be installed on a Windows OS computer running on your network. You can then add a Connection = to your configuration file to route logging activity to the IP address of the machine running the SI Console viewer. To be clear, the Si Console Viewer can only run on Windows OS, but integrations (or applications) using the SmartInspect logger package can run on any OS platform (e.g. Windows, Unix, Linux, MacOS, etc) that supports Python3 and the SmartInspectPython package.
The SI Console Viewer communicates on port 4228, so you may need to add a firewall rule (or allow inbound activity) to the machine the Console Viewer is running on.
Here is an example of an SI Console and what it captures:
Now that you are somewhat familiar with the SI Console, let's get started on setting up a configuration file and start logging some data!
The SmartInspect configuration file controls various aspects of the trace: where to log information, enabling / disabling of logging, logging level, session colors, etc.
The various integrations that I author are coded so that they look for a file named smartinspect.cfg located in the Home Assistant configuration folder.
There are various ways to create this file in the HA environment (HA File Editor add-on, VSCode editor, copy via ssh, etc). I prefer to use the HA File Editor add-on; if you are not familiar with it, follow the initial instructions in this tutorial to install it to your HA environment.
Using your editor of choice, create a new file in the HA configuration folder path named /config/smartinspect.cfg and add the following lines:
; smartinspect.cfg
; SmartInspect Configuration File settings.
; SmartInspect Logging output settings.
; remove the semi-colon (;) from a single "Connections = " line below to enable the option.
; only one "Connections = " line below can be active.
; - Log to SmartInspect Console Viewer running on the specified network address.
Connections = tcp(host=192.168.1.1,port=4228,timeout=30000,reconnect=true,reconnect.interval=10s,async.enabled=true)
; - Log to a file, keeping 3 days worth of logs, with a new log file created each day.
;Connections = file(filename="/config/smartinspect.sil", rotate=daily, maxparts=3, append=true)
; - Log to an encrypted file, keeping 3 days worth of logs, with a new log file created each day.
;Connections = file(filename="/config/smartinspectEncrypted.sil", encrypt=true, key="1234567890123456", rotate=daily, maxparts=3, append=true)
; - Log to SmartInspect Console Viewer AND to a local log file.
;Connections = tcp(host=192.168.1.1,port=4228,timeout=5000,reconnect=true,reconnect.interval=10s,async.enabled=true), file(filename="/config/smartinspect.sil",rotate=daily,maxparts=3,append=true)
; SmartInspect Logging Configuration General settings.
Enabled = True
Level = Verbose
DefaultLevel = Debug
AppName = Home Assistant VM
; set defaults for new sessions
; session defaults only apply to newly added sessions and do not affect existing sessions.
SessionDefaults.Active = True
SessionDefaults.Level = Verbose
SessionDefaults.ColorBG = 0xFFFFFF
; configure some individual session properties.
; note that this does not add the session to the sessionmanager; it simply
; sets the property values IF the session name already exists.
;Session.Main.Active = True
;Session.Main.Level = Verbose
;Session.Main.ColorBG = 0xFFFFFF
; configure SoundTouchPlus integration sessions.
Session.custom_components.soundtouchplus.ColorBG = 0x1AAE54
Session.custom_components.soundtouchplus.config_flow.ColorBG = 0x1AAE54
Session.custom_components.soundtouchplus.media_player.ColorBG = 0x40A9FB
; configure bosesoundtouchapi package sessions.
Session.bosesoundtouchapi.soundtouchdiscovery.ColorBG = 0xFBD340
Session.bosesoundtouchapi.websockets.soundtouchwebsocket.ColorBG = 0xFBD340
; configure SpotifyPlus integration sessions.
Session.custom_components.spotifyplus.ColorBG = 0x1AAE54
Session.custom_components.spotifyplus.config_flow.ColorBG = 0x1AAE54
Session.custom_components.spotifyplus.media_player.ColorBG = 0x40A9FBThe settings (as listed above) tell SmartInspect to route all logging activity to an SI Console viewer that is running on a Windows OS machine IP address of 192.168.1.1. Tracing is enabled (e.g. Enabled=True) with a verbose logging level (e.g. Level=Verbose).
If you prefer not to log packets over the network, then adjust the Connection = setting by commenting out (semi-colon ';' in position 1) the option you don't want and uncommenting the one you DO want. I have included several commented Connection = options to route log data to various types of connections, including encrypted files.
SmartInspect Logging support can be turned on and off for the integration without restarting Home Assistant. Just set Enabled=True or Enabled=False and save the file. The SmartInspect logger will detect the change, and reload the configuration to enable or disable logging immediately.
Save the configuration file to immediately apply the changes.
IMPORTANT - don't forget to disable logging (e.g. Enabled=False) when you are done with it, as it consumes extra resources to log information; especially if you are using the Debug log level!
Edit the /config/smartinspect.cfg file and change the Enabled setting:
- specify
Enabled=Trueto enable logging, orEnabled=Falseto disable logging. - save your changes to the file.
- you DO NOT need to restart Home Assistant.
The various integrations that I author are coded so that they look for a file named smartinspect.cfg located in the Home Assistant configuration folder.
There are various ways to create this file in the HA environment (HA File Editor add-on, VSCode editor, copy via ssh, etc). I prefer to use the HA File Editor add-on; if you are not familiar with it, follow the initial instructions in this tutorial to install it to your HA environment.
Using your editor of choice, create a new file in the HA configuration folder path named /config/smartinspect.cfg and add the following lines:
; smartinspect.cfg
; SmartInspect Configuration File settings.
; SmartInspect Logging output settings.
; - Log to a encrypted file, keeping 3 days worth of logs, with a new log file created each day.
Connections = file(filename="/config/smartinspect.sil", encrypt=true, key="123456", rotate=daily, maxparts=3, append=true)
; SmartInspect Logging Configuration General settings.
Enabled = True
Level = Verbose
DefaultLevel = Debug
AppName = HA
; set defaults for new sessions
; session defaults only apply to newly added sessions and do not affect existing sessions.
SessionDefaults.Active = True
SessionDefaults.Level = Verbose
SessionDefaults.ColorBG = 0xFFFFFFYou can select your own encryption key by changing the key="123456" value to the key of your choice (e.g. key="8675309"). The key value cannot exceed 16 characters.
Restart Home Assistant, waiting for the "Home Assistant has started" message to appear in the browser window (e.g. restarted fully). This will allow the integration you are tracing time to fully start.
This should generate a new (encrypted) trace file in the config folder with a date stamp suffix (e.g. /config/smartinspect-yyyy-mm-dd-hh-mm-ss.sil). I will then ask you to send me that file for diagnosis, as well as the encryption key value you specified.
Check out the following links for more information on SmartInspect.