Logging Subsystem

ThingWorx Model Definition in Composer > System > Subsystems > Logging Subsystem

Logging Subsystem

The logging subsystem manages various logs, such as Application, Script, and Communications.

Configuration

Log Retention Settings

Data Type

Default

Notes

Maximum File Size In KB

INTEGER

100000

When the size reaches or exceeds the defined size, the next log event triggers the rollover of the file to the ThingworxStorage > logs > archives folder.

You can change the default setting at run time to immediately save changes.

Maximum size is 1000000 KB.

Maximum Number Days for Archive

INTEGER

Daily rollovers are not clock-driven but depend on the arrival of logging events. Files are rolled over at midnight daily (and only upon the arrival of a log event) and moved to the archives folder.

By default, if a log is in the archive for more than seven days, it is deleted. You can change the default to 1 or up to 90 days.

Enable Stack Tracing

BOOLEAN

false

If enabled, when a service call error occurs in the Java API to com.thingworx.logging.LogUtilities.logInstanceExceptionDetails, the associated stack trace is logged in the ErrorLog.log file in the ThingworxStorage > logs folder. Helpful for debugging errors on the platform.

Enable Script Stack Tracing

BOOLEAN

true

If an error occurs in a script, the associated stack trace is logged in the ScriptErrorLog.log file located in the ThingworxStorage>logs folder. Helpful for debugging scripts created by platform users.

By default the script timeout setting on the ThingWorx platform is 30 seconds. If a script runs longer than this, the platform terminates the execution. A ThingWorx administrator can configure the script timeout in the Basic Settings section of the platform-settings.json configuration file. See also platform-settings.json Configuration Details.

In the ThingWorx Platform, if any error occurs and persists, logs are generated and printed in the respective log files, such as the application, script, and database. It is also observed that an error persists for a longer period of time, resulting in log files flooding with similar logs.

To overcome this scenario, the following configurations are introduced:

Prerequisite

Add the following filter to the logback.xml file.

Repetitive Log Filter Settings	Data Type	Default Value	Notes
Enable Log Filtering	BOOLEAN	false	To enable or disable log filtering.
Cache Size	INTEGER	2000	The size of the cache to store unique entries at a time.
Allowed Repetitions	INTEGER	10	Number of times repetitive logs can be logged (first occurrence is not counted in repetition).
Expire After Write Seconds	INTEGER	300	Duration in seconds to maintain logging of allowed repetitions.
Include Packages For Filtering	STRING		A comma separated list of packages to be included for filtering.

• Filtering of logs is only applicable for ERROR or WARN logs for configured packages under Include Packages For Filtering.

• Changing the value of Enable Log Filtering to true and adding package names to Include Packages For Filtering parameter enables the tracking of repetitive error or warn logs.

• Any change in the configuration parameter previously mentioned, resets the cache entries. Configured package related error or warn logs tracking restarts.

• Error or warn logs repetitions are tracked through Allowed Repetitions configuration parameter. Error or warn logs are printed only for configured values.

• Error or warn logs printing is paused after configured repetition count and until time mentioned in Expire After Write Seconds configuration parameter expires.

• Skipped counts and logged counts of repetitive log details are logged with DEBUG level log.

• You should be able to configure package/s through a comma-separated list. Mentioned packages will be tracked for error or warn logs.

• The Repetitive Log Filter Settings requires the complete package name to be mentioned in Include Packages For Filtering. For example, com.thingworx.system.subsystems.filetransfer is acceptable, but com.thingworx.system.subsystems or com.thingworx.system are not.

When setting the log level to DEBUG or TRACE, there will be an exponential increase in log volume for respective logs. The following configurations are introduced in LoggingSubsystem to reset log level after mentioned interval:

Log Level Auto Reset Settings	Data Type	Default Value (in seconds)	Notes
Global Trace Reset Interval in Seconds	Integer	600	If the default log level is changed to TRACE for any log (for example, ApplicationLog, and ScriptLog), the time interval mentioned acts as a timer. Once the timer goes off, the log level resets back to the previously set level.
Global Debug Reset Interval in Seconds	Integer	600	If the default log level is changed to DEBUG for any Log (for example, ApplicationLog, and ScriptLog), the time interval mentioned acts as a timer. Once the timer goes off, the log level resets back to the previously set level.
Sublogger Debug Reset Interval in Seconds	Integer	3600	If any Sublogger package is set to TRACE level, then the time interval mentioned acts as timer. Once timer goes off, log level resets back to default log level for respective Sublogger. This configuration helps to control exponential increase in log volume.
Sublogger Trace Reset Interval in Seconds	Integer	3600	If any Sublogger package is set to DEBUG level, then time interval mentioned acts as timer. Once the timer goes off, log level resets back to default log level for respective Sublogger. This configuration helps to control exponential increase in log volume.

• If ThingWorx Platform server or all nodes restart, then mentioned reset interval for global and sublogger will start again.

• ALL log levels have the same effect as TRACE log level for reset functionality. It does not have a separate timer and follows the intervals of global and sublogger TRACE levels.