SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST |
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. |
IO Object Object
Class List | |
ChannelTarget | |
Handle | |
NullTarget | |
Target |
Class Summary: ChannelTarget [Detail] | |
+---Logger.Target | +--Logger.ChannelTarget | |
Inherited Fields | |
From Logger.Target: | |
Method Summary | |
INIT(BOOLEAN, BOOLEAN, ByteChannel) | |
Write(STRING, STRING) | |
Inherited Methods | |
From Logger.Target: |
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: | |
Method Summary | |
INIT() | |
Write(STRING, STRING) | |
Inherited Methods | |
From Logger.Target: |
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 |
PROCEDURE (lt: ChannelTarget) INIT(passOnReport: BOOLEAN; passOnDebug: BOOLEAN; ch: ByteChannel)
Redefines: INIT
PROCEDURE (lt: ChannelTarget) Write(prefix: STRING; msg: STRING)
Redefines: Write
Class Detail: Handle |
Field Detail |
FIELD debugTarget-: Target
FIELD enableDebug-: BOOLEAN
FIELD enableReport-: BOOLEAN
FIELD prefix-: STRING
FIELD reportTarget-: Target
Method Detail |
PROCEDURE (lh: Handle) CloneTargets(newPrefix: STRING): Handle
PROCEDURE (lh: Handle) Debug(msg: STRING)
PROCEDURE (lh: Handle) DebugBool(msg: STRING; x: BOOLEAN)
PROCEDURE (lh: Handle) DebugInt(msg: STRING; x: LONGINT)
PROCEDURE (lh: Handle) DebugLongReal(msg: STRING; x: LONGREAL)
PROCEDURE (lh: Handle) DebugObject(msg: STRING; x: Object)
PROCEDURE (lh: Handle) EnableDebug(enable: BOOLEAN)
PROCEDURE (lh: Handle) EnableReport(enable: BOOLEAN)
PROCEDURE (lh: Handle) INIT(reportTarget: Target; debugTarget: Target; prefix: STRING)
PROCEDURE (lh: Handle) Report(msg: STRING)
Report messages are also duplicated into the debug log.
PROCEDURE (lh: Handle) ReportBool(msg: STRING; x: BOOLEAN)
PROCEDURE (lh: Handle) ReportInt(msg: STRING; x: LONGINT)
PROCEDURE (lh: Handle) ReportLongReal(msg: STRING; x: LONGREAL)
PROCEDURE (lh: Handle) ReportObject(msg: STRING; x: Object)
Class Detail: NullTarget |
Method Detail |
PROCEDURE (lt: NullTarget) INIT()
Redefines: INIT
PROCEDURE (lt: NullTarget) Write(prefix: STRING; msg: STRING)
Redefines: Write
Class Detail: Target |
Field Detail |
FIELD passOnDebug-: BOOLEAN
Global flag to disable all debug output send to this target. The flag is tested by the Handle implementations.
FIELD passOnReport-: BOOLEAN
Global flag to disable all report output send to this target. The flag is tested by the Handle implementations.
Method Detail |
PROCEDURE (lt: Target) INIT(passOnReport: BOOLEAN; passOnDebug: BOOLEAN)
PROCEDURE (lt: Target) Write(prefix: STRING; msg: STRING)
Variable Detail |
VAR nullHandle-: Handle
VAR nullTarget-: Target
VAR stderrTarget-: Target
VAR stdoutTarget-: Target
Constant Detail |
CONST timeStampFormat