API¶
Module for integrating Elasticsearch into Python’s logging
library.
-
class
lumberjack.
Lumberjack
(hosts=None, elasticsearch=None, config=None)¶ This is the initialisation point for using the lumberjack library.
In the intended use-case, this class is instantiated once and creates handlers for use with Python’s logging module.
For each type of log you want to store, you should provide a schema. If you don’t, nothing bad will happen, but it makes your cluster rather space-inefficient by default.
You should provide either a list of Elasticsearch hosts, or an already-instantiated
Elasticsearch
object from elasticsearch-py.Parameters: - hosts – A list of Elasticsearch nodes to connect to, in the form
[{'host': '127.0.0.1', 'port': 9200}]
. This is passed directly to elasticsearch.Elasticsearch. - elasticsearch – As an alternative to hosts, an already-instantiated
elasticsearch.Elasticsearch
object, perhaps with custom transports etc. - config – A configuration for Lumberjack. See the Configuration section in the docs for details.
-
get_handler
(suffix_format='%Y.%m')¶ Spawn a new logging handler.
You should use this method to get a
logging.Handler
object to attach to alogging.Logger
object.Note: It is almost definitely unwise to set the formatter of this handler yourself. The integrated formatter prepares documents ready to be inserted into Elasticsearch. Parameters: suffix_format – The time format string to use as the suffix for the indices. By default your indices will be called, e.g., generic-logging-2014.09
.
-
register_schema
(logger, schema)¶ Register a new log entry schema.
It is a good idea to register a ‘schema’ for every logger that you attach a handler to. This helps Elasticsearch store the data you provide optimally.
Note: This method will block until the mapping is registered with Elasticsearch, so you should do it in your initialisation.
Parameters: - logger – The name of the logger this schema will apply to.
- schema – The schema to be used.
-
trigger_flush
()¶ Manually trigger a flush of the log queue.
Note: This is not guaranteed to flush immediately; it merely cancels the wait before the next flush in the ActionQueue
thread.
- hosts – A list of Elasticsearch nodes to connect to, in the form
-
lumberjack.
get_default_config
()¶ Get a copy of the default config.
The copy can be modified in-place without affecting the default config itself.