twisted.logger

package documentation
(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:
        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.

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 _interfaces Logger interfaces.
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 a twisted.python.log.ILogObserver.
Class LimitedHistoryLogObserver ILogObserver that stores events in a buffer of a fixed size:
Class LogBeginner No summary
Variable LogEvent Undocumented
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 text. 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 text, 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 Undocumented
Variable globalLogPublisher Undocumented
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.
Variable timeFormatRFC3339 Undocumented
Variable _loggerFor Undocumented
globalLogPublisher = (source)

Undocumented

globalLogBeginner = (source)

Undocumented

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

Formats an event as text, 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: LogEvent)
ReturnsA formatted string. (type: str)
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 "{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 "#". Each defaults to "-" is not set.
  • event is the event, as formatted by formatEvent.

Example:

    >>> from time import time
    >>> from twisted.logger import formatEventAsClassicLogText
    >>> from twisted.logger import LogLevel
    >>>
    >>> formatEventAsClassicLogText(dict())  # No format, returns None
    >>> formatEventAsClassicLogText(dict(log_format="Hello!"))
    u'- [-#-] Hello!\n'
    >>> formatEventAsClassicLogText(dict(
    ...     log_format="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="Hello!",
    ...     log_time=time(),
    ...     log_system="my_system",
    ... ))
    u'2013-11-11T17:22:06-0800 [my_system] Hello!\n'
    >>>
Parameterseventan event. (type: LogEvent)
formatTimeA time formatter (type: Callable[[Optional[float]], str])
ReturnsA formatted event, or None if no output is appropriate. (type: Optional[str])
def formatTime(when, timeFormat=timeFormatRFC3339, default='-'): (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. (type: Optional[float])
timeFormatA time format. (type: Optional[str])
defaultText to return if when or timeFormat is None. (type: str)
ReturnsA formatted time. (type: str)
timeFormatRFC3339 = (source)

Undocumented

(type: str)
def eventAsText(event, includeTraceback=True, includeTimestamp=True, includeSystem=True, formatTime=formatTime): (source)

Format an event as text. Optionally, attach timestamp, traceback, and system information.

The full output format is: "{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 "#". Each defaults to "-" 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: LogEvent)
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[[float], str])
ReturnsA formatted string with specified options. (type: str)
Present SinceTwisted 18.9.0
LogEvent = (source)

Undocumented

_loggerFor = (source)

Undocumented

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 text data. Otherwise, UTF-8 bytes will be used. (type: IO[Any])
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 "-" is used. (type: Optional[str])
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: LogEvent)
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: str)
def eventFromJSON(eventText): (source)

Decode a log event from JSON.

ParameterseventTextThe output of a previous call to eventAsJSON (type: str)
ReturnsA reconstructed version of the log event. (type: JSONDict)
def jsonFileLogObserver(outFile, recordSeparator='\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 ("\n"). RS is a record separator. By default, this is a single RS character ("\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 str data. Otherwise, UTF-8 bytes will be used. (type: IO[Any])
recordSeparatorThe record separator to use. (type: str)
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 str or UTF-8 bytes. (type: IO[Any])
recordSeparatorThe expected record separator. If None, attempt to automatically detect the record separator from one of "\x1e" or "". (type: Optional[str])
bufferSizeThe size of the read buffer used while reading from inFile. (type: int)
ReturnsLog events as read from inFile. (type: Iterable[LogEvent])
@contextmanager
def capturedLogs(): (source)

Undocumented

ReturnsUndocumented (type: Iterator[Sequence[LogEvent]])
API Documentation for Twisted, generated by pydoctor 20.12.1 at 2021-02-28 19:53:36.