0
# Eliot-tree
1

2
A command-line tool and Python library for rendering Eliot structured logs as ASCII tree visualizations. Transforms flat JSON log messages into hierarchical tree structures that clearly show the relationships between different log events, making it easier to understand complex application flows and debug issues.
3

4
## Package Information
5

6
- **Package Name**: eliot-tree
7
- **Language**: Python
8
- **Installation**: `pip install eliot-tree`
9

10
## Core Imports
11

12
```python
13
from eliottree import tasks_from_iterable, render_tasks
14
```
15

16
For filtering capabilities:
17

18
```python
19
from eliottree import (
20
    filter_by_jmespath, filter_by_uuid, filter_by_start_date, filter_by_end_date,
21
    combine_filters_and
22
)
23
```
24

25
For theming and colors:
26

27
```python
28
from eliottree import get_theme, apply_theme_overrides, Theme, colored, color_factory
29
```
30

31
## Basic Usage
32

33
```python
34
import sys
35
from eliottree import tasks_from_iterable, render_tasks
36

37
# Parse Eliot message dictionaries into task objects
38
tasks = tasks_from_iterable([
39
    {"timestamp": 1425356936.278875, "uri": "http://example.org/soap", 
40
     "action_status": "started", "task_uuid": "f3a32bb3-ea6b-457c-aa99-08a3d0491ab4", 
41
     "action_type": "app:soap:client:request", "soapAction": "a_soap_action", "task_level": [1]},
42
    {"status": 200, "task_uuid": "f3a32bb3-ea6b-457c-aa99-08a3d0491ab4", 
43
     "task_level": [3], "action_type": "app:soap:client:request", 
44
     "timestamp": 1425356937.517161, "action_status": "succeeded"}
45
])
46

47
# Render tasks as ASCII tree
48
render_tasks(sys.stdout.write, tasks, colorize=True)
49
```
50

51
Output:
52
```
53
f3a32bb3-ea6b-457c-aa99-08a3d0491ab4
54
└── app:soap:client:request/1 ⇒ started 2015-03-03 04:28:56 ⧖ 1.238s
55
    ├── uri: http://example.org/soap
56
    ├── soapAction: a_soap_action
57
    └── app:soap:client:request/3 ⇒ succeeded 2015-03-03 04:28:57
58
        └── status: 200
59
```
60

61
## Architecture
62

63
Eliot-tree processes structured log data through a three-stage pipeline:
64

65
- **Parsing**: `tasks_from_iterable` converts flat Eliot message dictionaries into hierarchical task objects
66
- **Filtering**: Filter functions allow selective processing based on UUID, timestamps, or custom JMESPath queries
67
- **Rendering**: `render_tasks` transforms task objects into formatted ASCII tree output with customizable themes and styling
68

69
This design enables both programmatic usage in Python applications and command-line processing via the `eliot-tree` tool, supporting advanced filtering capabilities using JMESPath queries, timestamp ranges, and custom predicates for debugging, monitoring, and log analysis workflows.
70

71
## Capabilities
72

73
### Core Processing
74

75
Essential functions for parsing Eliot message dictionaries into task objects and rendering them as ASCII trees. These functions form the foundation of eliot-tree's functionality.
76

77
```python { .api }
78
def tasks_from_iterable(iterable): ...
79
def render_tasks(write, tasks, **options): ...
80
```
81

82
[Core Processing](./core-processing.md)
83

84
### Filtering
85

86
Advanced filtering capabilities using JMESPath queries, UUID selection, timestamp ranges, and logical combinations. Enables selective processing of log data based on various criteria.
87

88
```python { .api }
89
def filter_by_jmespath(query): ...
90
def filter_by_uuid(task_uuid): ...
91
def filter_by_start_date(start_date): ...
92
def filter_by_end_date(end_date): ...
93
def combine_filters_and(*filters): ...
94
```
95

96
[Filtering](./filtering.md)
97

98
### Theming and Colors
99

100
Comprehensive theming system with support for dark/light backgrounds, custom color schemes, and terminal color output. Provides both pre-built themes and extensible customization options.
101

102
```python { .api }
103
def get_theme(dark_background, colored=None): ...
104
def apply_theme_overrides(theme, overrides): ...
105
class Theme: ...
106
def colored(text, fg=None, bg=None, attrs=None): ...
107
```
108

109
[Theming and Colors](./theming.md)
110

111
### Error Handling
112

113
Exception classes for handling parsing errors in Eliot message dictionaries and JSON text, providing detailed error context for debugging.
114

115
```python { .api }
116
class EliotParseError(RuntimeError): ...
117
class JSONParseError(RuntimeError): ...
118
```
119

120
[Error Handling](./errors.md)
121

122
## Types
123

124
```python { .api }
125
# From six library for Python 2/3 compatibility
126
text_type = str  # In Python 3, or unicode in Python 2
127
```
128

129
## Command Line Interface
130

131
The package provides a comprehensive command-line tool:
132

133
```bash
134
# Basic usage
135
eliot-tree log_file.json
136

137
# With filtering by UUID
138
eliot-tree --task-uuid f3a32bb3-ea6b-457c-aa99-08a3d0491ab4 log_file.json
139

140
# With JMESPath filtering
141
eliot-tree --select 'action_type == `"http_client:request"`' log_file.json
142

143
# With timestamp filtering
144
eliot-tree --start 2015-03-03T04:28:00 --end 2015-03-03T04:30:00 log_file.json
145

146
# Colorized output
147
eliot-tree --color-output log_file.json
148

149
# ASCII-only output
150
eliot-tree --ascii log_file.json
151
```