Observability tooling often means juggling multiple components: collectors, backends, storage engines, and UI dashboards. otel-gui takes a different approach by collapsing the trace pipeline into a single Node.js process that acts as both the OTLP collector endpoint and the trace viewer. This setup targets local development and debugging workflows, offering immediate trace rendering without the usual complexity.
How otel-gui works as a trace viewer and OTLP collector
otel-gui is designed as a lightweight, zero-configuration OpenTelemetry trace viewer specifically for local development. It functions as a drop-in replacement for an OTLP collector endpoint, accepting OTLP/HTTP payloads on the standard port 4318. The server handles both JSON and Protobuf payloads, making it compatible with typical OpenTelemetry exporters.
The UI is built with Svelte, a modern frontend framework known for its minimal runtime and efficient reactivity. The backend uses Node.js to receive and process incoming traces. The traces are rendered immediately in a Honeycomb-style waterfall UI, which is a familiar model for developers used to tracing tools.
Real-time updates are powered by Server-Sent Events (SSE), pushing new trace data to the browser UI as it arrives. This enables a live, interactive experience without polling or manual refreshes.
Data storage defaults to in-memory retention, which suits ephemeral development sessions. However, otel-gui optionally supports PGlite-backed persistence for cases where developers want trace recovery after restarts. This is a lightweight SQLite-compatible storage option that balances simplicity with durability.
The UI also provides a service map view showing metrics like p50/p99 latency and error rates per service, a span search with attribute highlighting, keyboard navigation, and correlated log viewing. Import and export of trace data in OTLP JSON envelope format are supported, facilitating sharing or offline analysis.
Technical strengths and design tradeoffs
What sets otel-gui apart is its consolidation of the entire trace collection and visualization stack into a single executable. Typical distributed tracing setups use separate components: collectors (e.g., Jaeger, Tempo), storage backends (e.g., ClickHouse), and UI layers. Each adds operational overhead and configuration complexity.
By combining the OTLP collector and the trace viewer in one Node.js process, otel-gui significantly simplifies the development experience. Developers can instrument their apps to export traces directly to localhost:4318 and immediately see them visualized, without deploying or configuring any external services.
The choice of SSE for real-time UI updates is pragmatic: it’s simpler to implement than full WebSocket support and works well for pushing event streams in a single direction (server to client). This matches the natural flow of trace data.
The in-memory storage default is a clear tradeoff favoring speed and simplicity over durability. For local development, traces don’t usually need long-term persistence. However, the optional PGlite persistence addresses the use case where developers want to keep trace data across restarts.
The codebase uses TypeScript with Svelte on the frontend and Node.js on the backend. This stack offers good DX and fast iteration cycles, though it may not suit production environments at scale or high throughput. However, otel-gui is explicitly targeted at local dev rather than heavy production workloads.
The UI features like the service map and span search improve trace exploration ergonomics, which is often a weak spot in minimal tracing tools. The correlated log viewing enhances context when debugging distributed requests.
Quick start
Requires: Node.js ≥ 20, pnpm
git clone https://github.com/metafab/otel-gui
cd otel-gui
pnpm install
pnpm dev
This starts the development server on port 4318. Open http://localhost:4318 in your browser to access the trace viewer. The OTLP collector endpoint is live at the same address.
Alternatively, install with Homebrew from the custom tap:
brew install metafab/tap/otel-gui
Then run:
otel-gui
For containerized usage, pull and run the published Docker image:
docker pull ghcr.io/metafab/otel-gui:latest
docker run --rm --name otel-gui -p 4318:4318 ghcr.io/metafab/otel-gui:latest
You can override the port by setting the PORT environment variable in Docker, but 4318 is recommended for zero-config OTLP exporters.
verdict
otel-gui is a practical tool for developers who want a no-fuss way to visualize OpenTelemetry traces locally without spinning up a full observability stack. Its zero-config OTLP collector endpoint combined with a live-updating UI provides immediate feedback on distributed traces.
It’s not a replacement for production-grade tracing backends or long-term storage solutions. The in-memory default storage and single-process architecture limit scalability and durability. Also, the focus on local development means it lacks advanced multi-user or security features.
That said, for debugging and iterating on instrumentation in local or isolated environments, otel-gui delivers a clean, developer-friendly experience. Its minimal dependencies and easy deployment paths (pnpm, Homebrew, Docker) lower the barrier to entry.
If you find running Jaeger or Tempo too heavy for your dev workflow, otel-gui is worth keeping in your toolkit. It trades off scale and persistence for simplicity and speed, which is exactly what local tracing needs.
Related Articles
- SigNoz: OpenTelemetry-native observability with unified ClickHouse backend — SigNoz is an open-source observability platform that unifies logs, metrics, and traces using ClickHouse as a single data
- Crawlee: a TypeScript library for stealthy web scraping and browser automation — Crawlee is a TypeScript library for web scraping and browser automation with human-like stealth. Supports Playwright, Pu
- Otakuapuri: a Python desktop app for manga and anime with Cloudflare-bypass scraping and responsive Tkinter UI — Otakuapuri is a Python Tkinter app combining manga download, reading, and anime streaming with Cloudflare-bypass scrapin
- Sampler: lightweight terminal telemetry with Go-powered sparklines — Sampler is a Go CLI tool for terminal telemetry, visualizing server metrics via sparklines from various data sources. Ea
- cc-gateway: optimizing Claude Code API usage with a reverse proxy for telemetry normalization and cost savings — CC Gateway is a TypeScript reverse proxy for Claude Code that normalizes telemetry and device identity, strips billing h
→ GitHub Repo: metafab/otel-gui ⭐ 130 · TypeScript