Logging
=======

The (ssh log) module provides procedures to control the libssh logging facilities.

 -- Scheme Procedure: %default-log-printer priority function message userdata
     Default callback for printing log messages to the current error port.  The procedure comments out log messages with ``;;; `` to make it easier to distinguish libssh traces from Guile-SSH messages in REPL mode.

     This callback is set by default.

 -- Scheme Procedure: %default-libssh-log-printer priority function message userdata
     The procedure makes log messages in the same format as the libssh default log formatter.

 -- Scheme Procedure: current-logging-callback
     Return the current logging callback.  Returns a procedure or #f if the callback is not set.

 -- Scheme Procedure: set-logging-callback! callback
     Change the current logging callback to CALLBACK.  The CALLBACK must be a procedure that takes four arguments: priority of a log message, a function name, the message and a custom user data.

     Throw guile-ssh-error on an error.  Return value is undefined.

     Here is an example of a custom callback which indents each log message according to its priority:

          (define (pretty-log-printer priority function message userdata)
            (do ((i 1 (1+ i)))
                ((> i priority))
              (display "  " (current-error-port)))
            (format (current-error-port) "[~a] ~a~%"
                    (strftime "%Y-%m-%dT%H:%M:%S%z" (localtime (current-time)))
                    message))

          (set-logging-callback! pretty-log-printer)

     You can restore the default callback as the follows:

          (set-logging-callback! %default-log-printer)

 -- Scheme Procedure: set-log-userdata! user-data
     Set an arbitrary USER-DATA to be passed to a logging callback. Throw guile-ssh-error on an error.  Return value is undefined.

     By default the user data is set to #f.

 -- Scheme Procedure: get-log-userdata
     Get the current user data.

 -- Scheme Procedure: format-log priority procedure-name format-string arg ...
     Write a formatted message to the libssh log with the given PRIORITY. Return value is undefined.

     Syntax for the FORMAT-STRING is the same as for format procedure.

     PRIORITY is expected to be a symbol.  Acceptable priority levels are:

     nolog
          The message will be printed even if the logging is disabled

     rare
          Rare and noteworthy events

     protocol
          High level protocol information

     packet
          Lower level protocol infomations, packet level

     functions
          Function path

 -- Scheme Procedure: set-log-verbosity! verbosity
     Set the global log verbosity to a VERBOSITY.  Throw guile-ssh-error on error.  Return value is undefined.

     VERBOSITY is expected to be one of the following symbols:

     nolog
          The message will be printed even if the logging is disabled

     rare
          Rare and noteworthy events

     protocol
          High level protocol information

     packet
          Lower level protocol infomations, packet level

     functions
          Function path

 -- Scheme Procedure: get-log-verbosity
     Get global log verbosity value.