[Feature] CLI / TUI for Real-Time Distributed Log Tailing and Search

[ElioNeto]

Context

A major challenge in polyglot microservice architectures is observability during local development. Developers running a vyx project must currently tail multiple terminal windows — one for the Go Core, one per Node.js worker, one per Python worker — which is a terrible experience.

vyx has an opportunity to stand out by providing an AWS CloudWatch Logs Insights-like experience directly in the terminal, aggregating logs from all processes in a single, interactive view.

The Problem

  Terminal 1        Terminal 2         Terminal 3
 ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
 │  Go Core logs  │   │ node:api logs  │   │ python:ml logs │
 │  (zap JSON)    │   │ (console.log)  │   │ (print/logging)│
 └──────────────┘   └──────────────┘   └──────────────┘
       ↑                  ↑                   ↑
  no correlation       no correlation      no correlation

Even with structured logging (#53), the developer still needs a tool to aggregate and navigate these streams.

Proposed Solution

Build a dedicated TUI (Terminal User Interface) as a vyx subcommand (vyx logs) or a standalone binary (vyx-tui). It aggregates structured JSON logs from the Go Core and all connected workers into a single, interactive terminal view.

Recommended Stack

Go + charmbracelet/bubbletea is the recommended choice for consistency with the existing Go Core codebase. Alternatively, Rust + ratatui is also an excellent option and welcome as a contribution.

Key Features (MVP)

1. Unified Log Stream

Display logs from Go Core and all workers in a single, chronologically ordered and scrollable view.

┌─ vyx logs ────────────────────────────────────────────────────────────────────┐
│ 21:00:01 [CORE    ] INFO  HTTP server listening addr=:8080             │
│ 21:00:02 [go:api  ] INFO  Connected to core via /tmp/vyx/go:api.sock   │
│ 21:00:02 [node:api] INFO  Connected to core via /tmp/vyx/node:api.sock │
│ 21:00:05 [CORE    ] INFO  GET /api/hello ─ 200 ─ 1.2ms req=abc-123      │
│ 21:00:05 [go:api  ] INFO  Hello handler called user=user-42 req=abc-123 │
└─ Filter: _________________________ [Workers: ALL] ────────────────────┘

2. Visual Differentiation

Color-code log entries by origin layer:

Source	Color
Core	Blue
Go workers	Cyan
Node.js workers	Green
Python workers	Yellow
ERROR level (any)	Red

3. Interactive Filtering

• Filter live stream by req_id or correlation_id — great for tracing a single request end-to-end
• Full-text search in the log buffer
• Toggle visibility of individual workers (e.g., "show only node:api")
• Level filter (e.g., "show only WARN and ERROR")

Architecture Notes

The TUI reads structured JSON logs (defined in #53) from:

• The Go Core's stdout/stderr
• Each spawned worker's stdout/stderr (which the Core already captures as the parent process)

The simplest integration: vyx dev streams all worker output to the TUI via pipes or a local Unix socket.

Acceptance Criteria (MVP)

• Decision made on language/framework (Go/Bubbletea recommended)
• TUI reads and parses the unified structured JSON log format (from [Feature] Standardized Structured Logging across Polyglot Workers #53)
• Logs displayed in a scrollable, chronologically ordered, color-coded view
• Interactive input box to filter logs by req_id
• Toggle to show/hide individual workers
• vyx logs subcommand or vyx dev --tui flag launches the TUI
• Works on Linux, macOS, and Windows Terminal

Good First Issues (after MVP)

Once the MVP is merged, these can be broken into separate good first issue tasks:

• Export filtered log view to a file (vyx logs --export=session.json)
• Show worker health status in a sidebar (CPU, memory, restart count)
• Clickable req_id to auto-filter the stream

Dependencies

• Requires: [Feature] End-to-End Request Tracing (Correlation IDs) across Go Core and Workers #52 — End-to-End Request Tracing (Correlation IDs)
• Requires: [Feature] Standardized Structured Logging across Polyglot Workers #53 — Standardized Structured Logging (JSON schema must be defined first)

---

💡 Looking for contributors! This is a great issue for anyone interested in building CLI/TUI tools in Go or Rust. If you want to claim this, leave a comment and we’ll get you set up with context on the log schema and IPC architecture.