Logging
The Logback logging framework is used to manage the logs. The default logging configuration for a Connection Server writes logs with a log level of INFO or higher to standard out. For more control over the logging configuration, you can create a new logging configuration XML file (logback.xml) and instruct the Connection Server to use it by setting the environment variable for the Connection Server.
For information on how to configure the appenders and encoders for the logging configuration, see the manual page on the Logback website: http://logback.qos.ch/manual/index.html and the examples below.
This topic includes the following information about logging for the ThingWorx Connection Server:
◦ Table 7
◦ Table 8
Types of Logs
There are two types of logs:
• Operational — Contains messages that describe the state of the application or changes in the state of the application. It is intended for system administrators or any person interested in the general health of the system. For example:
◦ The application has started.
◦ The application failed to start due to an error in the configuration.
◦ An external system that was previously unavailable is available again.
◦ The configuration has been updated.
◦ A periodic process has run.
◦ A bounded resource has exhausted all of its resources.
• Functional — Contains messages that describe the lower-level details about what the individual application components are doing to accomplish their purpose (or function), including the context. In general, functional logs are more useful for debugging an application when problems arise. For example:
◦ Sending an HTTP request to service endpoint (for example, a write property service call): endpoint=http://localhost:8720/some-service.
◦ Database selection for user information failed: database=drm_data-source, userId=213801478. [With exception stacktrace]
◦ Stack traces
Log Levels
The following log levels are supported:
• Trace — The most detailed logs. These logs are useful for debugging while you develop an application. Trace logs can provide fine-grained information to troubleshoot issues that are difficult to find.
• Debug — Logs used to help in debugging issues. These log messages contain information about what the code is doing at the moment and the values of any important variables.
• Info — Important system information, such as periodic tasks that are running and changes in the state of an application. In most cases, exceptions are not logged at this level.
• Warn — Unexpected exceptions that are acceptable or that can be worked around. Any problems that could become errors, if left unattended.
• Error —Issues that affect the usage or performance of the system.
Each level writes out any messages from a lower level in the hierarchy. For example, if the logging of the application is set to Trace, then Debug, Info, Warn, and Error levels are written to the log file. If the logging of the application is set to Warn, then only Warn and Error levels are written to the log.
 |
Logs are very useful for debugging and troubleshooting an issue. Setting the log level to Trace, and re-running the application may help you find a problem quickly.
|
Two services are provided that allow you to determine the current log level and to set the log level for the Connection Server:
• GetLogLevel
• SetLogLevel
To set the log level, you can use the Log Settings tab for the Connection Server in ThingWorx. You can also open the logback.xml file in a text editor, and add or edit the following lines:
<root level="info">
<appender-ref ref="LOG" />
</root>
<appender-ref ref="LOG" />
</root>
The valid values for level are "error", "warn", "debug", "info", "trace", and "off".
Separating Operational and Functional Logging in the logback.xml File
To help differentiate the operational and functional logs, all operational logs are tagged with the "operational" marker. This tagging allows you to do something special for operational logs.
By default, all logging information is combined into one file. To separate the operational logs from the functional logs, add the following appender information to the logback.xml file
<appender name="OPSLOG" class="ch.qos.logback.core.FileAppender">
<file>cxserver-ops.log</file>
<append>true</append>
<filter class="ch.qos.logback.core.filter.EvaluatorFilter">
<evaluator class="ch.qos.logback.classic.boolex.OnMarkerEvaluator">
<marker>operational</marker>
</evaluator>
<OnMismatch>DENY</OnMismatch>
</filter>
<encoder>
<pattern>$d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<file>cxserver-ops.log</file>
<append>true</append>
<filter class="ch.qos.logback.core.filter.EvaluatorFilter">
<evaluator class="ch.qos.logback.classic.boolex.OnMarkerEvaluator">
<marker>operational</marker>
</evaluator>
<OnMismatch>DENY</OnMismatch>
</filter>
<encoder>
<pattern>$d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
In addition, to send operational logs exclusively to a separate file, you need to exclude them from the functional log by adding the following clause inside the LOGS appender:
<filter class="ch.qos.logback.core.filter.EvaluatorFilter">
<evaluator class="ch.qos.logback.classic.boolex.OnMarkerEvaluator">
<marker>operational</marker>
</evaluator>
<OnMatch>DENY</OnMatch>
</filter>
<evaluator class="ch.qos.logback.classic.boolex.OnMarkerEvaluator">
<marker>operational</marker>
</evaluator>
<OnMatch>DENY</OnMatch>
</filter>
In addition, add an appender-ref for the operational log (OPSLOG):
<root level="info">
<appender-ref ref="LOG" />
<appender-ref ref="OPSLOG" />
</root>
<appender-ref ref="LOG" />
<appender-ref ref="OPSLOG" />
</root>
The first appender-ref specifies the functional log. The second one is for the operational log.
Resolving a Reference in the Configuration File to the Metrics Logger
The reference to the metrics logger in the configuration file for the Connection Server is resolved in the Logback.xml file by using the following appender:
<appender name="METRICS" class="ch.qos.logback.core.FileAppender">
<file>metrics.log</file>
<append>false</append>
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<logger name="metrics" additivity="false">
<appender-ref ref="METRICS" />
</logger
<file>metrics.log</file>
<append>false</append>
<encoder>
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
</appender>
<logger name="metrics" additivity="false">
<appender-ref ref="METRICS" />
</logger
Monitoring Information
The Connection Server can provide the following types of information for administrators through ThingWorx Composer (Connection Server mashup):
• System-level information about the computer where the Connection Server is running.
• The status of the computer where the Connection Server is running.
• The current log level. You can also change the log level of the Connection Server. Refer to for information about the log levels.
• Performance metrics for the Connection Server. For details about metrics, refer to the topic, Metrics
As of v.8.4.0 of the Connection Server, the logging for the underlying services that retrieve this information provides the following information:
• The request details are logged (endpoint ID, request ID)
• The success or failure of sending the response is logged.
The Connection Server does not support returning a list of entities that are currently bound through it. More specifically, the service returns the following message
Bound thing names are not provided by this Connection Server instance.
In addition, the service does not return messages from the log file of the Connection Server. It returns a message similar to the following:
ApplicaitonLog not provided via monitor interface. Please examine system log files.
Log Messages
To assist you in understanding the error and warning messages you may see, this section provides tables for these two types of operational log messages.
|
Logger Name
|
Message
|
Probable Cause
|
Action to Take
|
|---|---|---|---|
|
com.thingworx.connectionserver.metrics.MetricsReporterManager
|
Metrics are enabled but no reporters are configured.
|
The metrics are enabled in the configuration file, but no metrics reporters were configured. No metrics are reported.
|
Enable the metrics reporter in the configuration file and restart the Connection Server.
|
|
com.thingworx.connectionserver.metrics.MetricsReporterManager
|
Graphite metrics reporter enabled without service discovery but no endpoints are configured.
|
No explicit endpoint has been defined in the configuration file. No metrics are reported to Graphite.
|
Define the endpoint in the configuration file and restart the Connection Server.
|
|
com.thingworx.fabric.impl.AbstractManyPlatformWebSocketFabric
|
Platform still alive, so not removing: endpoint={}
|
The Connection Server received a notification that the ThingWorx Platform is no longer available, but the Connection Server is still connected to it.
|
Verify whether the ThingWorx Platform specified is still available.
|
|
Logger Name
|
Message
|
Probable Cause
|
Action to Take
|
|---|---|---|---|
|
com.thingworx.connectionserver.ConnectionServer
|
Unable to start Connection Server
|
The Connection Server encountered an error that prevented it from starting up. The exception appears after the log message.
|
Resolve the issue mentioned in the exception and restart the Connection Server.
|
|
com.thingworx.connectionserver.metrics.MetricsReporterManager
|
Unable to create stream for metrics console reporter, defaulting to standard-out: intended file={}
|
The file specified for the metrics console reporter could not be created.The exception appears after the log message. The Connection Server will continue functioning, but the metrics are written to standard out rather than the intended metrics file.The output file is specified in the configuration file at the following key: cx-server.metrics.reporters.console.outfile.
|
Fix the underlying issue specified in the exception, and restart the Connection Server. Possible causes are non-existent base directories and permissions issues.
|
|
com.thingworx.connectionserver.metrics.MetricsReporterManager
|
Unable to create directory for metrics CSV reporter, disabling reporter: directory={}
|
The directory specified for the metrics CSV reporter could not be created. The exception appears after the log message. The Connection Server continues to operate, but the CSV metrics reporter is disabled. If the CSV metrics reporter is the only configured reporter, no metrics information is available.
|
Fix the underlying issue specified in the exception and restart the Connection Server. Possible causes are base directories not existing and permissions issues.
|
|
com.thingworx.fabric.impl.AbstractManyPlatformWebSocketFabric
|
Failure while connecting to platform: endpoint={}
|
The attempt to connect to the ThingWorx Platform failed. The exception appears after the log message. The Connection Server will not start.
|
Resolve the issue mentioned in the exception and restart the Connection Server. Possible causes are:
• The wrong ThingWorx Platform endpoint (host/port) is specified in the configuration.
• The endpoint is not accessible over the network from the Connection Server.
• The ThingWorx Platform is not running.
|