Eliot: Logging for Complex & Distributed Systems

Coveralls test coverage information Build Status

Eliot is a Python logging system that outputs causal chains of actions happening within and across process boundaries: a logical trace of the system’s operation.

Eliot is released by ClusterHQ under the Apache 2.0 License. Download from PyPI, read the documentation, file bugs at Github. Need help? Join the #eliot IRC channel on irc.freenode.net.

To install:

$ pip install eliot


  • Structured, optionally-typed log messages and actions.
  • Logged actions can span processes and threads.
  • Excellent support for unit testing your code’s logging.
  • Optional Twisted support.
  • Native journald support, easily usable by Logstash/Elasticsearch.
  • Supports CPython 2.7, 3.3, 3.4, 3.5 and PyPy.

Here’s an example of using Eliot, and the output rendered by the third-party eliot-tree utility:

import sys
from eliot import start_action, to_file
import requests

def check_links(urls):
    with start_action(action_type="check_links", urls=urls):
        for url in urls:
                with start_action(action_type="download", url=url):
                    response = requests.get(url)
            except Exception as e:
                raise ValueError(str(e))

check_links(["http://google.com"], ["http://nosuchurl"])
$ python examples/linkcheck.py | eliot-tree
+-- check_links@1/started
    `-- urls: [u'http://google.com', u'http://nosuchurl']
    +-- download@2,1/started
        `-- url: http://google.com
        +-- download@2,2/succeeded
    +-- download@3,1/started
        `-- url: http://nosuchurl
        +-- download@3,2/failed
            |-- exception: requests.exceptions.ConnectionError
            |-- reason: ('Connection aborted.', gaierror(-2, 'Name or service not known'))
    +-- check_links@4/failed
        |-- exception: exceptions.ValueError
        |-- reason: ('Connection aborted.', gaierror(-2, 'Name or service not known'))


Indices and tables