ZConfig Configuration

  This documentation covers the configuration of mailing loggers in
  an application already using ZConfig for configuration parsing.
  
  If that's the case, you will likely have your own existing
  schema.xml. If you do not, here is a minimal schema that will
  support configuration of loggers with mailing handlers and the
  default ZConfig log handlers:

  >>> f = open('schema.xml','w')
  >>> f.write('''
  ... <schema>
  ...   <!-- import for log sections -->
  ...   <import package="ZConfig.components.logger" file="logger.xml"/>
  ...   <!-- import for default log handlers -->
  ...   <import package="ZConfig.components.logger" file="handlers.xml"/>
  ...   <!-- import for mailing-logger and summarising-logger handlers -->
  ...   <import package="mailinglogger"/>
  ...   <!-- now the logger sections -->
  ...   <multisection name="*"
  ...                 attribute="loggers"
  ...                 type="logger"/>
  ... </schema>
  ... ''')
  >>> f.close()

  A sample config file that implements this schema is shown below:

  >>> f = open('my.conf','w')
  >>> f.write('''
  ...  <logger>
  ...    name  mylogger
  ...    level info
  ...    <mailing-logger>
  ...      level   error
  ...      from    logging@example.com
  ...      to      receiver@example.com
  ...      to      support@example.com
  ...      subject [MyApp] %(line)s
  ...      <headers>
  ...        filter some-customer
  ...      </headers>
  ...    </mailing-logger>    
  ...  </logger>
  ... ''')
  >>> f.close()

  To use this configuration in your application, you need to first
  load the schema:

  >>> from ZConfig import loadSchema
  >>> schema = loadSchema('schema.xml')

  You then need to load the configuration:

  >>> from ZConfig import loadConfig
  >>> config, handlers = loadConfig(schema, 'my.conf')

  The configuration now contains a list of logger factories:
  >>> config.loggers
  [<ZConfig.components.logger.logger.LoggerFactory instance at ...>]

  Calling these factories will instantiate the loggers and register
  them with the logging framework:

  >>> for logger in config.loggers:
  ...   logger()
  <logging.Logger instance at ...>

  As the above example shows, the factory also returns the new
  logger, although this can safely be ignored.

  Now that the configuration is loaded, any logging to the
  appropriate logger will cause an email to get sent:

  >>> from logging import getLogger
  >>> getLogger('mylogger').error('something bad has happened')
  sending to ['receiver@example.com', 'support@example.com'] from 'logging@example.com' using ('localhost', 25)
  Content-Type: text/plain; charset="us-ascii"
  MIME-Version: 1.0
  Content-Transfer-Encoding: 7bit
  filter: some-customer
  Subject: [MyApp] something bad has happened
  From: logging@example.com
  To: receiver@example.com, support@example.com
  X-Mailer: MailingLogger...
  Date: ...
  Message-ID: <...MailingLogger@...>
  <BLANKLINE>
  something bad has happened

  The same schema can also be used for a configuration that uses a
  summarising logger instead:

  >>> f = open('summarising.conf','w')
  >>> f.write('''
  ...  <logger>
  ...    name summary
  ...    <summarising-logger>
  ...      from    logging@example.com
  ...      to      summary@example.com
  ...      subject Summary of Activity
  ...      format  %(levelname)s - %(message)s
  ...      <headers>
  ...        filter some-customer
  ...      </headers>
  ...    </summarising-logger>    
  ...  </logger>
  ... ''')
  >>> f.close()
  >>> config, handlers = loadConfig(schema, 'summarising.conf')
  >>> for logger in config.loggers:
  ...   logger()
  <logging.Logger instance at ...>

  As with all summarising loggers, no emails are sent when messages
  are logged:

  >>> getLogger('summary').error('something bad happened')

  But, ZConfig's LoggerFactories have a handy method for re-opening
  loggers and their handlers. This method can be called to flush any
  queued messages and send a summary email:

  >>> config.loggers[0].reopen()
  sending to ['summary@example.com'] from 'logging@example.com' using ('localhost', 25)
  Content-Type: text/plain; charset="us-ascii"
  MIME-Version: 1.0
  Content-Transfer-Encoding: 7bit
  filter: some-customer
  Subject: Summary of Activity
  From: logging@example.com
  To: summary@example.com
  X-Mailer: MailingLogger...
  Date: ...
  Message-ID: ...
  <BLANKLINE>
  ERROR - something bad happened
  <BLANKLINE>

  One drawback of using ZConfig's logger section type is that you
  cannot use it to configure the root logger. In order to do this,
  you will need to come up with your own section type.

  Reference

    A full description of the possible keys and defaults for the
    mailing-logger and summarising-logger sections are given below:

    mailing-logger:

      dateformat

        The date format to use in log entries. This will be used
        wherever the %(asctime)s substitution is used.

        default: %Y-%m-%dT%H:%M:%S

      level

        The level at or above which an email log notification will be
        sent.

        This can either be a numeric level or one of the textual level
        identifiers.

        default: 0 

      from

        The address from which email log notifications will originate.

        This must be set.

      to

        The address to which email log notifications will be sent.

        At least one 'to' line must be included, but multiple lines
        can be included if email log notifications should be sent to
        multiple addresses.

      smtp-server 

        The SMTP server that should be used to send email
        notifications. This can include a port number, 
        eg: mail.example.com:2525 

        default: localhost

      subject 

        This is a format string specifying what information will be
        included in the subject line of the email notification.

        Information on what can be included in a subject format string can
        be found in docs/subjectformatter.txt

        default: [%(hostname)s] %(levelname)s - %(line)s

      format 

        This is a format string specifying what information will be
        included in each message that is logged.

        Information on what can be included in a format string can be
        found at:

        http://docs.python.org/lib/node293.html

        default: %(message)s

      send-empty-entries

        This is a boolean value which specifies whether empty log
        entries will be mailed or not.

        default: no

      flood-level

        This is an integer value specifying the maximum number of
        emails that can be sent in an hour that will not be considered
        a "flood".

        When a "flood" is detected, one email is sent at the CRITICAL
        level indicating that a flood has been detected, and no more
        emails will be sent in the same hour.

        So, this option, in effect, specifies the maximum number of
        emails that will be sent in any particular hour of the day.

        default: 10

      ignore

        A regular expression for entries to be silently discarded

        You can specify one or more regular expressions that are checked 
        against when a log entry is being handled. If the log entry message
        matches at least one of the regular expressions it will be discarded
        silently.

        default: unset

    summarising-logger:

      dateformat

        The date format to use in log entries. This will be used
        wherever the %(asctime)s substitution is used.

        default: %Y-%m-%dT%H:%M:%S

      level

        The level at or above which a logged message will be stored
        and sent as part of the summary email.

        This can either be a numeric level or one of the textual level
        identifiers.

        default: 0

      from

        The address from which the summary email will originate.

        This must be set.

      to

        The addresses to which the summary email will be sent.

        At least one 'to' line must be included, but multiple lines
        can be included if email log notifications should be sent to
        multiple addresses.

      smtp-server 

        The SMTP server that should be used to send send the summary
        mail. This can include a port number, 
        eg: mail.example.com:2525 

        default: localhost

      subject 

        This is a format string specifying what information will be
        included in the subject line of the summary email.

        Information on what can be included in a subject format string can
        be found in docs/subjectformatter.txt

        default: 'Summary of Log Messages'

      format 

        This is a format string specifying what information will be
        included in each message that is logged.

        Information on what can be included in a format string can be
        found at:

        http://docs.python.org/lib/node293.html

        default: %(asctime)s - %(levelname)s - %(message)s

      send-empty-entries

        This is a boolean value which specifies whether empty summary
        emails will be mailed or not.

        default: yes


      ignore

        A regular expression for entries to be silently discarded

        You can specify one or more regular expressions that are checked 
        against when a log entry is being handled. If the log entry message
        matches at least one of the regular expressions it will be discarded
        silently.

        default: unset

      atexit

        If True, this close method of the summarising logger is set as
        an atexit function that runs when the currently executing
        python script finishes.

        This results in a summary email being sent once the script
        terminates.

        default: True

