ns_log - Global server error log
The running NaviServer process opens a single log file into which all Notice, Error etc. messages are logged, whether originating from the server itself or form Tcl scripts and ADP pages.
The built-in set of severity levels can be extended. Logging can be enabled/disabled at run-time per-severity level. Custom filters can be added to process log messages.
Write a message to the error log file if the given severity-level is enabled (see ns_logctl). The message arguments are concatenated with connecting spaces. Note that this only queues messages for the log and does not actually guarantee that the message is immediately written to the log. The server can be instructed to queue messages in the cache via ns_logctl hold.
The following are the predefined values of severity-level.
Something interesting occurred. A notice shows typically a state change, start/end of some jobs, etc. This level can be as well used of temporary debugging, but such messages should be removed after some time.
Something that could mean something bad occurred. A warning indicates an unexpected situation, which requires attention of a developer and a corrective measure in the not-to-distant future. Usage of deprecated code or code using not following the engineering guidelines are of such type.
Something bad occurred. An error is a malfunction, that must be investigated by a developer. An error is an unhandled exception. The error.log file should be free of errors.
Something extremely bad occurred. The server will shut down after logging this message.
Something occurred that implies that there is a bug in the code. This condition could never happen when the code is behaving correctly.
General debugging.
Mirror access log entries in system log.
Debugging for the nscgi module.
Debugging for ns_connchan interactions.
Debugging for driver (low-level network IO).
Debugging for nsproxy module.
Debugging for request live cycle.
Debugging for SQL (nsdb module).
Debugging for task interface (e.g. ns_http).
Debugging for ns_urlspace interactions.
This logging level is typically just activated during development to introspect the behavior of new code. Such logging statements are typically removed once development has reached a stable point.
Returns a count of buffered messages for the current thread. The message buffering can be turned on subcommand hold.
Return all buffered log messages, removing them from the buffer without writing them to the log file. Write buffered log messages from the current thread to the log file. Do not disable buffering enabled by hold.
Buffer log messages originating in the current thread indefinitely. Log messages are no longer written directly to the server log. Use the subcommand release to disable buffering.
Return a copy of any buffered log messages for the current thread.
Write buffered log messages from the current thread to the log file and disable buffering. Future log messages will not be buffered.
Return a list of available severity-levels. The result includes the 7 predefined levels and those created with ns_logctl or via C code.
Return true if the given severity-level is enabled, false if it is disabled. If bool is given it enables/disables the given severity-level for all future log messages, server-wide. The options -color and -intensity can be used to set the coloring when the logfile is colorized. The color can be black, red, green, yellow, blue, magenta, cyan, gray, or default. Intensity can be normal or bright. The logfile colorization can be controlled by setting logcolorize in section ns/parameters of the configuration file.
If severity-level does not already exist and more arguments arg given, then the new severity is created. Future calls to ns_log may use new severity-level.
Return statistics from calls to ns_log by severity-level.
Discard this thread's buffered messages, leaving count untouched.
Register a log filter script with the given script-args where script should have the signature: script severity timestamp message ?script-args ...?. A handle will be returned which can be used to unregister the filter script.
Unregister the previously registered log filter script identified by handle.
Roll the server error log. The behavior is independent of the configuration parameter logroll. See ns_rollfile for details of log rolling.
The error log is configured globally for the whole server process.
ns_section ns/parameters ns_param ...
The following are valid configuration parameters:
If true, log entries will be colorized using ANSI color codes Default: false.
If true messages of severity-level Debug are enabled. Default: false.
If true, messages of severity-level Dev are enabled. Default: false.
If true, an extra newline is added to each log entry. Default: false.
The number of old error log files to keep around if log rolling is enabled. Default: 10.
If true, messages of severity-level Notice are enabled. Default: true.
When logcolorize is true, provide a color for the timestamp prefix. Possible values are: black red green yellow blue magenta cyan gray default. Default: green.
When logcolorize is true, provide the intensity for the timestamp prefix. Possible values are: normal bright. Default: normal.
If true, the log file will be rolled when the server receives a SIGHUP signal. Default: true.
When specified, use a timestamp based logroll format based on the specified time format (e.g. %Y-%m-%d). The timestamp is appended to the name. When within the granularity two log files are generated these are numbered.
Path to error log file. If the path is not fully qualified it is assumed to be relative to the server home directory ([ns_info home]). All the components of the path must exist. The server will fail to start if the log file cannot be opened. Default: logs/nsd.log
If true, log entries will have seconds timestamps. Default: true.
If true, log entries will have thread ids included. Default: true.
If true, log entries will have timestamps with microsecond (usec) resolution. Default: false.
If true, show time difference since last log entry with microsecond (usec) resolution. This option is useful for determine latencies with minimal effort. Default: false.
The example below is a snippet taken from sample-config.tcl, which is included in the NaviServer distribution.
ns_section ns/parameters {
# ...
# Provide name for main server log file:
ns_param serverlog ${homedir}/logs/error.log
#
# Configuration of serverlog
#
# Rolling of logfile:
ns_param logroll on
ns_param logmaxbackup 100 ;# (default: 10)
ns_param logrollfmt %Y-%m-%d ;# timestamp format appended to serverlog filename when rolled
#
# Format of log entries:
ns_param logusec true ;# add timestamps in microsecond (usec) resolution (default: false)
ns_param logusecdiff true ;# add timestamp diffs since in microsecond (usec) resolution (default: false)
ns_param logcolorize true ;# colorize log file with ANSI colors (default: false)
ns_param logprefixcolor green ;# black, red, green, yellow, blue, magenta, cyan, gray, default
ns_param logprefixintensity normal;# bright or normal
#
# Severities to be logged (can also be controlled at run time via ns_logctl):
ns_param logdebug false ;# debug messages
ns_param logdev false ;# development message
ns_param lognotice true ;# informational messages
# ...
}
The logging behavior can be tailored at startup or at run time as well via ns_logctl commands, as show below.
% ns_log notice "Hello World!" [21/May/1974:15:30:00][12257.40348b90][-command-] Notice: Hello World! % ns_log notice Hello World! [21/May/1974:15:30:01][12257.40348b90][-command-] Notice: Hello World!
Enable debug logging while the server is running.
nscp:1> ns_log debug testing... nscp:2> ns_logctl severity debug 0 nscp:3> ns_logctl severity debug -color green true 1 nscp:4> ns_log debug testing... [01/April/1984:11:11:59][12257.40348b90][-nscp:1-] testing...
Report log messages at the end of an ADP page, as well as log them to the error log file.
<h1>An ADP Page</h1>
<%
ns_logctl hold
# ... do some stuff here ...
%>
...
<%
if {[ns_logctl count] > 0} {
ns_adp_append "Log messages:"
ns_adp_append "<pre>[ns_logctl peek]</pre>"
}
ns_logctl release
%>
Create a new severity-level.
nscp:1> ns_logctl severities Notice Warning Error Fatal Bug Debug Dev nscp:2> ns_log my:debug "a debug message" unknown severity: "my:debug": should be one of: Notice Warning Error Fatal Bug Debug Dev nscp:3> ns_logctl severity my:debug off 0 nscp:4> ns_log my:debug "a debug message" nscp:5> ns_logctl severity my:debug on 0 nscp:6> ns_log my:debug "a debug message" [22/Nov/1963:13:25:00][1899.40349b90][-nscp:1-] my:debug: a debug message
ns_accesslog, ns_asynclogfile, ns_connchan, ns_http, ns_info, ns_rollfile