NaviServer - programmable web server


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

ns_log(n) 4.99.8 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 ...?

Queue a message for the error log file if the given severity-level is enabled. The message arguments are concatenated with connecting spaces. The message will reach the log file when the per-thread cache is flushed.

The following are the predefined values of severity-level.

Notice

Something interesting occurred.

Warning

Something that could mean something bad occurred.

Error

Something bad occurred.

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.

Debug

If debug level logging is enabled the the message is logged.

Dev

If dev level logging is enabled the message is logged.

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

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.

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. This includes the 7 predefined levels and those created with ns_logctl or via C code.

ns_logctl severity severity-level ?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.

If severity-level does not already exist and bool is given, then the new severity is created, enabled or disabled according to bool. 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 threads 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. This works whether the configuration parameter logroll is enabled or not. 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:

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

lognotice

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

logdev

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

logdebug

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

logusec

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

logexpanded

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

logroll

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

logmaxbackup

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

EXAMPLES

Equivalent log messages.

% 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 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_info, ns_rollfile

Keywords

configuration, error, log, path