or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-processing.mderrors.mdfiltering.mdindex.mdtheming.md
tile.json

tessl/pypi-eliot-tree

Render Eliot logs as an ASCII tree

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/eliot-tree@24.0.x

To install, run

npx @tessl/cli install tessl/pypi-eliot-tree@24.0.0

index.mddocs/

Eliot-tree

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.

Package Information

  • Package Name: eliot-tree
  • Language: Python
  • Installation: pip install eliot-tree

Core Imports

from eliottree import tasks_from_iterable, render_tasks

For filtering capabilities:

from eliottree import (
    filter_by_jmespath, filter_by_uuid, filter_by_start_date, filter_by_end_date,
    combine_filters_and
)

For theming and colors:

from eliottree import get_theme, apply_theme_overrides, Theme, colored, color_factory

Basic Usage

import sys
from eliottree import tasks_from_iterable, render_tasks

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

# Render tasks as ASCII tree
render_tasks(sys.stdout.write, tasks, colorize=True)

Output:

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

Architecture

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

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

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.

Capabilities

Core Processing

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.

def tasks_from_iterable(iterable): ...
def render_tasks(write, tasks, **options): ...

Core Processing

Filtering

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

def filter_by_jmespath(query): ...
def filter_by_uuid(task_uuid): ...
def filter_by_start_date(start_date): ...
def filter_by_end_date(end_date): ...
def combine_filters_and(*filters): ...

Filtering

Theming and Colors

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.

def get_theme(dark_background, colored=None): ...
def apply_theme_overrides(theme, overrides): ...
class Theme: ...
def colored(text, fg=None, bg=None, attrs=None): ...

Theming and Colors

Error Handling

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

class EliotParseError(RuntimeError): ...
class JSONParseError(RuntimeError): ...

Error Handling

Types

# From six library for Python 2/3 compatibility
text_type = str  # In Python 3, or unicode in Python 2

Command Line Interface

The package provides a comprehensive command-line tool:

# Basic usage
eliot-tree log_file.json

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

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

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

# Colorized output
eliot-tree --color-output log_file.json

# ASCII-only output
eliot-tree --ascii log_file.json