ThingWorx Model Definition in Composer > System > Logs > Configuring Logging
Configuring Logging
A default internal-logback.xml file is part of the ThingWorx .war file and is used to configure the logback subsystem. To find the file, unzip the Thingworx.war file and then unzip WEB_INF/lib/thingworx-platform-common-[version_number].jar.
You can copy the internal-logback.xml to /ThingworxPlatform/logback.xml and make changes. These logback.xml files do not stack or inherit from each other. You can then place your updated file in the ThingWorx configuration directory default/ThingworxPlatform for each ThingWorx instance.
Changing the Log Level to DEBUG
You can change an entry to force the log level of a specific class to DEBUG. For example, you can change the following:
<logger name="org.springframework.security" level="INFO" additivity="false">
<appender-ref ref="ASYNC_APPENDER_SECURITY"/>
</logger>
to the following withlevel="DEBUG":
<logger name="org.springframework.security" level="DEBUG" additivity="false">
<appender-ref ref="ASYNC_APPENDER_SECURITY"/>
</logger>
Or, you can add a new entry with the specific log level. For example:
<logger name="com.thingworx.security.authentication.sso" level="DEBUG" additivity="false">
<appender-ref ref="ASYNC_APPENDER_SECURITY"/>
</logger>
A package-level entry like this will turn on logging for that package and the subpackages.
Appenders
You can specify in which log you want the information to appear by specifying the correct appender in <appender-ref ref="[appender name]"/>. The possible appenders are:
• ASYNC_APPENDER_CONSOLE - console output
• ASYNC_APPENDER_APPLICATION - application log
• ASYNC_APPENDER_ERROR - error log
• ASYNC_APPENDER_SECURITY - security log
• ASYNC_APPENDER_SCRIPT - script log
• ASYNC_APPENDER_SCRIPT_ERROR - script error log
• ASYNC_APPENDER_CONFIGURATION - configuration log
• ASYNC_APPENDER_DATABASE - database log
• ASYNC_APPENDER_COMMUNICATION - communication log
Asynchronous Appender
ThingWorx uses the logback logging library with console and rolling file appenders. Both of these appenders are wrapped with the asynchronous appender, which disconnects the log requesters from actual log writes. The log requesters call the append(logEvent) method on AsyncAppender. This method adds the logEvent to the internal queue inside of the AsyncAppender. Therefore, the log requester can continue its work without having to wait for the logEvent to be written to the destination console or file. In the AsyncAppender, an internal thread picks the oldest logEvent from the internal queue and calls append(LogEvent) on the containing log appender console or file. The internal queue also serves as a buffer, which prevents data loss during short bursts in activity when the logging requests per second outnumber the internal appender write speed.For more information, see https://logback.qos.ch/manual/appenders.html.
You can configure the following parameters for the AsyncAppender in the logback.xml file:
Parameter
Environment Variable
Base Type
Default
Description
queueSize
different for each AsyncAppender; see table below
INTEGER
256
The maximum capacity of the blocking queue. This value is used during the creation of the AsyncAppender and cannot be changed. This value can be set per appender.
discardingThreshold
DISCARDING_THRESHOLD
INTEGER
0%
By default, when the blocking queue has 20% capacity remaining, it will drop events with TRACE, DEBUG, and INFO levels, and keep events with WARN and ERROR levels. To keep all events, set discardingThreshold to 0.
maxFlushTime
MAX_FLUSH_TIME
INTEGER
1000 ms
The maximum queue flush timeout in milliseconds. Depending on the queue depth and latency to the referenced appender, the AsyncAppender may take an unacceptable amount of time to fully flush the queue. When the LoggerContext is stopped, the AsyncAppender stop method waits this amount of time for the worker thread to complete. Events that cannot be processed within this time are discarded. The semantics of this value are identical to those of Thread.join(long).
neverBlock
NEVER_BLOCK
BOOLEAN
false
By default, this parameter is set to false, which means that the appender will block appending to a full queue rather than lose the message. If you set it to true, the appender will drop the message and not block your application.
Queue Size Values for Async Appenders
Each AsyncAppender has its own value forqueueSize since loggers will have different loads and need different queue sizes.
Appender Name
Environment Variable
Default
ASYNC_APPENDER_APPLICATION
MAX_QUEUE_SIZE_APPLICATION
10000
ASYNC_APPENDER_CONSOLE
ASYNC_APPENDER_CONSOLE
10000
ASYNC_APPENDER_CONFIGURATION
MAX_QUEUE_SIZE_CONFIGURATION
1000
ASYNC_APPENDER_SECURITY
MAX_QUEUE_SIZE_SECURITY
1000
ASYNC_APPENDER_DATABASE
MAX_QUEUE_SIZE_DATABASE
1000
ASYNC_APPENDER_COMMUNICATION
MAX_QUEUE_SIZE_COMMUNICATION
1000
ASYNC_APPENDER_ERROR
MAX_QUEUE_SIZE_ERROR
5000
ASYNC_APPENDER_SCRIPT
MAX_QUEUE_SIZE_SCRIPT
5000
ASYNC_APPENDER_SCRIPT_ERROR
MAX_QUEUE_SIZE_SCRIPT_ERROR
5000
You can change the default values by setting the associated environment variable. If you are running a server in Eclipse, you need to set the environment variables in Run configuration/server/environment.
The values specified through environmental variables will only be picked up during server startup. Therefore, if you want to change any of the values after the server is started, you have to restart it.
Log Settings
The default logback configuration settings for rolling files and archiving are below. You can configure these settings in Composer under Subsystems > LoggingSubsystem > Configuration > Log Retention Settings.
Log Retention Setting
Property Name
Default
Description
Maximum File Size In KB
MAX_FILE_SIZE
100000
Limit for the size of each log file
Maximum Number Days For Archive
MAX_HISTORY_SIZE
7
Number of days of log files kept in the archive
Total Size In GB Of All Log Files to Retain
TOTAL_SIZE_CAP
10
Limit for the size of all log files in the archive
Cluster Mode Versus Single-Server Mode
In cluster mode, multiple instances are going to write their logs to a single file. To achieve this, you have to enable theprudentflag in theRollingFileAppenderconfiguration; however, there are restrictions:
• In prudent mode, file compression is not allowed. One instance cannot be writing while another is compressing.
• The file property of FileAppender must be blank. Most operating systems do not allow renaming a file while another process has it open.
The following example has RollingFileAppender configured with SizeAndTimeBasedRollingPolicyin cluster mode:
<!-- configuration appender -->
<appender name="CONFIGURATION" class="ch.qos.logback.core.rolling.RollingFileAppender">

<!-- Support multiple-JVM writing to the same log file -->
<prudent>true</prudent>

<rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
<fileNamePattern>{LOG_PATH}/ConfigurationLog.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
<maxHistory>{MAX_HISTORY_SIZE}</maxHistory>
<totalSizeCap>{TOTAL_SIZE_CAP}</totalSizeCap>
<maxFileSize>{MAX_FILE_SIZE}</maxFileSize>
</rollingPolicy>

<encoder class="com.thingworx.logging.ThingWorxPatternLayoutEncoder">
<pattern>{CONFIGURATION_LAYOUT_PATTERN}</pattern>
</encoder>
</appender>
In single-server mode, the active log file will be placed in{ThingworxStorage}/logs and the rolled-over file will be in{ThingworxStorage}/logs/archive.
The following example hasRollingFileAppenderconfigured withSizeAndTimeBasedRollingPolicyin single-server mode:
<!-- application appender -->
<appender name="APPLICATION" class="ch.qos.logback.core.rolling.RollingFileAppender">

<file>{LOG_PATH}/ApplicationLog.log</file>

<rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
<fileNamePattern>{LOG_PATH}/archives/ApplicationLog.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
<maxHistory>{MAX_HISTORY_SIZE}</maxHistory>
<totalSizeCap>{TOTAL_SIZE_CAP}</totalSizeCap>
<maxFileSize>{MAX_FILE_SIZE}</maxFileSize>
</rollingPolicy>

<encoder class="com.thingworx.logging.ThingWorxPatternLayoutEncoder">
<pattern>{LAYOUT_PATTERN}</pattern>
</encoder>
</appender>
Was this helpful?