NaviServer - programmable web server
4.99  5.0

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

ns_log(n) 5.0.0a naviserver "NaviServer Built-in Commands"

Name

ns_log - Global server error log

Table Of Contents

Synopsis

Description

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.

COMMANDS

ns_log severity-level message ?message ...?

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.

Notice

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.

Warning

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.

Error

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.

Fatal

Something extremely bad occurred. The server will shut down after logging this message.

Bug

Something occurred that implies that there is a bug in the code. This condition could never happen when the code is behaving correctly.

Debug

General debugging.

Debug(access)

Mirror access log entries in system log.

Debug(cgi)

Debugging for the nscgi module.

Debug(connchan)

Debugging for ns_connchan interactions.

Debug(ns:driver)

Debugging for driver (low-level network IO).

Debug(nsproxy)

Debugging for nsproxy module.

Debug(request)

Debugging for request live cycle.

Debug(sql)

Debugging for SQL (nsdb module).

Debug(task)

Debugging for task interface (e.g. ns_http).

Debug(urlspace)

Debugging for ns_urlspace interactions.

Dev

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.

ns_logctl count

Returns a count of buffered messages for the current thread. The message buffering can be turned on subcommand hold.

ns_logctl flush

Write buffered log messages from the current thread to the log file. Do not disable buffering enabled by hold.

ns_logctl get

Return all buffered log messages, removing them from the buffer without writing them to the log file.

ns_logctl grep ?-filename filename? string

Read through the system log file, join continuation lines, strip color codes and grep 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.

ns_logctl 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.

ns_logctl peek

Return a copy of any buffered log messages for the current thread.

ns_logctl release

Write buffered log messages from the current thread to the log file and disable buffering. Future log messages will not be buffered.

ns_logctl severities

Return a list of available severity-levels. The result includes the 7 predefined levels and those created with ns_logctl or via C code.

ns_logctl severity severity-level ?-color color? ?-intensity intensity? ?bool?

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.

ns_logctl stats

Return statistics from calls to ns_log by severity-level.

ns_logctl truncate count

Discard this thread's buffered messages, leaving count untouched.

ns_logctl register script ?script-args ...?

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.

ns_logctl unregister handle

Unregister the previously registered log filter script identified by handle.

ns_logroll

Roll the server error log. The behavior is independent of the configuration parameter logroll. See ns_rollfile for details of log rolling.

CONFIGURATION

The error log is configured globally for the whole server process.

 ns_section ns/parameters
 ns_param   ...

The following are valid configuration parameters:

logcolorize

If true, log entries will be colorized using ANSI color codes Default: false.

logdebug

If true messages of severity-level Debug are enabled. Default: false.

logdev

If true, messages of severity-level Dev are enabled. Default: false.

logexpanded

If true, an extra newline is added to each log entry. Default: false.

logmaxbackup

The number of old error log files to keep around if log rolling is enabled. Default: 10.

lognotice

If true, messages of severity-level Notice are enabled. Default: true.

logprefixcolor

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.

logprefixintensity

When logcolorize is true, provide the intensity for the timestamp prefix. Possible values are: normal bright. Default: normal.

logroll

If true, the log file will be rolled when the server receives a SIGHUP signal. Default: true.

logrollfmt

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.

serverlog

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

logsec

If true, log entries will have seconds timestamps. Default: true.

logthread

If true, log entries will have thread ids included. Default: true.

logusec

If true, log entries will have timestamps with microsecond (usec) resolution. Default: false.

logusecdiff

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.

EXAMPLES

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

See Also

ns_accesslog, ns_asynclogfile, ns_connchan, ns_http, ns_info, ns_rollfile

Keywords

configuration, error, global built-in, log, nscgi, nsdb, nsproxy, path