Navigation

A package which logs Pyramid application exception (error) information to a
standard Python logger. This add-on is most useful when used in
production applications, because the logger can be configured to log to a
file, to UNIX syslog, to the Windows Event Log, or even to email.

When this add-on is included into your Pyramid application, whenever a
request to your application causes an exception to be raised, the add-on will
send the URL that caused the exception, the exception type, and its related
traceback information to a standard Python logger named
exc_logger.

You can use the logging configuration in your Pyramid application’s .ini
file to add a logger named exc_logger. This logger should be hooked up a
particular logging handler, which will allow you to use the standard Python
logging machinery to send your exceptions to a file, to syslog, or to an
email address.

It’s not generally useful to add exception logger configuration to a
development.ini file, because typically exceptions are displayed in the
interactive debugger and to the console which started the application, and
you really don’t care much about actually logging the exception
information. However, it’s very appropriate to add exception logger
configuration to a production.ini file.

The following logging configuration statements are in the defaultproduction.ini file generated by all Pyramid scaffolding:

The standard logging configuration of the production.ini of a scaffolded
Pyramid application does not name a logger named exc_logger. Therefore,
to start making use of pyramid_exclog, you’ll have to add an
exc_logger logger to the configuration. To do so:

Append ,exc_logger to the keys value of the [loggers] section,

Append ,exc_handler to the keys value of the [handlers]
section.

Append ,exc_formatter to the keys value of the [formatters]
section.

Add a section named [logger_exc_logger] with logger information
related to the new exception logger.

Add a section named [handler_exc_handler] with handler information
related to the new exception logger. In our example, it will have
configuration that tells it to log to a file in the same directory as the
.ini file named exception.log.

Add a section named [formatter_exc_formatter] with message formatting
information related to the messages sent to the exc_handler handler.
By default we’ll send only the time and the message.

Once you’ve changed your logging configuration as per the above, and you
restart your Pyramid application, all exceptions will be logged to a file
named exceptions.log in the directory that the production.ini file
lives.

You can get fancier with logging as necessary by familiarizing yourself with
the Python logging module configuration format. For example, here’s an
alternate configuration that logs exceptions via email to a user named
from@example.com to a user named to@example.com via the SMTP server
on the local host at port 25; each email will have the subject myappException:

pyramid_exclog` also has some its own settings in the form of
configuration values which are meant to be placed in the [app:myapp]
section of your Pyramid’s .ini file. These are:

exclog.ignore

By default, the exception logging machinery will log all exceptions (even
those eventually caught by a Pyramid exception view) except “http
exceptions” (any exception that derives from the base class
pyramid.httpexceptions.WSGIHTTPException such as HTTPFound). You
can instruct pyramid_exclog to ignore custom exception types by using
the excview.ignore configuration setting.

excview.ignore is a list of dotted Python names representing exception
types (e.g. myapp.MyException) or builtin exception names (e.g.
NotImplementedError or KeyError) that represent exceptions which
should never be logged. This list can be in the form of a
whitespace-separated string, e.g. KeyErrorValueErrormyapp.MyException or it may consume multiple lines in the .ini file.

This setting defaults to a list containing only
pyramid.httpexceptions.WSGIHTTPException.

By default the only content in error messages is the URL that was
accessed (retrieved from the url attribute of pyramid.request.Request)
and the exception information that is appended by Python’s
Logger.exception function.

If exclog.extra_info is true the error message will also include
the environ and params attributes of pyramid.request.Request formatted
using pprint.pformat(). The output from
pyramid.security.unauthenticated_id() is also included.

This setting defaults to false

An example:

[app:myapp]exclog.extra_info=true

exclog.get_message

If a customized error message is needed, the exclog.get_message
setting can be pointed at a function that takes a request as its only
argument and returns a string. It can be either a dotted name or the
actual function. For example: