viz0

viz0 is a terminal UI for inspecting OpenTelemetry data pulled from Dash0. It is designed for developers and SREs who want to inspect traces, logs, and metrics without changing application OTLP exporter configuration.

viz0 queries the Dash0 Backend on demand and renders the results in your terminal. It does not ingest, receive, or persist telemetry locally — your applications continue exporting OTLP to Dash0 as before.

The first vertical slice is the Trace Workspace: search a Dash0 time window, group matching spans into trace-centric summaries, and hydrate selected traces for waterfall and span inspection.

Requirements

• A Dash0 auth token with querying permissions
• A Dash0 API endpoint URL from your Dash0 organization settings
• Node.js 18 or newer and npm for package installation
• Bun 1.1 or newer is only required for development; release binaries bundle the Bun runtime

Install

Install with npm:

npm install --global @maxanderson95/viz0

npm resolves an optional per-platform package and installs only the one matching your OS and CPU. The viz0 command itself is a small Node launcher that exec's the platform binary. It does not require Bun at runtime.

Supported npm install targets:

| Platform | npm platform package | | ------------------- | ------------------------------------- | | macOS Apple Silicon | @maxanderson95/viz0-darwin-arm64 | | Linux arm64 | @maxanderson95/viz0-linux-arm64 | | Linux x64 | @maxanderson95/viz0-linux-x64 | | Windows x64 | @maxanderson95/viz0-windows-x64 |

To install without npm, download the executable for your platform from the latest GitHub Release, make it executable, and place it on your PATH as viz0.

Manual download artifacts:

| Platform | Artifact | | ------------------- | --------------------------------- | | macOS Apple Silicon | viz0-darwin-arm64 | | Linux arm64 | viz0-linux-arm64 | | Linux x64 | viz0-linux-x64-baseline | | Windows x64 | viz0-windows-x64.exe |

# Example: macOS Apple Silicon
curl -L -o viz0 https://github.com/MaxAnderson95/viz0/releases/latest/download/viz0-darwin-arm64
chmod +x viz0
xattr -d com.apple.quarantine viz0 2>/dev/null || true
mv viz0 ~/.local/bin/viz0

The macOS binaries are ad-hoc codesigned in CI so the arm64 kernel will execute them, but they are not Apple-notarized. The xattr -d com.apple.quarantine step removes the Gatekeeper attribute that curl adds to downloaded files; without it, macOS will block the binary on first run.

For manual downloads, verify the download against SHA256SUMS published with the release. To update, run npm update --global @maxanderson95/viz0 for npm installs or replace the binary with a newer release artifact for manual installs.

Configuration

viz0 uses Dash0's official environment variable names:

DASH0_API_URL=https://api.<region>.dash0.com
DASH0_AUTH_TOKEN=auth_...
# Optional. For query APIs, set this when you need a non-default Dataset.
DASH0_DATASET=my-dataset

DASH0_DATASET is optional in viz0 configuration, but Dash0's trace query API currently selects a non-default Dataset through the JSON request body. This is separate from ingestion behavior, where token/default ingestion Dataset rules can apply to writes.

If Dash0 returns access to dataset 'default' is not permitted, set DASH0_DATASET to the Dataset identifier you want viz0 to query.

Keep credentials out of version control. Load them from a shell profile, a secret manager, or a local .env file that is gitignored — do not commit .env files or paste tokens into shared scripts.

First run

With viz0 on your PATH and the environment variables set, launch the Trace Workspace:

export DASH0_API_URL=https://api.<region>.dash0.com
export DASH0_AUTH_TOKEN=auth_...
# export DASH0_DATASET=my-dataset   # optional

viz0

The footer lists available keybindings. Esc clears transient UI state and q opens the quit confirmation.

Development

bun install
bun run typecheck
bun test
bun run smoke:api
bun run dev

smoke:api only prints response metadata and trace-summary counts. It does not print raw telemetry payloads.

Safe mapping diagnostics

Trace mapping diagnostics compare viz0's mapped count summaries with safe Dash0 response metadata when Dash0 exposes that metadata. The comparison is count-only: spans, services, events, logs, and web events. It must not print raw telemetry payloads, attribute values, log bodies, or secrets.

The live metadata endpoint is still pending upstream ($counts_url in issue #11), so the diagnostic currently exists as tested pure comparison/formatting behavior and can be wired into smoke:api once Dash0 exposes safe count metadata.

Building release binaries locally

bun run build:all

Produces single-file executables under dist/ for the three supported targets. CI runs the same commands on tag push (v*), attaches the artifacts to a GitHub Release, publishes one npm package per platform containing the matching binary, and publishes the main @maxanderson95/viz0 package whose optionalDependencies point at the platform packages.

Release setup and first-publish notes are in docs/release.md.

Attribution

viz0 borrows TUI implementation ideas and may adapt MIT-licensed code from motel by Kit Langton. See THIRD_PARTY_NOTICES.md.