twisted.logger.__init_

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 `ILogFilterPredicate`s.
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.
Function	capturedLogs	Undocumented

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.

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.

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.

Parameters	event	A logging event. (type: `dict`)
Returns	A 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'
   >>>

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

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

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

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.

Parameters	event	A logging event. (type: `dict`)
	includeTraceback	If true and a `"log_failure"` key exists, append a traceback. (type: `bool`)
	includeTimestamp	If true include a formatted timestamp before the event. (type: `bool`)
	includeSystem	If true, include the event's `"log_system"` value. (type: `bool`)
	formatTime	A time formatter (type: `callable` that takes an `event` argument and returns a `unicode`)
Returns	A formatted string with specified options. (type: `unicode`)
Present Since	Twisted 18.9.0

def textFileLogObserver(outFile, timeFormat=timeFormatRFC3339):

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

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.

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

def eventFromJSON(eventText):

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

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

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

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.

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

@contextmanager
def capturedLogs():

Undocumented

API Documentation for twisted, generated by pydoctor at 2020-03-25 17:34:30.

twisted.logger.__init__ module documentation

`twisted.logger.init` module documentation