SubjectFormatter is a
special type of logging formatter that is
created from the subject parameter to the constuctor of a
It is tailored for formatting a log record to form the subject
line of an email message.
As can be seen below,
SubjectFormatter supports all
the usual keyword substitutions supported by normal Formatter objects:
>>> from mailinglogger.common import SubjectFormatter >>> formatter = SubjectFormatter(''' ... %(name)r ... %(levelno)r ... %(levelname)r ... %(pathname)r ... %(filename)r ... %(module)r ... %(lineno)d ... %(created)f ... %(asctime)r ... %(msecs)d ... %(relativeCreated)f ... %(thread)d ... %(process)d ... %(message)r ... ''',None)
To show this in action, we can instantiate a log record and then format it with our formatter:
>>> from logging import LogRecord >>> record = LogRecord(name='aname', ... level=10, ... pathname='somepath.py', ... lineno=123, ... msg='msgline%i\nmsgline%i', ... args=(1,2), ... exc_info=None) >>> print(formatter.format(record)) 'aname' 10 'DEBUG' 'somepath.py' 'somepath.py' 'somepath' 123 1167645600.000000 '2007-01-01 10:00:00,000' 0 ... ... ... 'msgline1\nmsgline2'
The example above, however, would not generate a valid email, as the subject line would contain newlines. For this reason, an additional keyword substitution is provided that is computed to be the first line of any message logged:
>>> f = SubjectFormatter('%(line)r')
We can now see how this formatter represents the log record generated previously:
>>> print(f.format(record)) 'msgline1'
As you can see, this only includes the first line of the message logged making it ideal for use in the generation of email subject lines.
Again, in order to prevent multi-line subjects, any exception information provided in a logging call is not added to the end of the subject line. This can be seen by creating a log entry as it would be by the python logging framework when an exception is logged:
>>> import sys >>> try: ... raise RuntimeException('something bad happened') ... except: ... exc_info = sys.exc_info() >>> record = LogRecord(name='aname', ... level=10, ... pathname='somepath.py', ... lineno=123, ... msg='bad things caught', ... args=(), ... exc_info=exc_info)
Normally, a logging formatter would include a traceback when representing this entry:
>>> from logging import Formatter >>> print(Formatter().format(record)) bad things caught Traceback (most recent call last): File "...", line 2, in <module> NameError: name 'RuntimeException' is not defined
However, if we use the subject formatter we previously created, the log entry is formatted as follows:
>>> print(f.format(record)) 'bad things caught'
To aid administration where the same python software runs on a cluster of machines, the hostname of the machine from which the message is logged can also be easilly included:
>>> f = SubjectFormatter('[%(hostname)s] %(line)r') >>> print(f.format(record)) [host.example.com] 'bad things caught'
Available LogRecord attributes¶
The attributes of the
LogRecord control what can be
included in the format string of any
The LogRecord attributes documentation gives full details of all
of these attributes, but the following table shows the ones added by
The first line of the message that was logged.
The hostname of the machine from which the message is logged.