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 a logging.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.
lumberjack.get_default_config()

Get a copy of the default config.

The copy can be modified in-place without affecting the default config itself.