Logging in Gajim

Logs are stored in a database (logs.db) . How to use the logging subsystem is described below.

Syntax

gajim --loglevel <logging directives>

Logging directives ::=
        Directive[,Directive[,…]]

Directive ::=
        Logspec=LEVEL

Logspec ::=
        logger[=logger[=…]]

LEVEL ::=
        Level name in uppercase, as listed in [1].
        Custom levels are recognized, provided that they are in all uppercase.
         - or -
        Level number. Does not need to match an existing level.

Note: No spaces are allowed anywhere.
[1]: http://www.python.org/doc/current/lib/module-logging.html

Examples

Setting gajim's global level to INFO:

gajim -l gajim=INFO

Exactly the same thing, numeric:

gajim -l gajim=20

Set main level to CRITICAL (at present nothing logs at this level, so it acts quiet), but everything in common/xmpp to DEBUG:

gajim -l gajim=CRITICAL,gajim.c.x=DEBUG

The same thing another way:

gajim -l gajim=CRITICAL -l gajim.c.x=DEBUG

Set main level to DEBUG, but silence transports_nb and gtkgui_helpers:

gajim -l gajim.c.x.transports_nb=gajim.gtkgui_helpers=CRITICAL,gajim=DEBUG

(Note different order here, the order of directives is in fact irrelevant.)

For the really lazy people, you can even omit gajim.* (except for src/gajim.py, which must always be specified as gajim.gajim.

Coding

Adding a logger to Python code is very simple. To the top of the file, add:

import logging
log = logging.getLogger('gajim.name.of.your.logger')

Of course you need to fill in the real name of the logger.

And that's it! Now you can write "log.debug("blahblah")" instead of "gajim.log.debug("blahblah")".

Hierarchy and Naming

Loggers are hierarchical, and are named (in Gajim) according to the file and directory structure.

For example, the logger for transports_nb is named:

gajim.c.x.transports_nb
  │   │ │       └────── Logger for common/xmpp/transports_nb, sublogger of xmpp.
  │   │ └────────────── xmpp, sublogger of common. Everything in common/xmpp goes through this logger
  │   └──────────────── common, sublogger of gajim. Everything in common/ goes through this logger.
  └──────────────────── Gajim's root logger. All new-style log messages pass through here.

Names of subdirectories are shortened to their first letter, to avoid overlong log lines.

Message Propagation

When a message is generated, the logger checks its own level. If the logger's level is unset, it will look at its parent's level, and so on, until a logger with a set level is found. So if the level of transports_nb has been set to DEBUG, this is its resulting level, and the parents will not be checked. By default all loggers are unset, except the gajim root, which is set to WARNING.

The message will be shown if its level is greater or equal to the logger's resulting level.

See also: the description of setLevel()