twisted.logger package documentation

Part of twisted

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.

Package test Unit tests for twisted.logger.
Module _buffer Log observer that maintains a buffer.
Module _capture Context manager for capturing logs.
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 ILogFilterPredicates.
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

ILogObserver that stores events in a buffer of a fixed size:
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 capturedLogs Undocumented
Function eventAsJSON Encode an event as JSON, flattening it if necessary to preserve as much structure as possible.
Function eventAsText Format an event as a unicode string. Optionally, attach timestamp, traceback, and system information.
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.
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):

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):

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):

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'-'):

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):

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):

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):

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):

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'):

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):

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)
@contextmanager
def capturedLogs():
Undocumented
API Documentation for twisted, generated by pydoctor at 2020-03-25 17:34:30.