---
id: eliot
version: "1.18.0"
license: Apache 2.0
license_treatment: permissive
maintenance: active
---

# eliot — Logging library that tells you why it happened

License: permissive · Maintenance: active · Downloads: 94.7K/mo

## What it is and what it does

Eliot replaces Python's standard logging model with a causal-chain approach: instead of isolated log lines, it records actions that spawn other actions, ultimately succeeding or failing. This lets you trace the story of what your application did—not just what happened, but why it happened and what caused each decision or failure.

The package is designed for single-process logging, distributed tracing across systems, and scientific computing with built-in support for NumPy and Dask. It also integrates with asyncio, Trio, and Twisted for coroutine and networking contexts. For multi-machine deployments, you typically pair it with external aggregation tools to store and query logs.

Use it for:

- Pinpoint performance bottlenecks by tracing causal chains of actions and their timing.
- Debug complex failures in distributed systems by following the action chain from request to error.
- Correlate user actions across services using Eliot's task UUID in logs sent to monitoring systems.
- Instrument scientific computing workflows with NumPy and Dask to understand computation flow.
- Trace async coroutine execution in asyncio or Trio to understand concurrency issues.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Eliot is a structured logging system that outputs causal chains of actions, showing what happened in your application and why, rather than isolated log lines.

Yes. Eliot is actively maintained, has low install friction, carries no known vulnerabilities, and solves a real problem—standard logging cannot answer causal questions. It's well-suited for debugging complex systems and distributed tracing. The Apache 2.0 license is permissive. Install it if you need to understand not just what happened, but why.

## Install

pip install eliot
uv add eliot
poetry add eliot

## Installing eliot

Before you install: Low install friction with four runtime dependencies (zope.interface, pyrsistent, boltons, orjson). Actively maintained with recent commits and steady development.

License in practice: Released under Apache 2.0, a permissive license allowing commercial and private use with minimal restrictions.

Quickstart:

pip install eliot

from eliot import start_action

with start_action(action_type="my_action"):
    # your code here
    pass

Requires Python 3.10 or later (3.10, 3.11, 3.12, 3.13, 3.14, or PyPy 3.11).

Verify before relying:

- Whether the asyncio/Trio/Twisted support is production-ready or experimental.
- Performance overhead of structured logging compared to standard logging in typical workloads.
- Integration maturity with Logstash and ElasticSearch for multi-machine log aggregation.

## Package facts

- License: Apache 2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 94.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

structured logging python, causal tracing logging, distributed tracing, action-based logging, why did this happen logging, application event tracing, performance debugging logs, structured-logging, distributed-tracing, debugging

[View on SkillFed](https://skillfed.io/packages/eliot) · [View on PyPI](https://pypi.org/project/eliot/)