# tracetree

> Fetch and display a trace from Tempo as a tree visualization. Use this when the user wants to view trace details, debug distributed operations, or analyze span hierarchies.

- Author: Gezim Basha
- Repository: gezibash/arc
- Version: 20260126154544
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/gezibash/arc
- Web: https://mule.run/skillshub/@@gezibash/arc~tracetree:20260126154544

---

---
name: tracetree
description: Fetch and display a trace from Tempo as a tree visualization. Use this when the user wants to view trace details, debug distributed operations, or analyze span hierarchies.
argument-hint: span <trace_id> | last --since <duration>
allowed-tools:
  - Bash(python3:*)
  - Bash(curl:*)
  - Read
---

# Trace Tree Visualization

This skill fetches traces from Tempo and displays them as an interactive tree or lists recent traces.

## Commands

### Show a trace (interactive by default)

Display a specific trace in an interactive TUI:

```bash
python3 .claude/skills/tracetree/tracetree.py span <trace_id>
```

Plain text output (non-interactive):

```bash
python3 .claude/skills/tracetree/tracetree.py span <trace_id> --no-interactive
```

### List recent traces (interactive by default)

Browse recent traces in an interactive TUI:

```bash
python3 .claude/skills/tracetree/tracetree.py last --since 5m
python3 .claude/skills/tracetree/tracetree.py last --since 1h --limit 20
```

Plain table output (non-interactive):

```bash
python3 .claude/skills/tracetree/tracetree.py last --since 1h --no-interactive
```

Options:
- `--since`, `-s`: Time range (e.g., `5m`, `1h`, `30s`, `1d`). Default: `5m`
- `--limit`, `-n`: Maximum traces to show. Default: `10`
- `--no-interactive`: Disable TUI, use plain text output

## Environment

- `TEMPO_URL`: Tempo endpoint (default: `http://tempo.orb.local:3200`)
- `LOKI_URL`: Loki endpoint for fetching correlated logs

## Interactive Mode

### Trace List View

Browse recent traces with keyboard navigation:

| Key | Action |
|-----|--------|
| `Up/Down` | Navigate traces |
| `Enter` | Open selected trace in span view |
| `r` | Refresh list |
| `q` | Quit |

### Span Tree View

Explore a single trace with hierarchical navigation:

| Key | Action |
|-----|--------|
| `Up/Down` | Navigate spans |
| `Space` | Expand/collapse span |
| `Enter` | Focus span (show details in panel) |
| `e` | Toggle error-only filter |
| `s` | Sort by duration (slowest first) |
| `Escape` | Back to trace list (if came from list) |
| `q` | Quit |

### Visual Indicators

- **Duration colors**: green (<10ms), yellow (10-100ms), red (>100ms)
- **Log levels**: ERROR=red, WARN=yellow, INFO=green, DEBUG=cyan
- **Error spans**: Red `!` indicator in tree
- **Collapsed**: `>` prefix, Expanded: `v` prefix

## Features

### Tree view (`span` command)
- Interactive navigation through span hierarchy
- Inline log entries under each span
- Details panel showing attributes and metadata
- Filter to show only error spans
- Sort spans by duration to find slow operations

### List view (`last` command)
- Interactive table with recent traces
- Columns: Time (with relative), Root Span, Duration, Span count
- Color-coded durations (green < 10ms, yellow < 100ms, red > 100ms)
- Press Enter to drill into any trace

### Non-interactive mode
- Use `--no-interactive` for plain text output
- Useful for scripting or piping to other commands
- Supports correlating JSON logs from stdin:

```bash
cat logs.jsonl | python3 .claude/skills/tracetree/tracetree.py span <trace_id> --no-interactive
```

## Running with uv

Use `uv run` to automatically handle dependencies (no install step):

```bash
uv run .claude/skills/tracetree/tracetree.py last --since 5m
uv run .claude/skills/tracetree/tracetree.py span <trace_id>
```

The script uses inline dependencies (PEP 723), so `uv` creates an isolated environment automatically.