audit(n) 1.1 "Logging / debugging module"
audit - Logging / debugging module
TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
COMMAND
OBJECT CONFIGURATION
EXAMPLES
SEE ALSO
KEYWORDS
COPYRIGHT
package require Tcl 8.4
package require audit::audit ?1.0?
This package provides audit storing and configuring capability.
Logs can be automatically (or manually) saved as well as readable
logs can also be created.
The audit information contains level, date stamp, textual data (the message),
stack trace, variable dumps and additional information.
Text log file only contains time stamp, level, stack trace size
and the actual message, while the audit file can store additional
information as well.
Audit can be set up to do dumps as bgerror so that error debugging
and automatic error reporting can be made easier. These logs can then be
examined and root cause can be found.
The information can be viewed using the audit browser.
The following audit levels are currently defined for level compatibility:
- Audit level 1 - error information
- Audit level 2 - warning information
- Audit level 3 - notice information
- Audit level 4 - debug information
- Audit level 5 - application logic
- Audit level 6 - major backend operations
- Audit level 7 - minor backend operations
- Audit level 8 - verbose operations
- Audit level 9 - stack trace
- audit::configure option value...
-
Configures audit using the options and values given to it.
The legal configuration options are described in section
OBJECT CONFIGURATION.
Unregisters a command from calling on each audit information being added.
- audit::audit type level message ?varlist? ?parameter1? ?value1? ?parameter2? ?value2? ?..?
-
Adds information to audit data and/or log.
Type can be any information that may suggest where
the information is coming from - for example module name,
procedure or OO class name. This information is visible
in both text logs and audit files.
Message is the textual message that represents what
is going on.
Varlist can supply one or move variables
(which should be visible in the context of function adding audit information)
that will be dumped as either variables or arrays.
Additional parameters can be supplied as multiple
parameters, that will also be added to audit information.
- audit::logroll
-
Roll log files. This should be scheduled daily at some regular hour.
- audit::addNotifier command ?priority?
-
Registsers a Tcl command that gets called for
each addition of information into the audit.
This can be used for live audit viewers.
- audit::removeNotifier command
-
Unregisters a command from calling on each audit information being added.
- audit::getlog ?maxlevel? ?regexpName? ?maxlength?
-
Returns a list of audit elements, where each element is a list with elements
- audit::saveAudit filename
-
Saves the current audit state to a file. Useful for custom bgerror handling
to send a bug report and/or dump all error traces.
| | {timestamp milliseconds type level message vars parameters stacktrace} |
Where timestamp is a stamp as clock seconds,
milliseconds is the return from clock seconds -milliseconds
(this information can be used for profiling purposes)
vars is a list of 0 or more series of three elements - varname-vartype-varvalue,
where vartype is either value or array.
parameters is a list of 0 or more series of three elements - paramname-paramvalue.
stacktrace is a list of each stack element, where each element is a list,
as returned from info level <level>.
Audit has the following configurable options:
- -limit integer
-
Limit on the number of audit information to keep.
This is used for async log files and audit files and for
memory conservation.
By default this is set to 20000.
- -level integer
-
Maximum level of messages to add to audits. It is recommended
to set this to value of 3 for production applications
and 9 for development applications.
By default this is set to 0 -
so logging is not done for any messages.
- -logfile filename
-
Filename of the file that should be used for storing text
log files.
If set to "", no file will be created or written to.
The format of the log files is as follows:
| | 06-04-01 18:30:00.0041 | bgerror | 1 | 3 | Background error: couldn't open socket: connection refused |
- -logfilecount integer
-
Count of previous log files to keep when doing audit::logroll.
By default this is set to 10.
- -emptylog boolean
-
Specifies whether the log files should be truncated if they
already exist. Setting it to false causes the typical behavior
similar to most applications that use log files.
This is only used when -synclog is set to true.
By default this is set to true - for compatibility reasons.
- -synclog boolean
-
If set to true, audit will append each line to the file
when it is added to audit. If set to false, the log file
will always be overwritten with current audit data and will be done
asynchronously after some time. This option prevents unrolled logs
from growing into infinity.
By default this is set to false - for compatibility reasons.
- -stderr stderr
-
Whether audit information should also be put into stderr. The format
is the same as in log files.
- -datafile filename
-
Name of the file which should store audit information for the application.
It is always written asynchronously after some time and is compressed
(uzing Trf or zlib).
If set to "", no file will be created or written to.
- -datafilecount integer
-
Count of previous audit files to keep when doing audit::logroll.
By default this is set to 0 so audits are not rolled at all.
| |
# small audit example
package require audit::audit
audit::configure -level 9 -logfile audit.txt -datafile audit.aud
# just log that we're initializing
audit::audit someType 3 "Initializing application"
set var1 1
set var2(2) 1234
# log an error + contents of variables var1 and var2
audit::audit someType 1 "Error message" {var1 var2}
# log an error + some other information (as name-value pairs)
if {1} {
audit::audit someType 1 "Cannot open file: $err" {} \
errorInfo $::errorInfo errorCode $::errorCode
}
|
audit_browser, audit_configgui
audit, log
Copyright © 2006 Wojciech Kocjan <wojciech.kocjan@dq.pl>