TreeLogger

A tree-structured logging service. Organize log entries as hierarchical trees of nodes, browse them in a real-time web UI, and interact programmatically via a REST API, WebSocket stream, or Python client library.

Features

• Tree-structured logs -- Create named trees with a root node, then attach child nodes at any depth.
• REST API -- Full CRUD under /api/v1 for trees and nodes.
• Real-time updates -- WebSocket endpoint pushes node_created events to connected clients.
• Web UI -- Built-in single-page dashboard with dark/light theme, collapsible tree view, depth-colored borders, and live node insertion.
• Python client -- TreeLoggerClient for sync HTTP, TreeSession for convenient context-manager logging, and TreeWatcher for async WebSocket streaming.

Quickstart

Requirements

• Python 3.10+

Install

pip install -e .

Run the server

treelogger-server

The server starts on http://localhost:8000. Open it in a browser to access the web UI.

Log some data

from treelogger.client import TreeLoggerClient

with TreeLoggerClient() as client:
    session = client.session("my-first-tree")
    with session:
        # Log under root
        step1 = session.log("Starting pipeline", {"stage": "init"})

        # Log under a specific parent
        session.log_child(step1["id"], "Loaded config", {"file": "config.yaml"})
        session.log_child(step1["id"], "Connected to DB")

Watch for updates (async)

import asyncio
from treelogger.client import TreeWatcher

async def watch(tree_id: str):
    async with TreeWatcher(tree_id) as watcher:
        async for event in watcher:
            print(event)

asyncio.run(watch("TREE_ID_HERE"))

API Reference

All endpoints are prefixed with /api/v1.

Trees

Method	Path	Description
POST	/trees	Create a tree. Body: {"name": "..."}. Returns tree info with root_id.
GET	/trees	List all trees.
GET	/trees/{tree_id}	Get a tree with all its nodes.

Nodes

Method	Path	Description
POST	/trees/{tree_id}/nodes	Add a node. Body: {"parent_id": "...", "message": "...", "attributes": {}}.
GET	/trees/{tree_id}/nodes	List all nodes in a tree.
GET	/trees/{tree_id}/nodes/{node_id}	Get a single node.
GET	/trees/{tree_id}/nodes/{node_id}/children	Get direct children of a node.

WebSocket

Connect to ws://localhost:8000/ws/trees/{tree_id} to receive real-time node_created events as JSON.

Architecture

treelogger/
  server/
    app.py        # FastAPI app with lifespan (init/close DB)
    routes.py     # REST endpoints (/api/v1)
    ws.py         # WebSocket hub and endpoint
    db.py         # SQLite database layer (raw sqlite3, WAL mode)
    models.py     # Pydantic request/response models
    static/
      index.html  # Single-page web UI
  client/
    client.py     # TreeLoggerClient, TreeSession, TreeWatcher

Data is stored in a local SQLite database (treelogger.db) using WAL journal mode.

License

MIT