twisted.logger
package documentationtwisted
View Source
Twisted Logger: Classes and functions to do granular logging.
Example usage in a module some.module
:
from twisted.logger import Logger log = Logger() def handleData(data): log.debug("Got data: {data!r}.", data=data)
Or in a class:
from twisted.logger import Logger class Foo(object): log = Logger() def oops(self, data): self.log.error("Oops! Invalid data from server: {data!r}", data=data)
Logger
s have namespaces, for which logging can be
configured independently. Namespaces may be specified by passing in a
namespace
argument to Logger
when
instantiating it, but if none is given, the logger will derive its own
namespace by using the module name of the callable that instantiated it,
or, in the case of a class, by using the fully qualified name of the
class.
In the first example above, the namespace would be
some.module
, and in the second example, it would be
some.module.Foo
.
Module | _buffer | Log observer that maintains a buffer. |
Module | _file | File log observer. |
Module | _filter | Filtering log observer. |
Module | _flatten | Code related to "flattening" events; that is, extracting a description of all relevant fields from the format string and persisting them for later examination. |
Module | _format | Tools for formatting logging events. |
Module | _global | This module includes process-global state associated with the logging system, and implementation of logic for managing that global state. |
Module | _io | File-like object that logs. |
Module | _json | Tools for saving and loading log events in a structured format. |
Module | _legacy | Integration with twisted.python.log . |
Module | _levels | Log levels. |
Module | _logger | Logger class. |
Module | _observer | Basic log observers. |
Module | _stdlib | Integration with Python standard library logging. |
Module | _util | Logging utilities. |
From the __init__.py
module:
Class | FileLogObserver | Log observer that writes to a file-like object. |
Class | FilteringLogObserver | ILogObserver
that wraps another ILogObserver , but
filters out events based on applying a series of ILogFilterPredicate s. |
Interface | ILogFilterPredicate | A predicate that determined whether an event should be logged. |
Interface | ILogObserver | An observer which can handle log events. |
Class | InvalidLogLevelError | Someone tried to use a LogLevel that is
unknown to the logging system. |
Class | LegacyLogObserverWrapper | ILogObserver
that wraps an twisted.python.log.ILogObserver . |
Class | LimitedHistoryLogObserver |
|
Class | LogBeginner | No summary |
Class | LogLevel | Constants describing log levels. |
Class | LogLevelFilterPredicate | ILogFilterPredicate
that filters out events with a log level lower than the log level for the
event's namespace. |
Class | LogPublisher | ILogObserver that fans out events to other observers. |
Class | Logger | A Logger emits log
messages to an observer. You should instantiate it as a class or module
attribute, as documented in this
module's documentation . |
Class | LoggingFile | File-like object that turns write() calls into logging
events. |
Class | PredicateResult | Predicate results. |
Class | STDLibLogObserver | Log observer that writes to the python standard library's
logging module. |
Function | eventAsJSON | Encode an event as JSON, flattening it if necessary to preserve as much structure as possible. |
Function | eventFromJSON | Decode a log event from JSON. |
Function | eventsFromJSONLogFile | Load events from a file previously saved with jsonFileLogObserver .
Event records that are truncated or otherwise unreadable are ignored. |
Function | extractField | Extract a given format field from the given event. |
Function | formatEvent | Formats an event as a unicode ,
using the format in event["log_format"] . |
Function | formatEventAsClassicLogText | Format an event as a line of human-readable text for, e.g. traditional log file output. |
Function | formatTime | Format a timestamp as text. |
Variable | globalLogBeginner | The LogBeginner
used to activate the main log observer, whether it's a log file, or an
observer pointing at stderr. (type: LogBeginner ) |
Variable | globalLogPublisher | The LogPublisher that
all Logger instances
that are not otherwise parameterized will point to by default. (type: LogPublisher ) |
Function | jsonFileLogObserver | Create a FileLogObserver
that emits JSON-serialized events to a specified (writable) file-like
object. |
Function | textFileLogObserver | Create a FileLogObserver
that emits text to a specified (writable) file-like object. |
LogPublisher
that
all Logger
instances
that are not otherwise parameterized will point to by default. (type: LogPublisher
)
LogBeginner
used to activate the main log observer, whether it's a log file, or an
observer pointing at stderr. (type: LogBeginner
)
Extract a given format field from the given event.
Parameters | field | A string describing a format field or log key. This is the text that would
normally fall between a pair of curly braces in a format string: for
example, "key[2].attribute" . If a conversion is
specified (the thing after the "!" character in a
format field) then the result will always be unicode . (type: str
(native string)) |
event | A log event. (type: dict ) | |
Returns | A value extracted from the field. (type: object ) | |
Raises | KeyError | if the field is not found in the given event. |
Formats an event as a unicode
,
using the format in event["log_format"]
.
This implementation should never raise an exception; if the formatting cannot be done, the returned string will describe the event generically so that a useful message is emitted regardless.
Parameters | event | A logging event. (type: dict ) |
Returns | A formatted string. (type: unicode ) |
Format an event as a line of human-readable text for, e.g. traditional log file output.
The output format is u"{timeStamp} [{system}]
{event}\n"
, where:
timeStamp
is computed by calling the given
formatTime
callable on the event's
"log_time"
value
system
is the event's "log_system"
value, if set, otherwise, the "log_namespace"
and "log_level"
, joined by a
u"#"
. Each defaults to
u"-"
is not set.
event
is the event, as formatted by formatEvent
.
Example:
>>> from __future__ import print_function >>> from time import time >>> from twisted.logger import formatEventAsClassicLogText >>> from twisted.logger import LogLevel >>> >>> formatEventAsClassicLogText(dict()) # No format, returns None >>> formatEventAsClassicLogText(dict(log_format=u"Hello!")) u'- [-#-] Hello!\n' >>> formatEventAsClassicLogText(dict( ... log_format=u"Hello!", ... log_time=time(), ... log_namespace="my_namespace", ... log_level=LogLevel.info, ... )) u'2013-10-22T17:30:02-0700 [my_namespace#info] Hello!\n' >>> formatEventAsClassicLogText(dict( ... log_format=u"Hello!", ... log_time=time(), ... log_system="my_system", ... )) u'2013-11-11T17:22:06-0800 [my_system] Hello!\n' >>>
Parameters | event | an event. (type: dict ) |
formatTime | A time formatter (type: callable
that takes an event argument and returns a unicode ) | |
Returns | A formatted event, or None
if no output is appropriate. (type: unicode
or None ) |
Format a timestamp as text.
Example:
>>> from time import time >>> from twisted.logger import formatTime >>> >>> t = time() >>> formatTime(t) u'2013-10-22T14:19:11-0700' >>> formatTime(t, timeFormat="%Y/%W") # Year and week number u'2013/42' >>>
Parameters | when | A timestamp. |
timeFormat | A time format. (type: unicode
or None ) | |
default | Text to return if when or timeFormat is None . (type: unicode ) | |
Returns | A formatted time. (type: unicode ) |
Create a FileLogObserver
that emits text to a specified (writable) file-like object.
Parameters | outFile | A file-like object. Ideally one should be passed which accepts unicode
data. Otherwise, UTF-8 bytes
will be used. (type: io.IOBase ) |
timeFormat | The format to use when adding timestamp prefixes to logged events. If None ,
or for events with no "log_timestamp" key, the
default timestamp prefix of u"-" is used. (type: unicode
or None ) | |
Returns | A file log observer. (type: FileLogObserver ) |
Encode an event as JSON, flattening it if necessary to preserve as much structure as possible.
Not all structure from the log event will be preserved when it is serialized.
Parameters | event | A log event dictionary. (type: dict
with arbitrary keys and values) |
Returns | A string of the serialized JSON; note that this will contain no newline
characters, and may thus safely be stored in a line-delimited file. (type: unicode ) |
Decode a log event from JSON.
Parameters | eventText | The output of a previous call to eventAsJSON (type: unicode ) |
Returns | A reconstructed version of the log event. (type: dict ) |
Create a FileLogObserver
that emits JSON-serialized events to a specified (writable) file-like
object.
Events are written in the following form:
RS + JSON + NL
JSON
is the serialized event, which is JSON text.
NL
is a newline (u"\n"
).
RS
is a record separator. By default, this is a single RS
character (u"\x1e"
), which makes the default output
conform to the IETF draft document
"draft-ietf-json-text-sequence-13".
Parameters | outFile | A file-like object. Ideally one should be passed which accepts unicode
data. Otherwise, UTF-8 bytes
will be used. (type: io.IOBase ) |
recordSeparator | The record separator to use. (type: unicode ) | |
Returns | A file log observer. (type: FileLogObserver ) |
Load events from a file previously saved with jsonFileLogObserver
.
Event records that are truncated or otherwise unreadable are ignored.
Parameters | inFile | A (readable) file-like object. Data read from inFile should
be unicode
or UTF-8 bytes . (type: iterable of lines) |
recordSeparator | The expected record separator. If None ,
attempt to automatically detect the record separator from one of
u"\x1e" or u"" . (type: unicode ) | |
bufferSize | The size of the read buffer used while reading from inFile . (type: integer) | |
Returns | Log events as read from inFile . (type: iterable of dict ) |