twisted.logger.__init__ module documentation

Part of twisted.logger 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)

Loggers 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.

Variable globalLogPublisher The LogPublisher that all Logger instances that are not otherwise parameterized will point to by default. (type: LogPublisher)
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)
Class InvalidLogLevelError Someone tried to use a LogLevel that is unknown to the logging system.
Class LogLevel Constants describing log levels.
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.
Function eventAsText Format an event as a unicode string. Optionally, attach timestamp, traceback, and system information.
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.
Interface ILogObserver An observer which can handle log events.
Class LogPublisher ILogObserver that fans out events to other observers.
Class LimitedHistoryLogObserver

ILogObserver that stores events in a buffer of a fixed size:
Class FileLogObserver Log observer that writes to a file-like object.
Function textFileLogObserver Create a FileLogObserver that emits text to a specified (writable) file-like object.
Class PredicateResult Predicate results.
Interface ILogFilterPredicate A predicate that determined whether an event should be logged.
Class FilteringLogObserver ILogObserver that wraps another ILogObserver, but filters out events based on applying a series of ILogFilterPredicates.
Class LogLevelFilterPredicate ILogFilterPredicate that filters out events with a log level lower than the log level for the event's namespace.
Class STDLibLogObserver Log observer that writes to the python standard library's logging module.
Class LoggingFile File-like object that turns write() calls into logging events.
Class LegacyLogObserverWrapper ILogObserver that wraps an twisted.python.log.ILogObserver.
Class LogBeginner No summary
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 jsonFileLogObserver Create a FileLogObserver that emits JSON-serialized events to a specified (writable) file-like object.
Function eventsFromJSONLogFile Load events from a file previously saved with jsonFileLogObserver. Event records that are truncated or otherwise unreadable are ignored.
globalLogPublisher =
The LogPublisher that all Logger instances that are not otherwise parameterized will point to by default. (type: LogPublisher)
globalLogBeginner =
The LogBeginner used to activate the main log observer, whether it's a log file, or an observer pointing at stderr. (type: LogBeginner)
def extractField(field, event): (source)

Extract a given format field from the given event.

ParametersfieldA 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))
eventA log event. (type: dict)
ReturnsA value extracted from the field. (type: object)
RaisesKeyErrorif the field is not found in the given event.
def formatEvent(event): (source)

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.

ParameterseventA logging event. (type: dict)
ReturnsA formatted string. (type: unicode)
def formatEventAsClassicLogText(event, formatTime=formatTime): (source)

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'
   >>>
Parameterseventan event. (type: dict)
formatTimeA time formatter (type: callable that takes an event argument and returns a unicode)
ReturnsA formatted event, or None if no output is appropriate. (type: unicode or None)
def formatTime(when, timeFormat=timeFormatRFC3339, default=u'-'): (source)

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'
   >>>
ParameterswhenA timestamp.
timeFormatA time format. (type: unicode or None)
defaultText to return if when or timeFormat is None. (type: unicode)
ReturnsA formatted time. (type: unicode)
def eventAsText(event, includeTraceback=True, includeTimestamp=True, includeSystem=True, formatTime=formatTime): (source)

Format an event as a unicode string. Optionally, attach timestamp, traceback, and system information.

The full output format is: u"{timeStamp} [{system}] {event}\n{traceback}\n" where:

  • timeStamp is the event's "log_time" value formatted with the provided formatTime callable.
  • 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.
  • traceback is the traceback if the event contains a "log_failure" key. In the event the original traceback cannot be formatted, a message indicating the failure will be substituted.

If the event cannot be formatted, and no traceback exists, an empty string is returned, even if includeSystem or includeTimestamp are true.

ParameterseventA logging event. (type: dict)
includeTracebackIf true and a "log_failure" key exists, append a traceback. (type: bool)
includeTimestampIf true include a formatted timestamp before the event. (type: bool)
includeSystemIf true, include the event's "log_system" value. (type: bool)
formatTimeA time formatter (type: callable that takes an event argument and returns a unicode)
ReturnsA formatted string with specified options. (type: unicode)
Present SinceTwisted 18.9.0
def textFileLogObserver(outFile, timeFormat=timeFormatRFC3339): (source)

Create a FileLogObserver that emits text to a specified (writable) file-like object.

ParametersoutFileA file-like object. Ideally one should be passed which accepts unicode data. Otherwise, UTF-8 bytes will be used. (type: io.IOBase)
timeFormatThe 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)
ReturnsA file log observer. (type: FileLogObserver)
def eventAsJSON(event): (source)

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.

ParameterseventA log event dictionary. (type: dict with arbitrary keys and values)
ReturnsA 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)
def eventFromJSON(eventText): (source)

Decode a log event from JSON.

ParameterseventTextThe output of a previous call to eventAsJSON (type: unicode)
ReturnsA reconstructed version of the log event. (type: dict)
def jsonFileLogObserver(outFile, recordSeparator=u'\x1e'): (source)

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".

ParametersoutFileA file-like object. Ideally one should be passed which accepts unicode data. Otherwise, UTF-8 bytes will be used. (type: io.IOBase)
recordSeparatorThe record separator to use. (type: unicode)
ReturnsA file log observer. (type: FileLogObserver)
def eventsFromJSONLogFile(inFile, recordSeparator=None, bufferSize=4096): (source)

Load events from a file previously saved with jsonFileLogObserver. Event records that are truncated or otherwise unreadable are ignored.

ParametersinFileA (readable) file-like object. Data read from inFile should be unicode or UTF-8 bytes. (type: iterable of lines)
recordSeparatorThe expected record separator. If None, attempt to automatically detect the record separator from one of u"\x1e" or u"". (type: unicode)
bufferSizeThe size of the read buffer used while reading from inFile. (type: integer)
ReturnsLog events as read from inFile. (type: iterable of dict)
API Documentation for Twisted, generated by pydoctor at 2018-10-15 19:29:43.