# `cement.ext.ext_logging`

The Logging Extension provides log handling based on the standard `logging.Logger`, and is the default log handler used by Cement.

## Requirements

> - No external dependencies.

## Configuration

This extension honors the following configuration settings from the config section `log.logging`:

> - level
> - file
> - to_console
> - rotate
> - max_bytes
> - max_files

A sample config section (in any config file) might look like:

    [log.logging]
    file = /path/to/config/file
    level = info
    to_console = true
    rotate = true
    max_bytes = 512000
    max_files = 4

## Usage

    from cement.core.foundation import CementApp

    with MyApp() as app:
        app.log.info("This is an info message")
        app.log.warning("This is an warning message")
        app.log.error("This is an error message")
        app.log.fatal("This is a fatal message")
        app.log.debug("This is a debug message")

class `cement.ext.ext_logging.``LoggingLogHandler`(*args, **kw)

  Bases: `cement.core.log.CementLogHandler`

  This class is an implementation of the ILog interface, and sets up the logging facility using the standard Python logging module.

  class `Meta`

    Bases: `object`

    Handler meta-data.

    `clear_loggers` = []

      List of logger namespaces to clear. Useful when imported software also sets up logging and you end up with duplicate log entries.

      Changes in Cement 2.1.3. Previous versions only supported clear_loggers as a boolean, but did fully support clearing non-app logging namespaces.

    `config_defaults` = {'max_bytes': 512000, 'rotate': False, 'to_console': True, 'file': None, 'level': 'INFO', 'max_files': 4}

      The default configuration dictionary to populate the `log` section.

    `console_format` = '%(levelname)s: %(message)s'

      The logging format for the consoler logger.

    `debug_format` = '%(asctime)s (%(levelname)s) %(namespace)s : %(message)s'

      The logging format for both file and console if `debug==True`.

    `file_format` = '%(asctime)s (%(levelname)s) %(namespace)s : %(message)s'

      The logging format for the file logger.

    `formatter_class`

      Class to use as the formatter

      alias of `Formatter`

    `interface`

      The interface that this class implements.

      alias of `ILog`

    `label` = 'logging'

      The string identifier of this handler.

    `namespace` = None

      The logging namespace.

      Note: Although Meta.namespace defaults to None, Cement will set this to the application label (CementApp.Meta.label) if not set during setup.

  `LoggingLogHandler.``_setup_console_log`()

    Add a console log handler.

  `LoggingLogHandler.``_setup_file_log`()

    Add a file log handler.

  `LoggingLogHandler.``clear_loggers`(namespace)

    Clear any previously configured loggers for `namespace`.

  `LoggingLogHandler.``debug`(msg, namespace=None, **kw)

    Log to the DEBUG facility.

    Parameters:

    - msg – The message to log.
    - namespace – A log prefix, generally the module `__name__` that the log is coming from. Will default to self._meta.namespace if None is passed. For debugging, it can be useful to set this to `__file__`, though `__name__` is much less verbose.
    - kw – Keyword arguments are passed on to the backend logging system.

  `LoggingLogHandler.``error`(msg, namespace=None, **kw)

    Log to the ERROR facility.

    Parameters:

    - msg – The message to log.
    - namespace – A log prefix, generally the module `__name__` that the log is coming from. Will default to self._meta.namespace if None is passed.
    - kw – Keyword arguments are passed on to the backend logging system.

  `LoggingLogHandler.``fatal`(msg, namespace=None, **kw)

    Log to the FATAL (aka CRITICAL) facility.

    Parameters:

    - msg – The message to log.
    - namespace – A log prefix, generally the module `__name__` that the log is coming from. Will default to self._meta.namespace if None is passed.
    - kw – Keyword arguments are passed on to the backend logging system.

  `LoggingLogHandler.``get_level`()

    Returns the current log level.

  `LoggingLogHandler.``info`(msg, namespace=None, **kw)

    Log to the INFO facility.

    Parameters:

    - msg – The message to log.
    - namespace – A log prefix, generally the module `__name__` that the log is coming from. Will default to self._meta.namespace if None is passed.
    - kw – Keyword arguments are passed on to the backend logging system.

  `LoggingLogHandler.``set_level`(level)

    Set the log level. Must be one of the log levels configured in self.levels which are `['INFO', 'WARNING', 'ERROR', 'DEBUG', 'FATAL']`.

    Parameters: | level – The log level to set.

  `LoggingLogHandler.``warn`(msg, namespace=None, **kw)

    DEPRECATION WARNING: This function is deprecated as of Cement 2.9.x in favor of the `LoggingLogHandler.warning()` function, and will be removed in future versions of Cement.

    See: :ref:LoggingLogHandler.warning():

  `LoggingLogHandler.``warning`(msg, namespace=None, **kw)

    Log to the WARNING facility.

    Parameters:

    - msg – The message to log.
    - namespace – A log prefix, generally the module `__name__` that the log is coming from. Will default to self._meta.namespace if None is passed.
    - kw – Keyword arguments are passed on to the backend logging system.