qpsmtpd Wiki

[[api:plugin_logging]]

You are here: start » api » plugin_logging

Login

You are currently not logged in! Enter your authentication credentials below to log in. You need to have cookies enabled to log in.

Login

You don't have an account yet? Just get one: Register

Forgotten your password? Get a new one: Set new password

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

api:plugin_logging [2007/01/08 16:06] (current)
jamtur01 created
Line 1: Line 1:
 +====== qpsmtpd logging system; developer documentation ======
  
 +Qpsmtpd now (as of 0.30-dev) supports a plugable logging architecture, so
 +that different logging plugins can be supported.  See the example logging
 +plugins in plugins/logging, specifically the plugins/logging/warn and
 +plugins/logging/adaptive files for examples of how to write your own
 +logging plugins.
 +
 +===== Internal support for pluggable logging =====
 +
 +Any code in the core can call ''$self->log()'' and those log lines will be
 +dispatched to each of the registered logging plugins.  When ''log()'' is
 +called from a plugin, the plugin and hook names are automatically included
 +in the parameters passed the logging hooks.  All plugins which register for
 +the logging hook should expect the following parameters to be passed:
 +
 +<code perl>
 +  $self, $transaction, $trace, $hook, $plugin, @log
 +</code>
 +
 +where those terms are:
 +
 +==== $self ====
 +
 +The object which was used to call the ''log()'' method; this can be any object
 +within the system, since the core code will automatically load logging
 +plugins on behalf of any object.
 +
 +==== $transaction ====
 +
 +This is the current SMTP transaction (defined as everything that happens
 +between HELO/EHLO and QUIT/RSET).  If you want to defer outputting certain
 +log lines, you can store them in the transaction object, but you will need
 +to bind the reset_transaction hook in order to retrieve that information
 +before it is discarded when the transaction is closed (see the
 +logging/adaptive plugin for an example of doing this).
 +
 +==== $trace ====
 +
 +This is the log level (as shown in config.sample/loglevel) that the caller
 +asserted when calling ''log()''.  If you want to output the textural
 +representation (e.g. LOGERROR) of this in your log messages, you can use
 +the ''log_level()'' function exported by Qpsmtpd::Constants (which is
 +automatically available to all plugins).
 +
 +==== $hook ====
 +
 +This is the hook that is currently being executed.  If ''log()'' is called by
 +any core code (i.e. not as part of a hook), this term will be ''undef''.
 +
 +==== $plugin ====
 +
 +This is the plugin name that executed the ''log()''.  Like [[plugin_logging#$hook|$hook]], if part of
 +the core code calls ''log()'', this wil be ''undef''.  See logging/warn for a
 +way to prevent logging your own plugin's log entries from within that
 +plugin (the system will not infinitely recurse in any case).
 +
 +==== @log ====
 +
 +The remaining arguments are as passed by the caller, which may be a single
 +term or may be a list of values.  It is usually sufficient to call 
 +''join(" ",@log)'' to deal with these terms, but it is possible that some
 +plugin might pass additional arguments with signficance.
 +
 +Note: if you register a handler for certain hooks, e.g. deny, there may
 +be additional terms passed between $self and $transaction.  See logging/adaptive for and example.