Feb 2024 - This site, and Kamaelia are being updated. There is significant work needed, and PRs are welcome.


Version: Axon 1.0.4

What is it?

A simple debugging class.

What is its purpose?

The purpose of this debug subsystem is to allow a configurable method for debugging. When dealing with single threaded concurrency it can become difficult to trace code, limiting the effectiveness of debuggers. (Especially the kind that allows you to step through execution)

How does it work?

The essential idea is this:

If one or more sections of code have an active tag, then a trace of what they requested is output along with a small amount of data to assist with debugging.

These sections, levels etc are defined in a "debug.conf" file in the local directory. In the absence of a debug.conf file, the system uses internal hard coded defaults.

One caveat: using a debug section/tag in code, but not defined in defaults nor in a config file will crash. This is by design.The reason is simple - whilst developers may wish to add random debug tags when creating their code, later when some maintainer wishes to figure out what's broken, having a complete list of all debug tags is vital. One way of ensuring this is to ensure they're either in the defaults or in a supplied and always findable debug.conf file. Quite how this will pan out in the long term is still unclear, but the motivation will remain the same. (Implementation approach may change of course!)

debug.conf file format

The config file consists of a number of lines.

Each line is either a comment or config line

A comment line is either an empty line, or a line starting with a '#'

A config line has 3 values:

section.tag debug.level debug.location


Sample trace output

Sat Feb 26 08:26:39 2005 | SimpleServerTestProtocol.mainBody | NetServ : We were sent data -

Sat Feb 26 08:26:39 2005 | SimpleServerTestProtocol.mainBody | We should probably do something with it now? :-)

Sat Feb 26 08:26:39 2005 | SimpleServerTestProtocol.mainBody | I know, let's sling it straight back at them :-)

Outstanding Issues

Just prior to the 1.0 release of Axon, we changed over to using setup.py (ie distutils) for installation/packaging etc. Prior to this the code expected to be run from a specific location and hence a debug.conf file would always be available. This was disable prior to the actual 1.0 release, but it would be nice to re-enable the full system again.

There are a number of issues with the way debugging is handled at present:

Configuration and defaults

Lack of decent test suite. (There is some partial testing, but it's nowhere near complete)

Documentation for the debug API currently sucks. (The only real usage docs would be to look at how Axon itself uses the debug subsystem)

Essentially the debugging divides the system into sections, and each section can have a debug level. The higher the debug level, the more output for that section you see. Debugging can also be switched on on a per component basis.

Issues Resolved

Pydoc Style Documentation

class debug(object)

Methods defined here:

__init__(self, assertBadDebug=1)

debug(self, section, level, *message)

note = debug(self, section, level, *message)

addDebug(self, **debugSections)

addDebugSection(self, section, level)

decreaseDebug(self, section)

increaseDebug(self, section)

readConfig(self, configFile='debug.conf')

setDebugSections(self, **debugSections)

useConfig(self, filename='debug.conf')

Testdoc Documentation

TODO:Implement test suite for Axon.debug.py (We did mention that tests were added late in the project?)

Michael, December 2004, February 2005