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

- ns_log severity-level message ?message ...?
- ns_logctl count
- ns_logctl flush
- ns_logctl get
- ns_logctl hold
- ns_logctl peek
- ns_logctl release
- ns_logctl severities
- ns_logctl severity severity-level ?bool?
- ns_logctl stats
- ns_logctl truncate count
- ns_logctl register script ?script-args ...?
- ns_logctl unregister handle
- ns_logroll

## 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