NaviServer Built-in Commands – 5.1.0
ns_log - Global server system 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.
Writes a message to the system log file if the given severity 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.
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 system 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.
A deprecated function was used.
Something security relevant has occurred.
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.
Write buffered log messages from the current thread to the log file. Do not disable buffering enabled by hold.
Returns all buffered log messages, removing them from the buffer without writing them to the log file.
Reads through the system log file, joins continuation lines, strips color codes and greps in the result for the provided string. The function returns all lines containing the specified string. When -filename is specified, the search is performed on the specified file. The specified filename should be fully qualified.
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.
Registers 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.
Write buffered log messages from the current thread to the log file and disable buffering. Future log messages will not be buffered.
Returns a list of available severity levels. The result includes the 7 predefined levels and those created with ns_logctl or via C code.
Returns true if the given severity is enabled, false if it is disabled. If the last argument ?true|false? is given it enables/disables the given severity 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 does not already exist and more arguments arg given, then the new severity is created. Future calls to ns_log may use new severity.
Returns statistics from calls to ns_log grouped by severity.
Discard this thread's buffered messages, leaving count untouched.
Unregisters the previously registered log filter script identified by handle.
Rolls the system log. The behavior depends on the configuration parameter logmaxbackup and logrollfmt. See ns_rollfile for details of log rotation.
The system log is configured globally for the NaviServer process in the ns/parameters section. These settings control which log severities are enabled, how log entries are formatted, and how the system log is rolled.
ns_section ns/parameters {
# Enable or disable selected severities.
ns_param logdebug false
ns_param lognotice true
ns_param logdev false
# Configure timestamp and thread information.
ns_param logsec true
ns_param logusec false
ns_param logusecdiff false
ns_param logthread true
ns_param logrelative false
# Configure log formatting.
ns_param logcolorize false
ns_param logprefixcolor green
ns_param logprefixintensity normal
ns_param logexpanded false
ns_param logdeduplicate false
# Configure system log file and log rotation.
ns_param systemlog logs/nsd.log
ns_param logmaxbackup 10
ns_param logroll true
ns_param logrollfmt %Y-%m-%d
}
The parameters logdebug, lognotice, and logdev control whether messages of the corresponding severities are written to the system log. Other severities, such as warnings and errors, are always important operational messages and should normally not be suppressed.
The parameters logsec, logusec, logusecdiff, logrelative, and logthread control the prefix added to log entries. These options are useful when debugging timing issues, comparing logs across repeated runs, or identifying which thread produced a log entry.
The logrelative option prints timestamps relative to the first log entry instead of wall-clock time. This can make logs from repeated test runs easier to compare.
The logusecdiff option adds the time difference since the previous log entry from the same process, which can be useful for spotting latency without additional instrumentation.
The parameters logcolorize, logprefixcolor, and logprefixintensity control ANSI color output for log prefixes. These settings are useful mainly when logs are viewed directly in a terminal.
The logexpanded option formats each log entry with the message on an indented separate line and adds a blank line after each entry. This can make long or multi-line messages easier to read during debugging, but produces larger and less compact log files.
The logdeduplicate option collapses consecutive identical log messages from the same thread. The first occurrence is written normally; repeated identical messages are suppressed until a different message is logged, at which point a summary line reports how often the previous message was repeated.
The systemlog parameter specifies the system log file. If the path is relative, it is resolved according to the server's global path rules.
The parameters logroll, logrollfmt, and logmaxbackup control log rotation and retention. When log rolling is enabled, NaviServer can rotate the system log on signal or according to the configured rolling behavior. The logrollfmt parameter controls the timestamp suffix appended to rotated log file names.
The following system-log-related parameters are accepted in the ns/parameters section, starting with the prefix log. For the complete reference of global configuration parameters, see NaviServer configuration parameter reference.
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 systemlog nsd.log
#
# Configuration of systemlog
#
# Rolling of logfile:
ns_param logrollonsignal on ;# log rotation on SIGHUP (default: on)
ns_param logmaxbackup 100 ;# (default: 10)
ns_param logrollfmt %Y-%m-%d ;# timestamp format appended to systemlog 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 logrelative false ;# start timestamps from zero relative to first log entry (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 messages passed to the ns_log command can be given either as a single string or as multiple arguments. In the latter case, the arguments are concatenated with spaces into one log message.
% 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!
The following example shows the effect of different timestamp formatting options. The example assumes that logusec is enabled, so that timestamps include microsecond resolution. When logrelative is enabled at the same time, the relative offset is likewise shown in microseconds.
;# logrelative = false (absolute wall clock time) [17/Sep/2025:19:11:23.456789] Notice: server started [17/Sep/2025:19:11:23.987654] Notice: listening on 0.0.0.0:8080 # logrelative = true (relative time since first entry) [0.000000] Notice: server started [0.122119] Notice: listening on 0.0.0.0:8080
If logusec is disabled, timestamps fall back to second-only precision, regardless of logrelative.
The logging behavior can be tailored at startup or at run time as well via ns_logctl commands, as show below. 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 system 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.
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
admin-config-params, ns_accesslog, ns_asynclogfile, ns_connchan, ns_http, ns_info, ns_purgefiles, ns_rollfile