Eliot

1.17.5 verified Fri May 01 auth: no python

Eliot is a structured logging library for Python designed to capture causality in distributed systems. It allows you to log actions as trees, showing what caused what, and integrates with serialization formats like JSON. Current version 1.17.5, requires Python >=3.9.0. Maintained actively with minor releases every few months.

pip install eliot

Common errors

error ModuleNotFoundError: No module named 'eliot' ↓

cause Eliot is not installed in the current environment.

fix

Run 'pip install eliot' to install the package.

error TypeError: to_file() missing 1 required positional argument: 'file' ↓

cause to_file() is called without providing a file-like object.

fix

Provide a file-like object, e.g., to_file(sys.stderr) or to_file(open('log.json', 'w')).

error AttributeError: module 'eliot' has no attribute 'parse_logs' ↓

cause The parse_logs function was removed in Eliot 1.17.0.

fix

Use the eliot-tree CLI tool or parse JSON lines manually with json.loads.

Warnings

gotcha Do not mix Eliot with the standard logging module unless you configure a bridge. Using both simultaneously may result in duplicate log lines or missing log entries. ↓

fix Use eliot.logging.bridge_logging() to bridge standard logging into Eliot, or set up Eliot as the sole logging system.

breaking Before 1.17.0, the default output was JSON lines. In 1.17.0+, the default changed to human-readable output via to_console() or to_file(). If you rely on JSON parsing, explicitly call to_file(sys.stdout) with a file-like object or set output format. ↓

fix Replace log_output = sys.stdout with to_file(log_output) in your initialization code. For JSON lines, use to_file(sys.stdout, format='json').

gotcha Eliot's start_action is a context manager that automatically logs the action's start and end. If you forget to use it as a context manager (e.g., not using 'with'), the action will not be logged correctly and may cause resource leaks. ↓

fix Always use 'with start_action(...) as action:' and avoid calling start_action without entering the context.

deprecated The 'eliot.parse' module (eliot.parse_logs) is deprecated as of 1.17.0. Use the eliot-tree CLI tool or parse logs manually with json.loads instead. ↓

fix Replace from eliot.parse import parse_logs with manual JSON parsing or switch to the external eliot-tree package.

Imports

start_action
```
from eliot import start_action
```
Action
```
from eliot import Action
```
log_call
```
from eliot import log_call
```
Message
```
from eliot import Message
```
to_file
```
from eliot import to_file
```

Quickstart

Initialize Eliot with to_file() and use start_action context managers to log nested actions.

import sys
from eliot import start_action, to_file

# Send logs to stderr
log_file = sys.stderr
# If you prefer JSON to a file, use open('log.json', 'w') as f: to_file(f)
to_file(log_file)

with start_action(action_type="hello"):
    print("Hello, world!")
    with start_action(action_type="inner"):
        pass