Table of Contents

LoggerBuffered

Namespace
ZAux
Implements

This Logger buffers log entries and this mechanism can also be used by external applications (i.e. a HMI) The buffer for this Logger is held externally and gets initialized during construction.

A single log message has the following properties

  • LogLevel: Severity of a message
  • Timestamp: Timestamp that contains information about when a message was logged
  • Message: String that contains the actual information that should be logged.

These properties can be easily handled by utilizing a predefined logging-method (i.e. Debug, Trace) or the generic method LogMessageRef. While the predefined logging-methods automatically fill most properties of a log message, the generic method give the most control by providing a parameter for every property of a log message.

LoggerNameDecorator allows to modify these properties to provide extra information to a log-entry. One possible application of this feature is to prefix the Message property. For example, a unit may prefix every message with its name by utilizing a LoggerNameDecorator such that log messages have the following format. For example if the logfile would be written in a file as of in the context of LoggerFile7FF this mechanism allows to change the logging behavior from

LogLevel |Date (mm-dd |Time (hh:ii:ss.(msec))|Message
DBG |04-09|18:14:44.713|step changed to bootBegin

to

LogLevel |Date (mm-dd |Time (hh:ii:ss.(msec))|Unitname|Message
DBG |04-09|18:14:44.713|Infrastructure|step changed to bootBegin

The Logger class allows to filter messages for a minimum severity level by setting MinimumLevel or MinimumLevelRef property. Logmessages with a Level that is smaller than the level set with this method are ignored.

FUNCTION_BLOCK LoggerBuffered IMPLEMENTS ZCore.ILogger, ZCore.ILoggerBase, ZCore.ILoggerImperativeApi, ZCore.ILoggerFluentApi

Constructor

FB_init

For the LoggerBuffered class the buffer has to be instantiated externally and then initialized during construction by giving the buffer size and a pointer to the first buffer entry; Also the head and tail pointer to index the log messages inside the buffer have to be instantiated externally.

Unfortunately the LoggerBuffered function block has no cyclic beahvior and therefore no parent is needed. Here the parent as first parameter is just for consistency that every Logger function block has its same construction and can easily be exchanged with another function block.

METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL,
 parent : ZCore.IManagedObject,
 bufferSize : DINT,
 dataBuffer : POINTER TO Message,
 indexOfFirstPtr : POINTER TO DINT,
 indexOfNextPtr : POINTER TO DINT) : BOOL

Inputs

bInitRetains BOOL

if TRUE, the retain variables are initialized (warm start / cold start)

bInCopyCode BOOL

if TRUE, the instance afterwards gets moved into the copy code (online change)

parent IManagedObject

Usually given as a interface to the ManagedObject that is the parent of this object, here for LoggerBuffered it is not used

bufferSize DINT

size of the buffer which holds the log-entries

dataBuffer POINTER TO Message

Pointer to the first entry of a data buffer which holds all the log entries

indexOfFirstPtr POINTER TO DINT

Pointer to head variable of ringbuffer, this one points to the last read entry-index

indexOfNextPtr POINTER TO DINT

Pointer to tail variable of ringbuffer, this one points to the next free entry-index

Returns

BOOL

Properties

MinimumLevel

Sets the threshold of logged messages. Logging messages, which have the same severity level or higher will be emitted handled by the logger (others are ignored). The default value for MinimumLevel, which is used when this method is not used to overwrite it, can be parametrized with a library parameter. The MinimumLevel, which is set with this property is for instance only, if the minimum loglevel should be controlled globally for all loggers used in an application, use MinimumLevelRef

Note

Calling this method will unlink the logger instance from the pointer that has been passed with SetLevelRef The Logger uses whatever method was called last.

PROPERTY MinimumLevel : ZCore.LogLevel

Property Value

LogLevel

MinimumLevelRef

Sets the threshold of logged messages to logLevelRef^. Since the passed value is a reference, it can be changed at any time externally and be shared over several loggers. Logging messages which have the same severity level or higher will be emitted handled by the logger (others are ignored). The default value for logLevel, which is used when this method is not used to overwrite it, can be parametrized with a library parameter.

Note

Calling this method will not effect the logLevel that has been set with MinimumLevel. The Logger uses whatever method was called last.

PROPERTY MinimumLevelRef : REFERENCE TO ZCore.LogLevel

Property Value

REFERENCE TO LogLevel

Methods

AtDebug

Initiates logging a message fluently with log-severity level Debug if the severity level applies.

logger.AtDebug().LogMessage('hello world');

A Debug message is less granular compared to the trace level, but it is more than you will need in everyday use. The debug log level should be used for information that may be needed for diagnosing issues and troubleshooting or when running an application in a test environment for the purpose of making sure everything is running correctly. For more information about this loglevel, see sematext.

METHOD AtDebug () : ZCore.ILoggerFluentAtLevel

Returns

ILoggerFluentAtLevel

AtError

Initiates logging a message fluently with log-severity level Error if the severity level applies.

logger.AtError().LogMessage('hello world');

The error level should be used when the application hits an issue preventing one or more functionalities from properly functioning. For instance, if a servo-motor can not reach its desired position or if a sudden pneumatic pressure drop occurs. For more information about this loglevel, see sematext.

METHOD AtError () : ZCore.ILoggerFluentAtLevel

Returns

ILoggerFluentAtLevel

AtFatal

Initiates logging a message fluently with log-severity level Fatal if the severity level applies.

logger.AtFatal().LogMessage('hello world');

The error level should be used when the application hits errors that stop the booting process or other hardward related issues (device that is disconnected while using, fieldbus interruptions, ...). For more information about this loglevel, see sematext.

METHOD AtFatal () : ZCore.ILoggerFluentAtLevel

Returns

ILoggerFluentAtLevel

AtInfo

Initiates logging a message fluently with log-severity level Info if the severity level applies.

logger.AtInfo().LogMessage('hello world');

Info is the standard log level and is indicating that something happened, i.e. the application entered a certain state For instance, an operator of your production system starts the automatic sequence and this can be logged as info if it was successfull or not. The information logged using the info log level should be purely informative and not looking into them on a regular basis shouldn’t result in missing any important information. For more information about this loglevel, see sematext.

METHOD AtInfo () : ZCore.ILoggerFluentAtLevel

Returns

ILoggerFluentAtLevel

AtTrace

Initiates logging a message fluently with log-severity level Trace if the severity level applies.

logger.AtTrace().LogMessage('hello world');

Trace is the most fine-grained information only used in rare cases where you need the full visibility of what is happening in your application and inside the third-party libraries that you use. You can expect the trace logging level to be very verbose. You can use it for example to annotate each step in a sequence or extra entries in different if branches. For more information about this loglevel, see sematext.

METHOD AtTrace () : ZCore.ILoggerFluentAtLevel

Returns

ILoggerFluentAtLevel

AtWarning

Initiates logging a message fluently with log-severity level Warning if the severity level applies.

logger.AtWarning().LogMessage('hello world');

A warning indicates that something unexpected happened in the application, a problem, or a situation that might disturb one of the processes. But that doesn’t mean that the application failed or the production system had to be stopped. The warning log level should be used in situations that are unexpected, but the code can continue the work. For example, an electric motor (servo) has two levels for overheating. A warning temperature and a temperature were it is very likely that it will soon get broken. For more information about this loglevel, see sematext.

METHOD AtWarning () : ZCore.ILoggerFluentAtLevel

Returns

ILoggerFluentAtLevel

Debug

Logs a message to the logger with log-severity level Debug if the severity level applies.

A Debug message is less granular compared to the trace level, but it is more than you will need in everyday use. The debug log level should be used for information that may be needed for diagnosing issues and troubleshooting or when running an application in a test environment for the purpose of making sure everything is running correctly. For more information about this loglevel, see sematext.

METHOD Debug (
 text : ZCore.ZString)

Inputs

text ZString

Desired debug message as ASCII text

Error

Logs a message to the logger with log-severity level Error if the severity level applies.

The error level should be used when the application hits an issue preventing one or more functionalities from properly functioning. For instance, if a servo-motor can not reach its desired position or if a sudden pneumatic pressure drop occurs. For more information about this loglevel, see sematext.

METHOD Error (
 text : ZCore.ZString)

Inputs

text ZString

Desired error message as ASCII text

Fatal

Logs a message to the logger with log-severity level Fatal if the severity level applies.

The error level should be used when the application hits errors that stop the booting process or other hardward related issues (device that is disconnected while using, fieldbus interruptions, ...). For more information about this loglevel, see sematext.

METHOD Fatal (
 text : ZCore.ZString)

Inputs

text ZString

Desired warning message as ASCII text

Info

Logs a message to the logger with log-severity level Info if the severity level applies.

Info is the standard log level and is indicating that something happened, i.e. the application entered a certain state For instance, an operator of your production system starts the automatic sequence and this can be logged as info if it was successfull or not. The information logged using the info log level should be purely informative and not looking into them on a regular basis shouldn’t result in missing any important information. For more information about this loglevel, see sematext.

METHOD Info (
 text : ZCore.ZString)

Inputs

text ZString

Desired information message as ASCII text

LogMessageRef

This method allows to set every single property of a log message manually. Usually this method should not be used in an application, use one of the specialized methods instead (i.e. Debug, Trace)

The timestamp property is overwritten by the actual timestamp if timestamp=0.

METHOD LogMessageRef (
 timestamp : ULINT,
 text : REFERENCE TO ZCore.ZString,
 logLevel : ZCore.LogLevel)

Inputs

timestamp ULINT

Unix timestamp of the running PLC target in 1ms resolution

text REFERENCE TO ZString

Desired information message as ASCII text

logLevel LogLevel

LogLevel based on Apache log4j

SetDateTime

Sets a Zeugwerk compatible DateTime function block that is used by the predefined logging-methods to automatically fill the timestamp property of a log message. If intrf=0 the timestamp of every message that is logged is 0.

METHOD SetDateTime (
 intrf : ZCore.IDateTime)

Inputs

intrf IDateTime

Interface to an instantiated Zeugwerk Framework compatible DateTime function block

Trace

Logs a message to the logger with log-severity level Trace if the severity level applies.

Trace is the most fine-grained information only used in rare cases where you need the full visibility of what is happening in your application and inside the third-party libraries that you use. You can expect the trace logging level to be very verbose. You can use it for example to annotate each step in a sequence or extra entries in different if branches. For more information about this loglevel, see sematext.

METHOD Trace (
 text : ZCore.ZString)

Inputs

text ZString

Desired trace message as ASCII text

Warning

Logs a message to the logger with log-severity level Warning if the severity level applies.

A warning indicates that something unexpected happened in the application, a problem, or a situation that might disturb one of the processes. But that doesn’t mean that the application failed or the production system had to be stopped. The warning log level should be used in situations that are unexpected, but the code can continue the work. For example, an electric motor (servo) has two levels for overheating. A warning temperature and a temperature were it is very likely that it will soon get broken. For more information about this loglevel, see sematext.

METHOD Warning (
 text : ZCore.ZString)

Inputs

text ZString

Desired warning message as ASCII text