Introduction

TpSCADALogger collects what happens inside PascalSCADA — communication, connections, scan threads, tags, events fired, security, database — and sends each message to the screen, to a file, to an event, or nowhere, according to a list of rules. A rule picks messages by source (the component name), class, category and level, so you decide, for example, that the traffic of one Modbus port goes to its own file, the S7 driver warnings go to the screen and every error also fires an event.

TpSCADALogMemo is the screen target: a read-only memo that shows the lines the rules send to the screen.

Both live on the PascalSCADA Utils palette. TpSCADALogger is in the pascalscada_common package (no LCL: it also works in services and console programs); TpSCADALogMemo is in pascalscada_hmi.

How it works

Every part of the framework posts its messages to a single, global hub. Each active TpSCADALogger gets a copy and routes it through its rules. Several loggers may exist in the same program; each one gets every message.

Logging costs nothing while nobody listens: before building a message (formatting a text, dumping a frame as hex) the code asks the hub whether some active rule wants that category and level. Posting only copies the message into the logger’s queue; the files, the screen and the event are handled by the logger’s own thread, in batches, so a communication thread never waits for the disk or the screen. Screen and event are delivered in the main thread.

Levels and categories
Level Use
llTrace Everything, including the bytes of each frame. A lot of data.
llDebug Details useful to understand a problem.
llInfo Normal events: connected, disconnected, started.
llWarning Something went wrong and was recovered (timeout, reconnection).
llError Something failed.
Category Messages about
lcComm bytes sent and received by a port
lcConnection opening, closing, reconnecting, timeouts
lcProtocol frames and requests of a protocol driver
lcScan scan and update threads, queues
lcTag tag reads, writes and values
lcEvent events fired
lcThread threads starting and stopping
lcSecurity login, logout, authorization
lcDatabase the database layer
lcHMI the visual controls
lcUser messages of your application
TpSCADALogger properties
Property Description
Active Turns the logger on and off (default True). At design time it never runs.
Rules The routing rules, evaluated in order (see below).
Display The screen target: a TpSCADALogMemo or any component that implements IpSCADALogDisplay. The Object Inspector lists only those.
LineFormat How a line looks. Tokens: %time%, %date%, %level%, %category%, %thread% (main, T1, T2… in the order the threads first post), %threadid% (the system id), %source%, %class%, %msg%, %data% (the payload in hex, empty when there is none). Empty restores the default.
OnLog Event fired, in the main thread, for each message a rule sends to ltEvent. Gets the message fields (Entry) and the formatted Line.
MaxFileSize Size limit of a log file in bytes; over it the file is renamed to .1, .2… (0 = no limit).
MaxRotatedFiles How many renamed files are kept (default 5).
FileIdleCloseMs A file that got nothing for this long is closed and reopened when needed (default 10 s).
FlushIntervalMs How often the logger’s thread writes what is queued (default 200 ms).
MaxQueue Messages the queue holds; beyond it new messages are dropped and a line N log messages dropped is logged later. Dropped counts them.

Flush(TimeoutMs) waits until everything posted before the call has been written and, in the main thread, shown. PSLogFlushAll does the same for every logger.

The default line looks like this:

2026-11-17 14:03:22.417 [WARN ] [connection] T2 Form1.ModBusTCP1 (TModBusTCPDriver): timeout, reconnecting
2026-11-17 14:03:22.419 [TRACE] [comm] T2 Form1.TCP_UDPPort1 (TTCP_UDPPort): TX | 00 01 00 00 00 06 01 03 00 00 00 0A
Rules

A message matches a rule when all of these hold:

Property Matches when
Enabled the rule is enabled.
MinLevel the message level is this one or higher (default llInfo).
Categories the message category is in the set (default: all).
SourceMask the source matches the mask. The source is the component path, like Form1.ModBusTCP1. Accepts * and ?, ignores case, and takes several masks separated by ;. Empty means everything.
ClassMask the class of the source or one of its ancestors matches the mask — TProtocolDriver matches every driver. Same syntax as SourceMask.

And then:

Property Effect
Targets Where it goes: ltScreen, ltFile, ltEvent, any combination. Empty drops the message.
FileName The file for ltFile. Accepts %date%, %source%, %class%, %category% and %level%, so one rule can write one file per day, per source or per class. A relative path is relative to the executable’s folder; missing folders are created.
StopProcessing When the rule matches, the following rules are not evaluated. With empty Targets it makes an exclusion.

When several rules match, the message goes to all their targets; two rules on the same file write the line once.

Examples:

Goal Rule
Errors and warnings of everything on the screen MinLevel = llWarning, Targets = [ltScreen]
Traffic of each port in its own daily file Categories = [lcComm], MinLevel = llTrace, Targets = [ltFile], FileName = logs/%source%-%date%.log
Everything from the S7CommPlus driver in one file ClassMask = TS7CommPlusDriver, MinLevel = llDebug, Targets = [ltFile], FileName = logs/s7plus.log
Ignore one noisy component first rule: SourceMask = Form1.Debug*, Targets = [], StopProcessing = True
TpSCADALogMemo

A memo set up for logs: read-only, no word wrap, scroll bars. Link it to the logger’s Display.

Property Description
MaxLines Lines kept; the oldest go first (default 1000, 0 = no limit).
AutoScroll Keeps the last line in view when new lines come (default True). Turn it off to read calmly.

A monospaced font keeps the columns aligned. To show the log somewhere else (a list, a grid, a status bar) use the OnLog event, or write a component that implements IpSCADALogDisplay (one method, AddLogLines(Lines: TStrings), called in the main thread).

What PascalSCADA posts
Who Category / level Messages
every communication port lcComm / llTrace TX 12/12 iorOK, RX 10/10 iorOK, with the bytes as payload, in the order the port did them.
lcComm / llWarning read failed: iorTimeOut, write failed: …
lcConnection / llInfo port started, port stopped
lcConnection / llError open failed, close failed, with the operating system error
lcConnection / llWarning connection lost
TTCP_UDPPort lcConnection / llInfo connected, reconnecting (llDebug: closing the socket)
TS7CommPlusDriver lcProtocol / llDebug the same messages as OnDebug (its connection’s included), with the driver as the source
TOPCUADriver lcProtocol / the message’s level the same messages as OnLog; the driver’s LogLevel still decides what the library reports
every protocol driver lcThread / llDebug TScanThread started, TScanUpdate finished… (llError when an exception stops a thread)
lcScan / llError an exception during the scan (scan read raised …, tag update raised …) — these used to be silently swallowed
every tag lcTag / llDebug scan write requested: [12.5], scan write ok (sync for synchronous writes)
lcTag / llWarning scan write failed: ioTimeOut; read failed: ioCommError once when reading starts failing, and reading again (llInfo) when it comes back
lcTag / llTrace every read (scan read ioOk) and every value change (value changed: 12.5 (raw 125))
lcEvent / llTrace each event assigned and fired: OnValueChange, OnValueChangeFirst, OnAsyncValueChange, OnReadOk, OnReadFail, OnWriteOk, OnWriteFail, OnUpdate
lcEvent / llError an exception raised while the tag was being updated — usually in your OnValueChange. The other tags of the batch are still updated.
user managers lcSecurity / llInfo login: fabio (password) or (chip card), logout: fabio, access to "valves" granted to maria (password) (llDebug when the logged user already has it)
lcSecurity / llWarning login failed: fabio (password), login blocked for 30000 ms after 3 failures, access to "valves" denied to maria. Passwords are never logged.
HMI controls that write to a tag lcHMI / llInfo wrote 1 to Form1.Valve1 (user fabio), with the control as the source — an audit trail of the operator’s actions (THMIEdit, THMICheckBox, THMIButton, THMIRadioGroup, THMITrackBar, THMIComboBox, THMIUpDown, THMIScrollBar)
lcHMI / llWarning write of 10 to Form1.Valve1 refused (user fabio): <reason>, e.g. out of the tag limits
THMIDBConnection lcDatabase / llInfo connected (postgresql host/db), disconnected (llError when it fails)
lcDatabase / llDebug SQL ok (12 rows): select …, transaction committed (3 statements)
lcDatabase / llWarning, llError SQL refused (ReadOnly): …, transaction rolled back …, SQL failed: <error> followed by the SQL, commit/rollback failed

Connection messages carry the port in parentheses: (192.168.0.10:502 TCP), (COM1 19200 8N1). The ports’ LogIOActions/LogFile and the drivers’ OnDebug/OnLog keep working as before. A driver’s threads start before the driver gets its name (the form sets the properties afterwards), so their started messages show the class, as in Form1.<TModBusTCPDriver>; everything after that shows the name. lcTag and lcEvent at llTrace produce a line per tag per scan: narrow those rules with SourceMask. lcDatabase at llDebug writes the SQL text, values included: keep it out of files other people read if your statements carry sensitive data.

Logging from your code
uses pscadalog;

PSLog(Self, lcUser, llInfo, &#039;batch started&#039;);
PSLogFmt(Self, lcUser, llWarning, &#039;tank %d above %f&#039;, [TankNo, Level]);

//build expensive messages only when someone wants them
if PSLogWants(lcComm, llTrace) then
  PSLog(Self, lcComm, llTrace, &#039;frame&#039;, FrameBytes);

Self (the sender) becomes the source and the class of the message; it may be nil. PSLog may be called from any thread.

Programs without the LCL

Files work in any program. The screen and the OnLog event reach the main thread through TThread.Queue, so a console program or service must call CheckSynchronize from time to time (an LCL application already does it).

Related examples
  • examples/laz_pscadalogger — a logger with three rules (screen, one file per category and day, an event counting the errors), a TpSCADALogMemo, a button to post messages of any level and category and a burst of four threads posting at the same time.