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.

• Zero config — listens on port 4318 (OTLP/HTTP) and 4317 (OTLP/gRPC), the standard OTLP ports. Most exporters work without changing a single setting
• OTLP ingestion — OTLP/HTTP accepts OTLP/JSON (application/json) and OTLP/Protobuf (application/x-protobuf); OTLP/gRPC accepts Protobuf exports over HTTP/2, with optional gzip compression
• 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, counters, up/down counters, histograms, exponential histograms, and summaries with time-series charts, histogram distribution + heatmap views, per-series filtering, and a paginated datapoint table with attributes
• 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
• MCP server — read-only Model Context Protocol endpoint for AI agents to search traces, logs, and metrics, inspect records, list services, and view the service map
• Import/export traces and logs — export one trace or log, or the filtered or selected traces/logs, as an 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

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

With Nix flakes enabled, run the latest version from this repository:

nix run github:metafab/otel-gui

To install it into your user profile:

nix profile install github:metafab/otel-gui

The app listens on port 4318 by default. Set PORT to use a different port:

PORT=55681 nix run github:metafab/otel-gui

For development in a checkout, enter the pinned Node.js and pnpm environment with:

nix develop
pnpm install
pnpm run dev

Pull and run the published GHCR image:

docker pull ghcr.io/metafab/otel-gui:latest
docker run --rm --name otel-gui -p 4318:4318 -p 4317:4317 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 -p 4317:4317 otel-gui

Then use the standard OTLP endpoint:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
# or, for gRPC exporters
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

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. The OTLP/gRPC receiver listens on OTEL_GUI_GRPC_PORT (default 4317).

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

Requires: Node.js ≥ 22.17, 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.

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

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.

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.

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. Monotonic sums are presented as Counters and non-monotonic sums as UpDownCounters; their OTLP data type remains Sum. Sum points get a server-computed per-second rate (with counter-reset detection); histograms render as both a distribution and a time/bucket heatmap.

OTLP/gRPC exporters can send traces, logs, and metrics to the standard gRPC port:

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

The receiver implements the OTLP TraceService, LogsService, and MetricsService Export methods over plaintext HTTP/2 (no TLS), with optional gzip compression. Change the port with OTEL_GUI_GRPC_PORT, or disable the receiver with OTEL_GUI_GRPC_ENABLED=false. If the port is already in use, a warning is logged and the HTTP server keeps running.

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

# 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

# Counter metrics (monotonic OTLP Sum 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.

The Streamable HTTP MCP endpoint is available at http://localhost:4318/mcp (assuming the default port 4318).

For example, add it to Claude Code:

claude mcp add --transport http otel-gui http://localhost:4318/mcp

Add this server to a VS Code .vscode/mcp.json file:

{
  "servers": {
    "otel-gui": {
      "type": "http",
      "url": "http://localhost:4318/mcp"
    }
  }
}

The server exposes read-only tools: search_traces, get_trace, search_logs, get_log, search_metrics, get_metric, list_services, and get_service_map. Search results and detail payloads are bounded; oversized responses return a tool error rather than being silently truncated.

MCP is enabled by default and restricted to loopback clients. To disable it, set OTEL_GUI_MCP_ENABLED=0. For Docker or reverse-proxy setups where the client does not arrive as loopback, OTEL_GUI_MCP_ALLOW_REMOTE=1 opts into remote access. Only do this when network exposure is appropriately restricted: otel-gui does not authenticate MCP clients, and the MCP tools can read retained telemetry.

Agents that can make HTTP requests can read telemetry from the existing /api/* routes without an MCP client. See the HTTP API guide for examples, limits, response shapes, and access considerations. A machine-readable OpenAPI specification is also served by the running instance at /openapi.yaml; the root llms.txt provides a short discovery index.

These application routes are unversioned and currently have no authentication. The OpenAPI document describes existing behavior but does not establish a compatibility guarantee. For read-only access, use the GET routes; treat DELETE and import endpoints as destructive. MCP remains an alternative with purpose-built search tools.

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.

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.

Direct HTTP requests use their connection scheme for origin checks. Behind a TLS-terminating reverse proxy, set PROTOCOL_HEADER=x-forwarded-proto and configure the trusted proxy to remove client-supplied X-Forwarded-Proto headers and set the correct value itself. Only enable this setting when clients cannot bypass the proxy. The proxy must also forward the correct Host header.

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

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.

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).

• 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

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

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