Table Of Contents

Next topic

Examples for rrlog

This Page

Manual for rrlog

A Remote Rotating Log for Python that works instantly


Download from Github | Sourceforge | see Change History

Overview

rrlog is a pure Python logging tool. It is for both debugging and production and provides common features instantly. These are:

  • Log Rotation
  • Remote Logging
  • Stacktrace logging (i.e. automatic call paths in logfiles)
  • EMail notification
  • logging into ASCII text files
  • logging into a database
  • Optional Integration with the python standard logging

How it looks like, for the impatient

A rotating server to log over sockets looks like:

logServer = filewriter.createRotatingServer(
        filePathPattern = "./myfile-%s.log",
        rotateCount=3,
        rotateLineMin=10,
        )
socketserver.startServer(logServer)

and an application using that server:

log = socketclient.createClientLog(
        errorHandler="stderr",
        )
log("Hello")

See below for full examples.

Most battery types included

Everything works instantly. No additional libraries required, except for database logging. Database logging needs the SqlAlchemy package.

Where it sucks

There are at least the following caveats:

  • It is designed and tested with a multi-process but not multithreaded application. Notice that nobody did care for a threaded environment yet. It may work threaded if you use the remote logging way. See Multiprocess & Multithread
  • rrlog still lives in the grey-bearded Python 2 world. There is an experimental Python 3 version (see Requirements) but that wasn’t in productive use yet.

Major improvements likely to come next are:

  • The rotation is triggered by the number of logged messages only. A time/date-triggered rotation is missing
  • only ASCII logging is specified. Unicode messages should be standard with Python3.

Basic usage

Create a callable log object

  1. call a “create...()” function

    There are multiple conventient create() functions. Each makes a specific log configuration: for local or remote logging, into a file or a database etc. Look into the Basic Examples to see which create...() functions are available.

  2. You got a log object. Call it with these arguments:

    • the log message (str)
    • an optional “category”, which is a single character. That “category” rawly corresponds with the “info”,”debug”,”warn”... levels of the standard logging.

    Example:

    log("Uuups!","E")
    

Althought that log object is ready to use, you can Use Pythons standard logging. (The log integrates as a handler.)

There are more arguments. See Basic Examples or the rrlog.Log.__call__() docstring.

The category parameter

Categories are custom. They fit specific needs. However there is a convention: “E” for error messages, “W” for warnings.

The category latter appears in each logged line (leftmost, by default).

Example use of the category: Messages with category “U” could trace the user behaviour of your website. By extracting all logfile lines that start with “U ”, you get a log essence with the user behaviour. rrlog can also Send mails for selected categories. For example, “S” could mark Security relevant messages which automatically trigger emails. Or, with every text a user typed into the contact formular, we log with category “M” and the user message as content. The rrlog can immediately send an email with the logged content.

Now for something completely different ...

Requirements

When using database logging, the SQLAlchemy library is required. File logging needs no additional library.

Tested environment:

  • Python 2.7 on 64Bit Linux
  • SQLAlchemy 0.8.1

Only this environment is tested. rrlog supports a wide range of Python and SQLAlchemy versions, to minimize dependency trouble. There’s a wide version range expected to work:

  • SQLAlchemy: all >= 0.3.2
  • Python: all from 2.4 to 2.7.

If some of these “supported versions” don’t work, it is considered a bug. Please tell (Contact)

Contact

Bug reports, improvements ...

Mail to rrlog at reifenberg.de

Or see http://www.reifenberg.de/rrlog/ or the sourceforge site Sourceforge

License (MIT)

MIT License

Copyright (c) 2007 Ruben Reifenberg

This software contains code from other MIT licensed projects. Thanks to:

The simplejson package:
	Copyright (c) 2006 Bob Ippolito

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Indices and tables