Eliot is a Python logging library that records causal chains of actions rather than a flat stream of unrelated factoids, and it is for Python developers and scientific-computing teams who need to answer why a code path ran, why an error happened, or where time went.

What it is

Eliot is a logging system for Python that models application behaviour as a tree of actions. Each action can spawn child actions, and every action eventually either succeeds or fails, so the emitted logs form the story of what the software did and what caused it. Instead of writing lines of text to a stream, the application describes its work in terms of actions, and Eliot serialises that structure.

The concrete problem it solves is causation. Python's built-in logging module and similar systems output a stream of factoids that are interesting but do not explain what is going on: standard logging cannot answer why an application is slow, what caused a particular code path to be chosen, or why an error happened. Eliot replaces that flat, uncorrelated stream with causal chains, so a developer can pinpoint performance bottlenecks, understand what happened when, and see who called what. It lives in the Python ecosystem and is distributed on PyPI and conda-forge.

Key capabilities

• Action-based causal logging, where actions spawn other actions and each one ends in success or failure, producing a traceable narrative rather than isolated lines.
• Causal tracing across a distributed system, so work spanning multiple processes can still be related back to its origin.
• Built-in support for NumPy and Dask, aimed at scientific-computing workloads.
• Support for asyncio and Trio coroutines, plus the Twisted networking framework.
• Task UUIDs that can be attached to downstream error reports; the README testimonial describes sending Eliot task UUIDs to Sentry so a notification links back to a high-level trace with metadata at each operation.
• Structured log output designed to be aggregated and stored by tools such as Logstash and ElasticSearch when running across multiple machines.
• Runs on Python 3.10 through 3.14, and on PyPy 3.11.

Who uses it and how

• Single-process Python applications that need to explain their own control flow and timing.
• Distributed systems where causal tracing has to cross process and machine boundaries, with logs shipped onward to an aggregation stack.
• Scientific-computing pipelines using NumPy and Dask, where understanding which stage is slow matters as much as the result.
• Asynchronous services built on asyncio, Trio, or Twisted, where interleaved coroutines make conventional log streams hard to read.
• Teams that already route errors to Sentry and want each notification to resolve to a trace with per-operation metadata, as described in the README testimonial.

Getting started

Install from PyPI with pip install eliot, or from conda-forge. Commercial support is available from Python⇒Speed.

How it compares

The nearest named alternative in the project's own framing is Python's built-in logging, which Eliot characterises as producing a stream of factoids that cannot answer why questions. Logstash and ElasticSearch are not competitors but complements: Eliot generates the logs, and those tools aggregate and store them once multiple processes or machines are involved.

When to use it — and when not to

A self-hoster running several processes across several machines must also operate an aggregation stack such as Logstash and ElasticSearch, because Eliot only generates logs and does not store or search them. Anyone wanting a turnkey hosted observability product, or a team unwilling to instrument code in terms of actions, should look elsewhere. The project carries 120 open issues and is maintained by a single person, Itamar Turner-Trauring, which is a real bus-factor consideration despite the recent commit activity.

"Eliot has made tracking down causes of failure (in complex external integrations and internal uses) tremendously easier. Our errors are logged to Sentry with the Eliot task UUID. That means we can go from a Sentry notification to a high-level trace of operations—with important metadata at each operation—in a few seconds. We immediately know which user did what in which part of the system."

—Jonathan Jacobs