otel-gui

     

A lightweight, zero-config OpenTelemetry viewer for local development — traces, logs, and metrics in one place.

Drop-in replacement for a collector endpoint — point your OTLP exporter at it and see your telemetry immediately. No database required.

✨ Features

• Zero config — listens on port 4318, the standard OTLP/HTTP port. Most exporters work without changing a single setting
• OTLP JSON & Protobuf — accepts both application/json and application/x-protobuf payloads
• Real-time streaming — traces, logs, and metrics all update live over SSE (Server-Sent Events) using an incremental snapshot + delta protocol, so views refresh in place without flicker or polling
• Traces and spans — trace list; waterfall timeline with full span details, and correlation with logs
• Logs — log list; log details view; correlation with traces
• Metrics — gauges, sums, histograms, exponential histograms, and summaries time-series charts, histogram distribution + heatmap views, and per-series filtering
• Service map — auto-generated graph of cross-service calls with error rates and latency (p50/p99)
• Search & filter — filter traces, logs and metrics by text, id, service, severity, and attributes: search spans inside a trace based on attributes, events, and span name or id
• Import/export traces — export one trace, filtered traces, or selected traces as OTLP JSON envelope; import from OTLP JSON or otel-gui export files with metadata preview before confirmation
• Bulk list actions — trace and log lists support multi-select export and split delete actions (Clear All + Delete Selected (n))
• Keyboard navigation — rich keyboard control: arrow keys for the span tree, / to search, t/l/m/s to jump to Traces/Logs/Metrics/Service Map tabs, Enter/Space to activate focused rows in the Traces and Logs grids, escape key to clear search and go back to the list, ? for shortcuts help
• Error navigation — jump between error spans with one key
• Span details — attributes, events with timeline markers, resource attributes, instrumentation scope, span links, correlated logs
• Global logs workflow — browse all logs in a dedicated tab, open full log details, and jump from logs to the owning trace/span
• Trace and log counts — the trace list shows both span and correlated log counts, and trace detail summarizes correlated logs alongside spans/services/depth
• Collapse/expand — hide subtrees in the waterfall for cleaner viewing
• Resizable panels — drag splitters to resize the waterfall name column and the span details sidebar
• Dark mode — toggle between light and dark themes
• Incremental ingestion — spans from the same trace can arrive in separate requests and out of order; the store merges them correctly
• In-memory with optional local persistence — default is in-memory only; opt into PGlite-backed restart recovery with bounded retention

📸 Screenshots

Trace list & filters

Service map

Trace detail — waterfall & span sidebar

Search highlighting

Correlated logs

Global logs

Metrics

🛠️ Quick Start

Install with Homebrew

otel-gui can be installed from a custom Homebrew tap:

brew install metafab/tap/otel-gui

Then run:

otel-gui
# or override default port (4318)
PORT=55681 otel-gui
# open the UI in your default browser on startup
otel-gui --open # or -o
# show usage
otel-gui -h # or --help

Notes:

• Homebrew formula updates are automated from tagged releases (v*) by the release workflow.

To update to the latest version, you'll use:

brew update
brew upgrade metafab/tap/otel-gui

Docker 🐳

Pull and run the published GHCR image:

docker pull ghcr.io/metafab/otel-gui:latest
docker run --rm --name otel-gui -p 4318:4318 ghcr.io/metafab/otel-gui:latest

Container tags are published from Git refs:

• latest for the default branch
• v* tags (for example, v1.1.0)
• sha-<commit> immutable tags

Build and run locally with Docker:

docker build -t otel-gui .
docker run --rm -p 4318:4318 otel-gui

Then use the standard OTLP endpoint:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Docker port configuration

The container reads PORT (default 4318). You can override it at runtime:

docker run --rm -e PORT=55681 -p 55681:55681 otel-gui

Using port 4318 is recommended for zero-config OTLP exporters.

Docker Compose

Run with Docker Compose:

docker compose up --build

Run in background:

docker compose up -d --build

Stop:

docker compose down

To use a different port:

PORT=55681 docker compose up --build

Local development

Requires: Node.js ≥ 20, pnpm

git clone https://github.com/metafab/otel-gui
cd otel-gui
pnpm install
pnpm dev

Open http://localhost:4318 — the OTLP endpoint is live at the same address.

Development commands

pnpm run dev        # Start dev server on port 4318
pnpm run lint       # Lint TypeScript, JavaScript, and Svelte files
pnpm run format     # Format files with Prettier
pnpm run format:check # Check formatting without writing changes
pnpm run check      # TypeScript type-check
pnpm run test       # Run unit tests (Vitest)
pnpm run test:watch # Tests in watch mode
pnpm run build      # Production build

Sending Traces

Point any OpenTelemetry SDK exporter at the viewer:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

No other configuration needed. The viewer accepts the standard POST /v1/traces endpoint.

Requests with Content-Encoding: gzip are also supported.

Sending Logs

The viewer also accepts OTLP logs at:

POST /v1/logs

Use the same traceId/spanId values as your spans to get correlated logs in trace detail sidebar.

Sending Metrics

The viewer also accepts OTLP metrics at:

POST /v1/metrics

Gauges, sums, histograms, exponential histograms, and summaries are all supported and appear in the Metrics tab. Sums get a server-computed per-second rate (with counter-reset detection); histograms render as both a distribution and a time/bucket heatmap.

Try the demo

Run the bundled e-commerce demo to see all features immediately:

./demo-ecommerce.sh

On Windows (PowerShell):

.\demo-ecommerce.ps1

If script execution is blocked, run it for the current shell session only:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\demo-ecommerce.ps1

This sends a realistic multi-service trace (frontend → backend-api → auth-service + database) with errors, retries, incremental span arrival across two requests, correlated logs, and staged metrics.

Run the dedicated metrics-only demo:

./demo-metrics.sh

On Windows (PowerShell):

.\demo-metrics.ps1

Manual curl examples

# Simple 3-span trace
curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d @samples/sample-trace.json

# Correlated logs for the simple trace
curl -X POST http://localhost:4318/v1/logs \
  -H "Content-Type: application/json" \
  -d @samples/sample-log.json

# E-commerce trace — part 1 (frontend + backend-api)
curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d @samples/sample-trace-ecommerce-part1.json

# E-commerce correlated logs — part 1
curl -X POST http://localhost:4318/v1/logs \
  -H "Content-Type: application/json" \
  -d @samples/sample-log-ecommerce-part1.json

# E-commerce trace — part 2 (auth-service + database with errors)
curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d @samples/sample-trace-ecommerce-part2.json

# E-commerce correlated logs — part 2
curl -X POST http://localhost:4318/v1/logs \
  -H "Content-Type: application/json" \
  -d @samples/sample-log-ecommerce-part2.json

# Trace with error spans (status.code = 2)
curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d @samples/sample-trace-error.json

# Trace with span links
curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d @samples/sample-trace-links.json

# Gauge metrics (memory usage)
curl -X POST http://localhost:4318/v1/metrics \
  -H "Content-Type: application/json" \
  -d @samples/sample-metrics-gauge.json

# Sum/Counter metrics (request count with cumulative points)
curl -X POST http://localhost:4318/v1/metrics \
  -H "Content-Type: application/json" \
  -d @samples/sample-metrics-sum-counter.json

# Histogram metrics (database latency distribution)
curl -X POST http://localhost:4318/v1/metrics \
  -H "Content-Type: application/json" \
  -d @samples/sample-metrics-histogram.json

# E-commerce metrics staged flow (part 1 then part 2)
curl -X POST http://localhost:4318/v1/metrics \
  -H "Content-Type: application/json" \
  -d @samples/sample-metrics-ecommerce-part1.json

curl -X POST http://localhost:4318/v1/metrics \
  -H "Content-Type: application/json" \
  -d @samples/sample-metrics-ecommerce-part2.json

See SAMPLE_TRACES.md for a full feature exploration guide.

⚙️ Configuration

Copy .env.example to .env to customize:

cp .env.example .env
# then edit .env

For external backend registration details, see docs/enterprise-persistence-module.md.

When OTEL_GUI_PERSISTENCE_MODE=pglite falls back to memory, check GET /api/config -> persistence.unavailableReason for a precise cause.

🏗️ Building

pnpm build
PORT=4318 node build

The production build uses @sveltejs/adapter-node. In-memory state is kept alive by the Node.js process — no external store required for local use.

In Docker, with the default configuration,traces are in-memory only and are lost when the container stops.

Self-contained executable (SEA)

otel-gui can be packaged as a self-contained executable using Node 22 SEA (Single Executable Applications).

Requirements:

• Node.js 22.x (for SEA blob generation)
• pnpm

Build for your current OS/arch:

pnpm run build
pnpm run sea:package

Generate for a specific target platform:

pnpm run sea:bundle
pnpm run sea:package:target -- --target linux-x64

Supported targets:

• linux-x64
• linux-arm64
• macos-x64
• macos-arm64
• win-x64
• win-arm64

Cross-target note:

• If target differs from your host (for example building linux-x64 on macOS), provide a matching Node 22 target binary:

pnpm run sea:package:target -- \
  --target linux-x64 \
  --node-binary /absolute/path/to/node-linux-x64

Output directory:

dist/binaries/otel-gui-<platform>/
  otel-gui[.exe]
  build/
  proto/

Run from that directory:

./otel-gui
# or override default port (4318)
PORT=55681 ./otel-gui
# open the UI in your default browser on startup
./otel-gui --open # or -o
# show usage
./otel-gui -h # or --help
# print version + platform/runtime details
./otel-gui --version # or -v

Notes:

• Keep otel-gui[.exe], build/, and proto/ together in the same output folder.
• Current OSS executable packaging targets memory mode. Optional enterprise persistence remains an external module workflow.

⌨️ Keyboard Shortcuts

📐 Architecture

POST /v1/traces          ← OTLP receiver (JSON + Protobuf)
POST /v1/logs            ← OTLP logs receiver (JSON + Protobuf)
POST /v1/metrics         ← OTLP metrics receiver (JSON + Protobuf)

GET  /api/traces         ← trace list for the UI
DELETE /api/traces       ← clear all traces or delete selected traceIds
GET  /api/traces/:id     ← single trace
GET  /api/traces/:id/logs ← trace-scoped correlated logs
GET  /api/traces/:id/logs/:logId ← single trace-scoped log detail
GET  /api/traces/:id/export ← export a single trace envelope
POST /api/traces/export  ← export filtered/selected traceIds
POST /api/traces/import/preview ← validate + preview import metadata
POST /api/traces/import  ← import otel-gui envelope or raw OTLP JSON

GET  /api/logs           ← global log list for the UI
DELETE /api/logs         ← clear all logs or delete selected logIds
GET  /api/logs/:id       ← single log detail

GET  /api/metrics        ← metric list for the UI
DELETE /api/metrics      ← clear all metrics or delete selected ids
GET  /api/metrics/:id    ← metric detail and chart data
GET  /api/metrics/:id/stream ← SSE stream for metric detail updates

GET  /api/service-map    ← aggregated service graph
GET  /api/stream         ← multiplexed SSE stream for traces, logs, and metrics
GET  /api/config         ← runtime limits and persistence status

Server-only state lives in src/lib/server/traceStore.ts with swappable backends behind the TraceStore interface. In default memory mode, runtime state is kept in memory with FIFO eviction. The retention limits default to 1000 traces (OTEL_GUI_MAX_TRACES), 1000 log records (OTEL_GUI_MAX_LOGS), 1000 metric entries (OTEL_GUI_MAX_METRICS), and 600 points per metric series (OTEL_GUI_MAX_METRIC_POINTS).
SSE subscribers are notified on every write and receive a debounced event: traces message.
Additional persistence backends (including pglite) are loaded via OTEL_GUI_PERSISTENCE_BACKEND_MODULE and can be distributed separately (for example in an enterprise package).

💠 Tech Stack

• SvelteKit 3 with Svelte 5 runes ($state, $derived, $effect)
• @sveltejs/adapter-node for persistent in-memory state
• protobufjs for Protobuf decoding
• No UI framework — custom waterfall and service-map SVG, with uPlot for metric charts
• TypeScript throughout

🤝 Contributing

You can submit a new idea.

And of course, you can develop an existing or a new idea 😀:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests if applicable
4. Run pnpm run lint && pnpm run format:check && pnpm run check && pnpm run test to validate
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is open source. See the LICENSE file for details.