Logger

This module provides a very simple but still powerful abstraction for logging policy, log messages, and log targets.

It distingushes between two kinds of log messages:

Debug Messages

The target audience of debug messages are people who know about the inner workings of the program or library--that is, developers. As such, they are not for public consumption and developers have complete freedom where to output debug messages, and what to put into them.

Report Messages

Reports are intended for people who use or operate the application. Their intention is usually to report on progress of the application, provide information on interaction with the outside world, and, most importantly, to communicate failures and the cause of the problem. Report messages must be formulated in such a way that they can be understood and acted upon by non-developers.

Report logs and debug logs can be send to different targets. A typical setup might forward reports to a remote logging service, while debug logs are only written to local files. Examples for report messages: which config file is being read, whether the configuration has been processed successfully, or that an external database server has been connected to. All reports messages are duplicated into the debug log as well. This means, that access to the debug log provides all the log messages of the application, in the order in which they were generated by the application.

There are a number of issues that are not addressed by this module. The application designer has to create his own policy regarding the following issues:

Logging by Functional Units

This module does not provide and infrastructure to groups log messages by applications, components, modules, classes, or functions. By using different log handles with distinct prefix strings, the developer can group messages by functional units.

Severity Levels

Beyond the basic distinction between report and debug messages, no further message classification is build in. The reason for this is that there is no " one size fits all" severity classification. And even there is an agreed baseline, it is very hard to use it consistently across applications, third party software, different developers, and so on.

Usage of Log Handles

There is no predisposition on how log handles are used in applications, libraries, or modules. In some situations, a single log handle stored in a global public variable may be sufficient. Other designs may prefer to use separate handles for functional units.

Import List

    IO
    Object
    Object
 
Class List
ChannelTarget
Handle
NullTarget
Target
Class Summary: ChannelTarget [Detail]
  +---Logger.Target
       |
       +--Logger.ChannelTarget
Inherited Fields

From Logger.Target:

          passOnDebug, passOnReport

Method Summary
INIT(BOOLEAN, BOOLEAN, ByteChannel)

          
Write(STRING, STRING)

          
Inherited Methods

From Logger.Target:

          INIT, Write

 
Class Summary: Handle [Detail]
  +--Logger.Handle
Field Summary
debugTarget-: Target

          
enableDebug-: BOOLEAN

          
enableReport-: BOOLEAN

          
prefix-: STRING

          
reportTarget-: Target

          
Method Summary
CloneTargets(STRING): Handle

          
Debug(STRING)

          
DebugBool(STRING, BOOLEAN)

          
DebugInt(STRING, LONGINT)

          
DebugLongReal(STRING, LONGREAL)

          
DebugObject(STRING, Object)

          
EnableDebug(BOOLEAN)

          
EnableReport(BOOLEAN)

          
INIT(Target, Target, STRING)

          
Report(STRING)

          Report messages are also duplicated into the debug log.
ReportBool(STRING, BOOLEAN)

          
ReportInt(STRING, LONGINT)

          
ReportLongReal(STRING, LONGREAL)

          
ReportObject(STRING, Object)

          
 
Class Summary: NullTarget [Detail]
  +---Logger.Target
       |
       +--Logger.NullTarget
Inherited Fields

From Logger.Target:

          passOnDebug, passOnReport

Method Summary
INIT()

          
Write(STRING, STRING)

          
Inherited Methods

From Logger.Target:

          INIT, Write

 
Class Summary: Target [Detail]
  +--Logger.Target
Field Summary
passOnDebug-: BOOLEAN

          Global flag to disable all debug output send to this target.
passOnReport-: BOOLEAN

          Global flag to disable all report output send to this target.
Method Summary
INIT(BOOLEAN, BOOLEAN)

          
Write(STRING, STRING)

          
 
Variable Summary
nullHandle-: Handle

          
nullTarget-: Target

          
stderrTarget-: Target

          
stdoutTarget-: Target

          
Constant Summary
timeStampFormat

          

Class Detail: ChannelTarget
Method Detail

INIT

PROCEDURE (lt: ChannelTarget) INIT(passOnReport: BOOLEAN; 
               passOnDebug: BOOLEAN; 
               ch: ByteChannel)

Redefines: INIT


Write

PROCEDURE (lt: ChannelTarget) Write(prefix: STRING; 
                msg: STRING)

Redefines: Write

 
Class Detail: Handle
Field Detail

debugTarget

FIELD debugTarget-: Target

enableDebug

FIELD enableDebug-: BOOLEAN

enableReport

FIELD enableReport-: BOOLEAN

prefix

FIELD prefix-: STRING

reportTarget

FIELD reportTarget-: Target
Method Detail

CloneTargets

PROCEDURE (lh: Handle) CloneTargets(newPrefix: STRING): Handle

Debug

PROCEDURE (lh: Handle) Debug(msg: STRING)

DebugBool

PROCEDURE (lh: Handle) DebugBool(msg: STRING; 
                    x: BOOLEAN)

DebugInt

PROCEDURE (lh: Handle) DebugInt(msg: STRING; 
                   x: LONGINT)

DebugLongReal

PROCEDURE (lh: Handle) DebugLongReal(msg: STRING; 
                        x: LONGREAL)

DebugObject

PROCEDURE (lh: Handle) DebugObject(msg: STRING; 
                      x: Object)

EnableDebug

PROCEDURE (lh: Handle) EnableDebug(enable: BOOLEAN)

EnableReport

PROCEDURE (lh: Handle) EnableReport(enable: BOOLEAN)

INIT

PROCEDURE (lh: Handle) INIT(reportTarget: Target; 
               debugTarget: Target; 
               prefix: STRING)

Report

PROCEDURE (lh: Handle) Report(msg: STRING)

Report messages are also duplicated into the debug log.


ReportBool

PROCEDURE (lh: Handle) ReportBool(msg: STRING; 
                     x: BOOLEAN)

ReportInt

PROCEDURE (lh: Handle) ReportInt(msg: STRING; 
                    x: LONGINT)

ReportLongReal

PROCEDURE (lh: Handle) ReportLongReal(msg: STRING; 
                         x: LONGREAL)

ReportObject

PROCEDURE (lh: Handle) ReportObject(msg: STRING; 
                       x: Object)
 
Class Detail: NullTarget
Method Detail

INIT

PROCEDURE (lt: NullTarget) INIT()

Redefines: INIT


Write

PROCEDURE (lt: NullTarget) Write(prefix: STRING; 
                msg: STRING)

Redefines: Write

 
Class Detail: Target
Field Detail

passOnDebug

FIELD passOnDebug-: BOOLEAN

Global flag to disable all debug output send to this target. The flag is tested by the Handle implementations.


passOnReport

FIELD passOnReport-: BOOLEAN

Global flag to disable all report output send to this target. The flag is tested by the Handle implementations.

Method Detail

INIT

PROCEDURE (lt: Target) INIT(passOnReport: BOOLEAN; 
               passOnDebug: BOOLEAN)

Write

PROCEDURE (lt: Target) Write(prefix: STRING; 
                msg: STRING)
 
Variable Detail

nullHandle

VAR nullHandle-: Handle

nullTarget

VAR nullTarget-: Target

stderrTarget

VAR stderrTarget-: Target

stdoutTarget

VAR stdoutTarget-: Target
Constant Detail

timeStampFormat

CONST timeStampFormat