Introdução
TpSCADALogger reúne o que acontece dentro do PascalSCADA — comunicação, conexões, threads de scan, tags, eventos disparados, segurança, banco de dados — e manda cada mensagem para a tela, para um arquivo, para um evento ou para lugar nenhum, conforme uma lista de regras. Uma regra escolhe as mensagens pela fonte (o nome do componente), pela classe, pela categoria e pelo nível. Assim você decide, por exemplo, que o tráfego de uma porta Modbus vai para um arquivo só dela, que os avisos do driver S7 vão para a tela e que todo erro também dispara um evento.
TpSCADALogMemo é o destino de tela: um memo somente leitura que mostra as linhas que as regras mandam para a tela.
Os dois ficam na paleta PascalSCADA Utils. O TpSCADALogger está no pacote pascalscada_common (sem LCL: funciona também em serviços e programas de console); o TpSCADALogMemo está no pascalscada_hmi.
Como funciona
Todas as partes do framework publicam suas mensagens num único hub global. Cada TpSCADALogger ativo recebe uma cópia e a passa pelas suas regras. Pode haver vários loggers no mesmo programa; cada um recebe todas as mensagens.
O log não custa nada enquanto ninguém escuta: antes de montar uma mensagem (formatar um texto, converter um frame em hexadecimal) o código pergunta ao hub se alguma regra ativa quer aquela categoria e nível. Publicar só copia a mensagem para a fila do logger; arquivos, tela e evento são tratados pela thread do próprio logger, em lotes, e uma thread de comunicação nunca espera pelo disco ou pela tela. A tela e o evento chegam na thread principal.
Níveis e categorias
| Nível | Uso |
|---|---|
llTrace |
Tudo, inclusive os bytes de cada frame. Muitos dados. |
llDebug |
Detalhes úteis para entender um problema. |
llInfo |
Eventos normais: conectou, desconectou, iniciou. |
llWarning |
Algo deu errado e foi recuperado (timeout, reconexão). |
llError |
Algo falhou. |
| Categoria | Mensagens sobre |
|---|---|
lcComm |
bytes enviados e recebidos por uma porta |
lcConnection |
abertura, fechamento, reconexão, timeouts |
lcProtocol |
frames e requisições de um driver de protocolo |
lcScan |
threads de scan e de atualização, filas |
lcTag |
leituras, escritas e valores de tags |
lcEvent |
eventos disparados |
lcThread |
threads iniciando e terminando |
lcSecurity |
login, logout, autorização |
lcDatabase |
a camada de banco de dados |
lcHMI |
os controles visuais |
lcUser |
mensagens da sua aplicação |
Propriedades do TpSCADALogger
| Propriedade | Descrição |
|---|---|
Active |
Liga e desliga o logger (padrão True). Em tempo de projeto ele nunca roda. |
Rules |
As regras de roteamento, avaliadas em ordem (veja abaixo). |
Display |
O destino de tela: um TpSCADALogMemo ou qualquer componente que implemente IpSCADALogDisplay. O Object Inspector lista só esses. |
LineFormat |
O formato da linha. Marcadores: %time%, %date%, %level%, %category%, %thread% (main, T1, T2… na ordem em que as threads publicam pela primeira vez), %threadid% (o id do sistema), %source%, %class%, %msg%, %data% (os bytes em hexadecimal, vazio quando não há). Vazio volta ao padrão. |
OnLog |
Evento chamado, na thread principal, para cada mensagem que uma regra manda para ltEvent. Recebe os campos da mensagem (Entry) e a linha formatada (Line). |
MaxFileSize |
Tamanho máximo de um arquivo de log em bytes; acima dele o arquivo é renomeado para .1, .2… (0 = sem limite). |
MaxRotatedFiles |
Quantos arquivos renomeados são mantidos (padrão 5). |
FileIdleCloseMs |
Um arquivo que não recebe nada por esse tempo é fechado e reaberto quando preciso (padrão 10 s). |
FlushIntervalMs |
De quanto em quanto tempo a thread do logger grava o que está na fila (padrão 200 ms). |
MaxQueue |
Mensagens que a fila comporta; acima disso as novas são descartadas e depois sai uma linha N log messages dropped. Dropped conta quantas. |
Flush(TimeoutMs) espera até que tudo o que foi publicado antes da chamada esteja gravado e, na thread principal, mostrado. PSLogFlushAll faz o mesmo para todos os loggers.
A linha padrão fica assim:
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
Regras
Uma mensagem casa com uma regra quando todas estas condições valem:
| Propriedade | Casa quando |
|---|---|
Enabled |
a regra está habilitada. |
MinLevel |
o nível da mensagem é este ou maior (padrão llInfo). |
Categories |
a categoria da mensagem está no conjunto (padrão: todas). |
SourceMask |
a fonte casa com a máscara. A fonte é o caminho do componente, como Form1.ModBusTCP1. Aceita * e ?, não diferencia maiúsculas e aceita várias máscaras separadas por ;. Vazio significa tudo. |
ClassMask |
a classe da fonte ou um ancestral dela casa com a máscara — TProtocolDriver casa com todos os drivers. Mesma sintaxe da SourceMask. |
E então:
| Propriedade | Efeito |
|---|---|
Targets |
Para onde vai: ltScreen, ltFile, ltEvent, em qualquer combinação. Vazio descarta a mensagem. |
FileName |
O arquivo de ltFile. Aceita %date%, %source%, %class%, %category% e %level%, então uma regra pode gravar um arquivo por dia, por fonte ou por classe. Um caminho relativo é relativo à pasta do executável; pastas que faltam são criadas. |
StopProcessing |
Quando a regra casa, as regras seguintes não são avaliadas. Com Targets vazio vira uma exclusão. |
Quando várias regras casam, a mensagem vai para todos os destinos delas; duas regras no mesmo arquivo gravam a linha uma vez só.
Exemplos:
| Objetivo | Regra |
|---|---|
| Erros e avisos de tudo na tela | MinLevel = llWarning, Targets = [ltScreen] |
| Tráfego de cada porta num arquivo diário próprio | Categories = [lcComm], MinLevel = llTrace, Targets = [ltFile], FileName = logs/%source%-%date%.log |
| Tudo do driver S7CommPlus num arquivo | ClassMask = TS7CommPlusDriver, MinLevel = llDebug, Targets = [ltFile], FileName = logs/s7plus.log |
| Ignorar um componente barulhento | primeira regra: SourceMask = Form1.Debug*, Targets = [], StopProcessing = True |
TpSCADALogMemo
Um memo preparado para logs: somente leitura, sem quebra de linha, com barras de rolagem. Ligue-o no Display do logger.
| Propriedade | Descrição |
|---|---|
MaxLines |
Linhas mantidas; as mais antigas saem primeiro (padrão 1000, 0 = sem limite). |
AutoScroll |
Mantém a última linha visível quando chegam linhas novas (padrão True). Desligue para ler com calma. |
Uma fonte monoespaçada deixa as colunas alinhadas. Para mostrar o log em outro lugar (uma lista, uma grade, uma barra de status) use o evento OnLog, ou escreva um componente que implemente IpSCADALogDisplay (um método, AddLogLines(Lines: TStrings), chamado na thread principal).
O que o PascalSCADA publica
| Quem | Categoria / nível | Mensagens |
|---|---|---|
| toda porta de comunicação | lcComm / llTrace |
TX 12/12 iorOK, RX 10/10 iorOK, com os bytes como dados, na ordem em que a porta os fez. |
lcComm / llWarning |
read failed: iorTimeOut, write failed: … |
|
lcConnection / llInfo |
port started, port stopped |
|
lcConnection / llError |
open failed, close failed, com o erro do sistema operacional |
|
lcConnection / llWarning |
connection lost |
|
TTCP_UDPPort |
lcConnection / llInfo |
connected, reconnecting (llDebug: closing the socket) |
TS7CommPlusDriver |
lcProtocol / llDebug |
as mesmas mensagens do OnDebug (inclusive as da conexão), com o driver como fonte |
TOPCUADriver |
lcProtocol / o nível da mensagem |
as mesmas mensagens do OnLog; o LogLevel do driver continua decidindo o que a biblioteca informa |
| todo driver de protocolo | lcThread / llDebug |
TScanThread started, TScanUpdate finished… (llError quando uma exceção para uma thread) |
lcScan / llError |
uma exceção durante o scan (scan read raised …, tag update raised …) — antes elas eram engolidas em silêncio |
|
| todo tag | lcTag / llDebug |
scan write requested: [12.5], scan write ok (sync para escritas síncronas) |
lcTag / llWarning |
scan write failed: ioTimeOut; read failed: ioCommError uma vez quando a leitura passa a falhar, e reading again (llInfo) quando volta |
|
lcTag / llTrace |
toda leitura (scan read ioOk) e toda mudança de valor (value changed: 12.5 (raw 125)) |
|
lcEvent / llTrace |
cada evento atribuído e disparado: OnValueChange, OnValueChangeFirst, OnAsyncValueChange, OnReadOk, OnReadFail, OnWriteOk, OnWriteFail, OnUpdate |
|
lcEvent / llError |
uma exceção levantada enquanto o tag era atualizado — normalmente no seu OnValueChange. Os outros tags do lote continuam sendo atualizados. |
|
| gerenciadores de usuário | lcSecurity / llInfo |
login: fabio (password) ou (chip card), logout: fabio, access to "valves" granted to maria (password) (llDebug quando o usuário logado já tem a permissão) |
lcSecurity / llWarning |
login failed: fabio (password), login blocked for 30000 ms after 3 failures, access to "valves" denied to maria. A senha nunca vai para o log. |
|
| controles de HMI que escrevem num tag | lcHMI / llInfo |
wrote 1 to Form1.Valve1 (user fabio), com o controle como fonte — uma trilha de auditoria das ações do operador (THMIEdit, THMICheckBox, THMIButton, THMIRadioGroup, THMITrackBar, THMIComboBox, THMIUpDown, THMIScrollBar) |
lcHMI / llWarning |
write of 10 to Form1.Valve1 refused (user fabio): <motivo>, ex.: fora dos limites do tag |
|
THMIDBConnection |
lcDatabase / llInfo |
connected (postgresql host/db), disconnected (llError quando falha) |
lcDatabase / llDebug |
SQL ok (12 rows): select …, transaction committed (3 statements) |
|
lcDatabase / llWarning, llError |
SQL refused (ReadOnly): …, transaction rolled back …, SQL failed: <erro> seguido do SQL, commit/rollback failed |
As mensagens de conexão trazem a porta entre parênteses: (192.168.0.10:502 TCP), (COM1 19200 8N1). O LogIOActions/LogFile das portas e o OnDebug/OnLog dos drivers continuam funcionando como antes. As threads de um driver começam antes de ele receber o nome (o form ajusta as propriedades depois), então as mensagens de started mostram a classe, como em Form1.<TModBusTCPDriver>; tudo o que vem depois mostra o nome. lcTag e lcEvent em llTrace geram uma linha por tag a cada scan: restrinja essas regras com SourceMask. lcDatabase em llDebug grava o texto do SQL, valores inclusive: mantenha isso fora de arquivos que outras pessoas leem se os seus comandos levam dados sensíveis.
Publicando do seu código
uses pscadalog; PSLog(Self, lcUser, llInfo, 'lote iniciado'); PSLogFmt(Self, lcUser, llWarning, 'tanque %d acima de %f', [TankNo, Level]); //monte mensagens caras só quando alguém quiser if PSLogWants(lcComm, llTrace) then PSLog(Self, lcComm, llTrace, 'frame', FrameBytes);
Self (o remetente) vira a fonte e a classe da mensagem; pode ser nil. PSLog pode ser chamado de qualquer thread.
Programas sem a LCL
Arquivos funcionam em qualquer programa. A tela e o evento OnLog chegam na thread principal por TThread.Queue, então um programa de console ou serviço precisa chamar CheckSynchronize de tempos em tempos (uma aplicação LCL já faz isso).
Exemplos relacionados
examples/laz_pscadalogger— um logger com três regras (tela, um arquivo por categoria e dia, um evento que conta os erros), umTpSCADALogMemo, um botão para publicar mensagens de qualquer nível e categoria e uma rajada de quatro threads publicando ao mesmo tempo.
