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 __init__.py:

Interface	`ILogFilterPredicate`	A predicate that determined whether an event should be logged.
Interface	`ILogObserver`	An observer which can handle log events.
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.
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`	A `LogBeginner` holds state related to logging before logging has begun, and begins logging when told to do so. Logging "begins" when someone has selected a set of observers, like, for example, a `FileLogObserver`...
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	`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	`PredicateResult`	Predicate results.
Class	`STDLibLogObserver`	Log observer that writes to the python standard library's `logging` module.
Exception	`InvalidLogLevelError`	Someone tried to use a `LogLevel` that is unknown to the logging system.
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.
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.
Type Alias	`LogEvent`	Undocumented
Variable	`globalLogBeginner`	Undocumented
Variable	`globalLogPublisher`	Undocumented
Variable	`timeFormatRFC3339`	Undocumented
Variable	`_loggerFor`	Undocumented

globalLogPublisher = (source) ¶

Undocumented

globalLogBeginner = (source) ¶

Undocumented

def extractField(field: str, event: LogEvent) -> Any: (source) ¶

Extract a given format field from the given event.

Parameters
field:`str`	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 str.
event:`LogEvent`	A log event.
Returns
`Any`	A value extracted from the field.
Raises
`KeyError`	if the field is not found in the given event.

def formatEvent(event: LogEvent) -> str: (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.

Parameters
event:`LogEvent`	A logging event.
Returns
`str`	A formatted string.

def formatEventAsClassicLogText(event: LogEvent, formatTime: Callable[[Optional[float]], str] = formatTime) -> Optional[str]: (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'
    >>>

Parameters
event:`LogEvent`	an event.
formatTime:`Callable[[Optional[float]], str]`	A time formatter
Returns
`Optional[str]`	A formatted event, or `None` if no output is appropriate.

def formatTime(when: Optional[float], timeFormat: Optional[str] = timeFormatRFC3339, default: str = '-') -> str: (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'
    >>>

Parameters
when:`Optional[float]`	A timestamp.
timeFormat:`Optional[str]`	A time format.
default:`str`	Text to return if `when` or `timeFormat` is `None`.
Returns
`str`	A formatted time.

timeFormatRFC3339: str = (source) ¶

Undocumented

def eventAsText(event: LogEvent, includeTraceback: bool = True, includeTimestamp: bool = True, includeSystem: bool = True, formatTime: Callable[[float], str] = formatTime) -> str: (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.

Parameters
event:`LogEvent`	A logging event.
includeTraceback:`bool`	If true and a `"log_failure"` key exists, append a traceback.
includeTimestamp:`bool`	If true include a formatted timestamp before the event.
includeSystem:`bool`	If true, include the event's `"log_system"` value.
formatTime:`Callable[[float], str]`	A time formatter
Returns
`str`	A formatted string with specified options.
Present Since
Twisted 18.9.0

LogEvent = (source) ¶

Undocumented

Value

Dict[str, Any]

_loggerFor = (source) ¶

Undocumented

def textFileLogObserver(outFile: IO[Any], timeFormat: Optional[str] = timeFormatRFC3339) -> FileLogObserver: (source) ¶

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

Parameters
outFile:`IO[Any]`	A file-like object. Ideally one should be passed which accepts text data. Otherwise, UTF-8 `bytes` will be used.
timeFormat:`Optional[str]`	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 `"-"` is used.
Returns
`FileLogObserver`	A file log observer.

def eventAsJSON(event: LogEvent) -> str: (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.

Parameters
event:`LogEvent`	A log event dictionary.
Returns
`str`	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.

def eventFromJSON(eventText: str) -> JSONDict: (source) ¶

Decode a log event from JSON.

Parameters
eventText:`str`	The output of a previous call to `eventAsJSON`
Returns
`JSONDict`	A reconstructed version of the log event.

def jsonFileLogObserver(outFile: IO[Any], recordSeparator: str = '\x1e') -> FileLogObserver: (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".

Parameters
outFile:`IO[Any]`	A file-like object. Ideally one should be passed which accepts `str` data. Otherwise, UTF-8 `bytes` will be used.
recordSeparator:`str`	The record separator to use.
Returns
`FileLogObserver`	A file log observer.

def eventsFromJSONLogFile(inFile: IO[Any], recordSeparator: Optional[str] = None, bufferSize: int = 4096) -> Iterable[LogEvent]: (source) ¶

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

Parameters
inFile:`IO[Any]`	A (readable) file-like object. Data read from `inFile` should be `str` or UTF-8 `bytes`.
recordSeparator:`Optional[str]`	The expected record separator. If `None`, attempt to automatically detect the record separator from one of `"\x1e"` or `""`.
bufferSize:`int`	The size of the read buffer used while reading from `inFile`.
Returns
`Iterable[LogEvent]`	Log events as read from `inFile`.

@contextmanager
def capturedLogs() -> Iterator[Sequence[LogEvent]]: (source) ¶

Undocumented