NoTouch Center Log configuration and options

Logging information and options for NoTouch Center including syslog

NoTouch Center logging has been carefully engineered to supply exactly the right amount of information. In some cases, users may need more fine-grain control on NoTouch Center logging. For instance, it could be necessary to:

increase logging (debug) in case of troubleshooting
disable annoying but harmless log messages
specially treat log messages that emanate from your own scripts using the Scripting interface

Every log message knows its originating module (e.g. com.stratodesk.center.msrv.MServer), a log level (e. g. DEBUG, INFO, ERROR) and the actual log message. The logging system distributes these log messages into certain appenders. There are two appenders configured by default, one logs to the system console (=standard output), the other one into the database, the APPLOG table; this is what you then find in the "Log" view in NoTouch Center.

The standard output will be redirected to a file named center.log - i.e. the center.log file is the main and most important log file:

On a Stratodesk Virtual Appliance the file is /var/log/center.log

1 Log configuration file
2 Log output format
3 Exceptions and stack traces
4 Logging to syslog

Log configuration file

The master log configuration file is log4j2.xml - NoTouch Center uses the well-established Log4J2 toolkit [1] for logging. The file resides in the main NoTouch Center installation directory /opt/center/.

Use a regular text editor to edit the file /opt/center/. If you edit this file, please restart NoTouch Center afterwards for the changes to become effective (Linux command - systemctl restart center)

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="ERROR" package="com.stratodesk.center">
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{ISO8601} %-5p [%t] %c: %m%n"/>
    </Console>
    <TorqueDBAppender name="TorqueDBAppender">
    </TorqueDBAppender>
  </Appenders>
  <Loggers>
          <Logger name="com.stratodesk" level="INFO">
                  <AppenderRef ref="TorqueDBAppender"/>
          </Logger>
          <Logger name="scripts" level="INFO">
                  <AppenderRef ref="TorqueDBAppender"/>
          </Logger>
          <Logger name="org.apache.commons.httpclient" level="ERROR"/>
          <Logger name="org.apache.commons.httpclient" level="ERROR"/>
          <Logger name="org.apache.struts" level="ERROR"/>
          <Logger name="net.sf.jasperreports" level="ERROR"/>
          <Root level="ERROR">
                <AppenderRef ref="Console"/>
          </Root>
  </Loggers>
</Configuration>

The easiest thing to add more verbosity is to modify the line <Logger name="com.stratodesk" level="INFO"> to be <Logger name="com.stratodesk" level="DEBUG"> - This will greatly increase the load and logging on the server, only use for diagnostic purposes.

remember to edit back to <Logger name="com.stratodesk" level="INFO"> when diagnostic is completed

Another example - add a line right before the <Root level="ERROR"> line.

    <Logger name="com.stratodesk.msrv.MServer" level="DEBUG"/>

This example would enable debug-level logging for the MServer, the component that deals with clients.

Another example: Let's assume you are writing scripts using the Scripting interface. You frequently use logger.debug() statements in your code and you want this visible. So change the log level of the "scripts" namespace to DEBUG:

        <Logger name="scripts" level="DEBUG">
                 <AppenderRef ref="TorqueDBAppender"/>
         </Logger>

Log output format

Each line in the log file has the following fields:

Exact timestamp (date and time including microseconds)
Log level
Thread ID
Originating module
Actual message

Take this example:

2015-06-14T01:13:33,896 INFO  [main] com.stratodesk.center.Start: Product version: 4.1.404
2015-06-14T01:13:33,898 INFO  [main] com.stratodesk.center.Start: Instance UUID: 5d842478-9012-47e4-XXXX-XXXXee0f602f
2015-06-14T01:13:33,900 INFO  [main] com.stratodesk.center.LicenseManager: Local Address:stratodeskva (IP(s): 192.168.21.10)
2015-06-14T01:13:34,778 INFO  [main] com.stratodesk.center.DatabaseNG: Database configured and connected
2015-06-14T01:13:34,868 INFO  [main] com.stratodesk.center.DatabaseNG: Upgrading database from older product version 4.1.384
2015-06-14T01:13:34,886 INFO  [main] com.stratodesk.center.web.UpdateManager: system imported release information 
2015-06-14T01:19:20,677 INFO  [main] com.stratodesk.center.web.UpdateManager: system imported lang information 
2015-06-14T01:19:20,736 INFO  [main] com.stratodesk.center.LicenseManager: License present: 30x LMD for Stratodesk Test Environment (6XYZ7250)
2015-06-14T01:19:20,737 INFO  [main] com.stratodesk.center.LicenseManager: License present: 50x MCLI for Stratodesk Test Environment (6XYZ7251)
2015-06-14T01:23:29,780 INFO  [main] com.stratodesk.center.Start: System ready
2015-06-14T02:57:15,293 INFO  [qtp664996488-36] com.stratodesk.center.LoginService: User 'admin' (System Administrator) logged in from 127.0.0.1
2015-06-14T02:58:58,034 INFO  [qtp664996488-38] com.stratodesk.center.actions.logon.LogoffAction: User 'admin' logged off

Exceptions and stack traces

An "exception" denotes a state of a software program that is "unusual". Using exceptions allows to write cleaner and more efficient code, as multiple "if (ok) then - else" constructs are eliminated and replaced by a 'mainstream' execution path and unusual states like "disk drive full" etc. An exception does not necessarily mean a catastrophic failure of some component and it does not mean there is a software bug - not all! It only means something is "exceptional".

Sometimes exceptions are logged with a "stack trace" that allows the programmer to know exactly where in the program code the exception happened. This can be helpful for improving the software, sometimes it has no value whatsoever. Imagine a situation when suddenly the database server (Oracle, MS SQL, MySQL) crashes and NoTouch Center can not fulfill a query.

org.apache.torque.TorqueException: com.mysql.jdbc.exceptions.jdbc4.MySQLQueryInterruptedException: Query execution was interrupted
        at org.apache.torque.util.BasePeer.throwTorqueException(BasePeer.java:105)
        at org.apache.torque.util.BasePeer.executeQuery(BasePeer.java:945)
        at org.apache.torque.util.BasePeer.doSelect(BasePeer.java:783)
        at org.apache.torque.util.BasePeer.doSelect(BasePeer.java:756)

Even though the system logs a nice stack trace and we know exactly where in the code the exception occured, it is still not really helpful because we are not dealing with a software but instead the failure of an external component.

What this means is, if you try to debug a problem, look into the log files, check it for exceptions, but keep the "big picture" in mind - an exception is not necessarily the problem, most likely it is a symptom, but not the cause!

Logging to syslog

Of course you can direct log messages to a syslog server instead of the default log file. The underlying logging framework supports the SyslogAppender, so you

register the SyslogAppender in the Appenders section
reference it in the Loggers section depending on your actual logging desires

On the NoTouch Center VA

Connect via SSH

Elevate privileges

In /opt/center - You will find log4j2.xml - You can use a text editor to edit the file

Add a new line in the “<Appenders>” section with the syntax :
- <Syslog name="bsd" host="destinationIP" port="port" "Protocol"/>
In the <Syslog name=’’ " field, enter bsd
In the host=’’” field, enter the destination IP of the Target Syslog Server
In the port=”” field, enter the port the Syslog server is listening. Ex 514
In the protocol=””, enter the protocol you wish to use. Ex TCP
Once that line is complete, towards the bottom of the log4j2.xml file there is a section:
- <AppenderRef ref=”bsd”/>
This field must equal the same as defined in the Syslog name = in 1a above
- The log4j2.xml should look similar to below
Note* there are several mentions of AppenderRef, Only Need to change the <AppenderRef> below <Root level="ERROR"> (for this example below)

An example - look for both occurrences of the "bsd" logger:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="ERROR" package="com.stratodesk.center">
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{ISO8601} %-5p [%t] %c: %m%n"/>
    </Console>
    <TorqueDBAppender name="TorqueDBAppender">
    </TorqueDBAppender>
    <Syslog name="bsd" host="192.168.1.10" port="514" protocol="TCP"/>
  </Appenders>
  <Loggers>
          <Logger name="com.stratodesk" level="INFO">
                  <AppenderRef ref="TorqueDBAppender"/>
          </Logger>
          <Logger name="scripts" level="INFO">
                  <AppenderRef ref="TorqueDBAppender"/>
          </Logger>
          <Logger name="org.apache.commons.httpclient" level="ERROR"/>
          <Logger name="org.apache.commons.httpclient" level="ERROR"/>
          <Logger name="org.apache.struts" level="ERROR"/>
          <Logger name="net.sf.jasperreports" level="ERROR"/>
          <Root level="ERROR">
                <AppenderRef ref="bsd"/>
          </Root>
  </Loggers>
</Configuration>

The SyslogAppender can do much more than just old-school syslog - please see log4j2 SyslogAppender for a complete overview.