Navigation

Pyramid allows you to make use of the Python standard library
logging module. This chapter describes how to configure logging and how
to send log messages to loggers that you've configured.

Warning

This chapter assumes you've used a scaffold to create a project
which contains development.ini and production.ini files which help
configure logging. All of the scaffolds which ship with Pyramid do
this. If you're not using a scaffold, or if you've used a third-party
scaffold which does not create these files, the configuration information in
this chapter may not be applicable.

A Pyramid project created from a scaffold is configured to allow
you to send messages to Pythonstandardlibraryloggingpackage loggers from within your application. In particular, the
PasteDeploydevelopment.ini and production.ini files created
when you use a scaffold include a basic configuration for the Python
logging package.

PasteDeploy .ini files use the Python standard library ConfigParserformat. This is the same format used as the Python
logging module's Configuration file format.
The application-related and logging-related sections in the configuration file
can coexist peacefully, and the logging-related sections in the file are used
from when you run pserve.

The pserve command calls the pyramid.paster.setup_logging() function,
a thin wrapper around the logging.config.fileConfig() using the specified
.ini file, if it contains a [loggers] section (all of the
scaffold-generated .ini files do). setup_logging reads the logging
configuration from the ini file upon which pserve was invoked.

Default logging configuration is provided in both the default
development.ini and the production.ini file. The logging configuration
in the development.ini file is as follows:

a logger named root is created that logs messages at a level above or
equal to the INFO level to stderr, with the following format:

2007-08-17 15:04:08,704 INFO [packagename] Loading resource, id: 86

a logger named myapp is configured that logs messages sent at a level
above or equal to DEBUG to stderr in the same format as the root logger.

The root logger will be used by all applications in the Pyramid process
that ask for a logger (via logging.getLogger) that has a name which begins
with anything except your project's package name (e.g., myapp). The logger
with the same name as your package name is reserved for your own usage in your
Pyramid application. Its existence means that you can log to a known
logging location from any Pyramid application generated via a scaffold.

Pyramid and many other libraries (such as Beaker, SQLAlchemy, Paste) log
a number of messages to the root logger for debugging purposes. Switching the
root logger level to DEBUG reveals them:

[logger_root]#level = INFOlevel=DEBUGhandlers=console

Some scaffolds configure additional loggers for additional subsystems they use
(such as SQLALchemy). Take a look at the production.ini and
development.ini files rendered when you create a project from a scaffold.

Python's special __name__ variable refers to the current module's fully
qualified name. From any module in a package named myapp, the __name__
builtin variable will always be something like myapp, or
myapp.subpackage or myapp.package.subpackage if your project is named
myapp. Sending a message to this logger will send it to the myapp
logger.

To log messages to the package-specific logger configured in your .ini
file, simply create a logger object using the __name__ builtin and call
methods on it.

Often there's too much log output to sift through, such as when switching the
root logger's level to DEBUG.

For example, you're diagnosing database connection issues in your application
and only want to see SQLAlchemy's DEBUG messages in relation to database
connection pooling. You can leave the root logger's level at the less verbose
INFO level and set that particular SQLAlchemy logger to DEBUG on its
own, apart from the root logger:

[logger_sqlalchemy.pool]level=DEBUGhandlers=qualname=sqlalchemy.pool

then add it to the list of loggers:

[loggers]keys=root, myapp, sqlalchemy.pool

No handlers need to be configured for this logger as by default non-root
loggers will propagate their log records up to their parent logger's handlers.
The root logger is the top level parent of all loggers.

This technique is used in the default development.ini. The root logger's
level is set to INFO, whereas the application's log level is set to
DEBUG:

All of the child loggers of the myapp logger will inherit the DEBUG
level unless they're explicitly set differently. Meaning the myapp.views,
myapp.models, and all your app's modules' loggers by default have an
effective level of DEBUG too.

For more advanced filtering, the logging module provides a
logging.Filter object; however it cannot be used directly from the
configuration file.

The WSGI design is modular. Waitress logs error conditions, debugging
output, etc., but not web traffic. For web traffic logging, Paste provides the
TransLoggermiddleware. TransLogger produces logs in the Apache Combined Log
Format. But
TransLogger does not write to files; the Python logging system must be
configured to do this. The Python logging.FileHandler logging handler
can be used alongside TransLogger to create an access.log file similar to
Apache's.

Like any standard middleware with a Paste entry point, TransLogger can
be configured to wrap your application using .ini file syntax. First
rename your Pyramid .ini file's [app:main] section to
[app:mypyramidapp], then add a [filter:translogger] section, then use a
[pipeline:main] section file to form a WSGI pipeline with both the
translogger and your application in it. For instance, change from this:

TransLogger will automatically setup a logging handler to the console when
called with no arguments, so it "just works" in environments that don't
configure logging. Since our logging handlers are configured, we disable
the automation via setup_console_handler=False.

With the filter in place, TransLogger's logger (named the wsgi logger) will
propagate its log messages to the parent logger (the root logger), sending its
output to the console when we request a page:

To direct TransLogger to an access.log FileHandler, we need the following
to add a FileHandler (named accesslog) to the list of handlers, and ensure
that the wsgi logger is configured and uses this handler accordingly:

As mentioned above, non-root loggers by default propagate their log records to
the root logger's handlers (currently the console handler). Setting
propagate to 0 (False) here disables this; so the wsgi logger
directs its records only to the accesslog handler.

Finally, there's no need to use the generic formatter with TransLogger as
TransLogger itself provides all the information we need. We'll use a formatter
that passes through the log messages as is. Add a new formatter called
accesslog by including the following in your configuration file: