Overview
The OPC UA Integration with Cumulocity allows connecting any OPC UA Server which can have various majority levels and address space sizes. In order to detect performance issues, compatibility problems and security issues fast. It is highly recommended to monitor software components in a productive environment. In that article, I will talk about the possibilities to set up logging at the OPC UA Gateway.
The OPC UA Gateway is written in Java using the Spring framework. This framework provides a wide variety of features for logging. The OPC UA Gateway is using the standard logback and I will show you how to run your OPC UA gateway with a log configuration with give you the right transparency for a common production environment.
The configuration should always be aligned with the environment you run the OPC UA gateway. In most cases, it runs close to the OPC UA Server, for example in a factory on an Edge device. The resources, like the storage is usually limited. This means you must be careful what log-level for each package you would configure to keep the files as small as possible but on the other hand the right information content in it. Also, the capability to rollover files once a certain condition and compress them, makes a lot of sense in such environments.
Example
Let’s assume the OPC UA gateway will run on an industrial PC and can only use max 50 MB for log files. However, for auditing reasons historic files must be buffered at least for three days. The post-processing tool impose size limit of 5 MB on the log files.
How should the logging configuration look like and how to start the gateway with it? Let’s start with a predefined a logback configuration xml. This contains a few very important configurations, which will be explained below. However, Logback has powerful and complex configuration possibilities, please visit the logback manual for more details: https://logback.qos.ch/manual/introduction.html
At this articel we will focus on FileAppender which writes files to the storage.
<?xml version="1.0" encoding="UTF-8"?>
<configuration scan="true" scanPeriod="30 seconds">
<include resource="org/springframework/boot/logging/logback/defaults.xml" />
<appender name="FILE"
class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>/${user.home}/.opcua/log/device-gateway.log</file>
<encoder>
<pattern>${FILE_LOG_PATTERN}</pattern>
</encoder>
<rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
<!-- rollover daily and archive file -->
<fileNamePattern>/${user.home}/.opcua/log/device-agent-%d{yyyy-MM-dd}.%i.zip</fileNamePattern>
<!-- each file should be at most 5MB, keep 3 days' worth of history capped at 50MB total size -->
<maxFileSize>5MB</maxFileSize>
<maxHistory>3</maxHistory>
<totalSizeCap>50MB</totalSizeCap>
</rollingPolicy>
</appender>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>${CONSOLE_LOG_PATTERN}</pattern>
<charset>utf8</charset>
</encoder>
</appender>
<logger name="com.cumulocity.opcua.client.gateway" level="INFO" />
<logger name="com.cumulocity" level="INFO" />
<root level="INFO">
<appender-ref ref="FILE" />
<appender-ref ref="STDOUT" />
</root>
</configuration>
Size- and Time-Base Rolling Policy
fileNamePattern
https://logback.qos.ch/manual/appenders.html#tbrpFileNamePattern
Automatic file compression is enabled if file option ends with .gz or .zip. It also defines the rollover period. In that case daily rollover. %d{yyyy-MM-dd}. As already mentioned, we also have configured . This means Logback will create a new archive file if maxFileSize is reached and adds a counter (%i) to the file.
maxHistory
https://logback.qos.ch/manual/appenders.html#tbrpMaxHistory
In the case of a daily rollover, the value means days.
totalSizeCap
https://logback.qos.ch/manual/appenders.html#tbrpTotalSizeCap
Controls the total size of all archive files. Oldest archives are deleted asynchronously.
Logger
Logback defines 5 log levels: TRACE , DEBUG , INFO , WARN , ERROR. This log levels you can define for the root logger and all additional loggers. In that example, it is currently set to INFO. For more diagnostic logging, both specific loggers can be set to DEBUG to get debug information as well for the specific context.
<logger name="com.cumulocity.opcua.client.gateway" level="DEBUG" />
<logger name="com.cumulocity" level="INFO" />
Starting with specific logging config
It is time to start your OPC UA Gateway with your logging config by using JVM -Dlogging.config. In the following example, the opcua-device-gateway-logging.xml is stored next to the jar file.
java -Dspring.profiles.active=default,test1 -Dlogging.config=opcua-device-gateway-logging.xml -jar opcua-device-gateway-1013.0.125.jar
After a while you will see the log directory will look like that:
Conclusion
Logging is very important, but the right configuration of the logger is essential to get the right insights. This article gives you a glimpse of the logback capabilities to setup logging for a specific environment.