Logging

A Moya web application can generate a number of log messages, useful for monitoring what your site is doing and diagnosing errors. Moya's logging system is highly configurable and allows you to set which log messages you see and where they are written.

Introduction

Moya borrows its logging system from Python's logging library and has much the same capabilities.

Log messages are emited from various loggers. A logger has a name which identifies the source of the log messages. Moya uses the name moya for its log messages. Loggers are further categorized with a dot. The following lists the loggers used by Moya:

moya.app.APP
Logs messages written by applications; APP is replaced with the name of the application. For example moya.app.auth would be the name used for log messages written by the application named "auth".
moya.cache
Log messages written by the cache system when cache debug is enabled.
moya.email
Log messages written regarding the sending of emails.
moya.jsonrpc
Log messages regarding remote procedure calls.
moya.request
Logs information about each request.
moya.runtime
Logs information about events that occur during normal operation.
moya.security
Logs information about security issues, such CSRF attempts detected by the forms library.
moya.signal
Log messages regarding signals.
moya.startup
Messages regarding the startup process, such as the importing and installing of libraries.

Each log messages has a log level, which defines the severity of the log message. Log messages may be filtered based on the log level, so you only see the type of message you are interested in. The log levels are as follows:

debug
Information to help you track down errors, which you probably don't want in production.
info
General information about normal operation of the server.
warning
A potential problem was detected.
error
The server was unable to perform as requested.
fatal
A serious issue with potential data loss was detected.

Log Tags

You can write log messages of your own with the <log> tag. The message goes in the enclosed text. Here's an example:

<log>Your log messages goes here</log>

You may set the logging level with the level attribute. For example:

<log level="debug">1s and 0s</log>
<log level="info">Thought you might want to know</log>
<log level="error">I've made a terrible mistake</log>

For each of the logging levels there is a log tag that write logs just that level. For instance, <log-debug> writes a debug log and <log-warn> writes a warning log. These level specific log tags are identical to <log> in all other respects.

Configuration

The logging system may be configured via an INI file, which allows you to set which messages are to be filtered, and where they should will be written (e.g. to the console or to a file).

The development server uses logging configuration taken from a file called logging.ini which is set up to write all message to the console. In production, Moya uses the file prodlogging.ini which shows only messages with level info or higher.

You can change which logging configuration file is used in the development server with the --logging switch. This is useful for checking your production logging settings. For example:

$ moya --logging prodlogging.ini runserver

The logging configuration file used in production is set in the WSGI file (see Deploying). The default prodlogging.ini writes log messages with a level of INFO or higher to syslog. Note that the syslog configuration assumes the defaults for most Linux Distros, if you are running on OSX or Windows, you will need enable the configuration for your platform which will be commented out in prodlogging.ini.

Moya's logging INI format is similar to the configuration format used by Python's logging module, but is more consistent with Moya's other INI files (and somewhat less prone to errors).

Loggers

You can configure a logger with a named section as follows:

[logger:moya]
level = DEBUG

This sets a level of DEBUG on the moya logger, which ensures that all log messages are written.

Note that when a log message is written, the logging system looks for all handlers in the hierarchy defined with the dotted notation. For example if the moya.app.auth logger emits a message, it will be written to moya.app.auth, moya.app, moya, and finally a special logger called root. If you don't want this behavior, you can set propagate=no on the logger, to stop writing to the loggers further up the chain.

If you find your log messages are being written twice, it is likely because they are being propagated up the hierarchy. You will probably want to disable propagation on most specific handler (most dots).

Formatters

A formatter sets how a log message is formatted. Here's the default formatter that writes the log message along with the date and level:

[formatter:simple]
format = %(asctime)s:%(name)s:%(levelname)s: %(message)s
datefmt = [%d/%b/%Y %H:%M:%S]

Handlers

A handler sets the destination for logging messages (file, console, syslog etc). See the Python documentation for the full details on creating formatters. Otherwise, here are the default handlers used by Moya:

# Writes syntax highlighted log messages to the terminal
[handler:moyaconsole]
class = moya.logtools.MoyaConsoleHandler
formatter = simple
args = (sys.stdout,)

# Writes simple text to the terminal
[handler:stdout]
class = StreamHandler
formatter = simple
args = (sys.stdout,)

# Writes to a syslog server
[handler:syslog]
class = logging.handlers.SysLogHandler
args = ('/dev/log',)

You can set which handler a logger should use with the handler key. For example:

[logger:moya]
level = DEBUG
handler = moyaconsole
Note that without a handler of some kind a logger will not be able to write log messages.

Other Loggers

Other loggers not under the moya namespace may be configured with Moya's logging configuration. The sqlalchemy logger is of particular interest, as it can log all the SQL queries going to the database. If you add the following to your logging ini, you will see SQL related information in the terminal:

[logger:sqlalchemy.engine]
handlers = moyaconsole
propagate = no
level = INFO

You can set the level to DEBUG to display more details, although the messages there are less useful than the SQL. Set level to WARN to disable sqlalchemy logs.