the magic log object
InternalLogger for reporting errors within Twiggy itself
InternalLogger for use by developers writing extensions to Twiggy
Add multiple emitters. tuples should be (name_of_emitter, min_level, filter, output). The last three are passed to Emitter.
Quickly set up emitters.
Parameters: |
|
---|
Optional additions of logging functionality
Logging feature to add information about process, etc.
Adds the following fields:
Hostname : | current hostname |
---|---|
Pid : | current process id |
Thread : | current thread name |
Logging feature to add information about a socket
Adds the following fields:
ip_addr: numeric IP address port: port number host: peer hostname, as returned by getnameinfo() service: the human readable name of the service on port
Parameters: | s (socket) – the socket to extract information from |
---|
A filter is any function that takes a Message and returns True if it should be emitted.
create a filter intelligently
You may pass:
None, True: the filter will always return True False: the filter will always return False string: compiled into a regex regex: match() against the message text callable: returned as is list: apply msgFilter to each element, and all() the results
Return type: | filter function |
---|
create a filter, which gives True if the messsage’s name equals any of those provided
names will be stored as an attribute on the filter.
Parameters: | names (strings) – names to match |
---|---|
Return type: | filter function |
Formats are single-argument callables that take a Message and return an object appropriate for the Output they are assigned to.
string to separate line parts. Defaults to :.
string to prepend to traceback lines. Defaults to \nTRACE.
Set to '\\n' (double backslash n) to roll up tracebacks to a single line.
ConversionTable used to format fields. Defaults to line_conversion
format the text part of a message
format the fields of a message
format the traceback part of a message
a default line-oriented ConversionTable. Produces a nice-looking string from fields.
Fields are separated by a colon (:). Resultant string includes:
time: in iso8601 format (required) level: message level (required) name: logger name
Remaining fields are sorted alphabetically and formatted as key=value
a default LineFormat for output to a file. Sample output.
Fields are formatted using line_conversion and separated from the message text by a colon (:). Traceback lines are prefixed by TRACE.
a default line-oriented ConversionTable for use in the shell. Returns the same string as line_conversion but drops the time field.
a default LineFormat for use in the shell. Same as line_format but uses shell_conversion for fields.
Levels include (increasing severity): DEBUG, INFO, WARNING, ERROR, CRITICAL, DISABLED
A log level. Users should not create new instances.
Levels are opaque; they may be compared to each other, but nothing else.
convert time to ISO 8601 format - it sucks less!
Parameters: | gmtime (time.struct_time) – time tuple. If None, use time.gmtime() (UTC) |
---|
XXX timezone is not supported
return the name of the current thread
Holder for ConversionTable items
Variables: |
|
---|
Convert data dictionaries using Converters
For each item in the dictionary to be converted:
Users may override genericValue/genericItem/aggregate by subclassing or assigning a new function on a ConversionTable instance.
Really, it’s pretty intuitive.
Parameters: | seq – a sequence of Converters |
---|
You may also pass 3-or-4 item arg tuples or kwarg dicts (which will be used to create Converters)
do the conversion
Parameters: | d (dict) – the data to convert. Keys should be strings. |
---|
make an independent copy of this ConversionTable
return the first converter for key
return a list of all converters for key
delete the all of the converters for key
Loggers should not be created directly by users; use the global log instead.
Base class for loggers
dictionary of bound fields for structured logging. By default, contains a single field time with value time.gmtime(). This function will be called for each message emitted, populating the field with the current time.struct_time.
bind fields for structured logging. kwargs are interpreted as names/values of fields.
bind fields for structured logging. Use this instead of fields if you have keys which are not valid Python identifiers.
Parameters: | d (dict) – dictionary of fields. Keys should be strings. |
---|
convenience method to enable traceback logging
convenvience method to bind name field
convenience method for structured logging. Calls fields() and emits at info
convenience method for structured logging. Use instead of struct if you have keys which are not valid Python identifiers.
Parameters: | d (dict) – dictionary of fields. Keys should be strings. |
---|
The following methods cause messages to be emitted. format_spec is a template string into which args and kwargs will be substitued.
Emit at DEBUG level
Emit at INFO level
Emit at WARNING level
Emit at ERROR level
Emit at CRITICAL level
Logger for end-users. The type of the magic log
Filter on format_spec. For optimization purposes only. Should have the following signature:
Should the message be emitted.
add a feature to the class
Parameters: |
|
---|
disable a feature.
A method will still exist by this name, but it won’t do anything.
Parameters: | name (string) – the name of the feature to disable. |
---|
delete a feature entirely
Parameters: | name (string) – the name of the feature to remove |
---|
A logging message. Users never create these directly.
Changed in version 0.4.1: Pass args/kwargs as list/dict instead of via */** expansion.
The constructor takes a dict of options to control message creation. In addition to suppress_newlines, the following options are recognized:
trace: control traceback inclusion. Either a traceback tuple, or one of the strings always, error, in which case a traceback will be extracted from the current stack frame. style: the style of template used for format_spec. One of braces, percent, dollar.
Any callables passed in fields, args or kwargs will be called and the returned value used instead. See dynamic messages.
All attributes are read-only.
dictionary of structured logging fields. Keys are string, values are arbitrary. A level item is required.
should newlines be escaped in output. Boolean.
a stringified traceback, or None.
the human-readable message. Constructed by substituting args/kwargs into format_spec. String.
Parameters: |
|
---|
a callable taking a Message and formatting it for output. None means return the message unchanged.
Class variable, indicating that locks should be used when running in a synchronous, multithreaded environment. Threadsafe subclasses may disable locking for higher throughput. Defaults to True.
Parameters: |
|
---|
New in version 0.4.1: Add the close_atexit parameter.
Finalize the output.
The following methods should be implemented by subclasses.
Acquire any resources needed for writing (files, sockets, etc.)
Do the work of writing
Parameters: | x – an implementation-dependent object to be written. |
---|
An Output with support for asynchronous logging.
Inheriting from this class transparently adds support for asynchronous logging using the multiprocessing module. This is off by default, as it can cause log messages to be dropped.
Parameters: | msg_buffer (int) – number of messages to buffer in memory when using asynchronous logging. 0 turns asynchronous output off, a negative integer means an unlimited buffer, a positive integer is the size of the buffer. |
---|
Output messages to a file
name, mode, buffering are passed to open()
Output to an externally-managed stream.
The stream will be written to, but otherwise left alone (i.e., it will not be closed).
An output that just discards its messages
an output that stuffs messages in a list
Useful for unittesting.
Variables: | messages (list) – messages that have been emitted |
---|
Changed in version 0.4.1: Replace DequeOutput with more useful ListOutput.