binsight

module

v0.2.1 Latest Latest Go to latest Published: Sep 12, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/adrijshikhar/binsight

Links

Open Source Insights

README ¶

binsight

A local, read-only MySQL & MariaDB binlog viewer and analyzer for developers.

Quick nav: What it is · Screenshots · Features · Install · Usage · Architecture · License

What it is

binsight is a local, read-only MySQL & MariaDB binlog viewer, analyzer, parser, inspector, and decoder for developers. Point it at a directory of binlog files and it produces a filterable event stream, transaction grouping, row-image diffs, hex forensics, anomaly detection, and a schema timeline — all in a browser UI backed by a zero-config SQLite index. It also streams live from a running server as a replica, acting as a mysqlbinlog replacement with a visual front-end.

Decode never blocks the UI. Everything the browser reads comes from the index.

Screenshots

Demo

binsight demo

Full demo GIF coming soon.

Features

Feature	Detail
Event stream	Filterable, virtualised table; group by transaction; click any event to open the drawer
Row images	Before/after values for `UPDATE`, full rows for `INSERT`/`DELETE`
Diff view	Side-by-side go-mysql vs `mysqlbinlog` decode; per-field divergence highlighted
Hex view	Raw bytes with event-header overlay — for binlog forensics
Overview metrics	Per-file dashboard: event counts, sizes, TPS, top tables/operations
Anomaly detection	Six pluggable detectors: huge transaction (bytes + rows), long-running, rolled-back, bulk row event, schema churn; inline ⚠ markers; configurable thresholds in Settings
Schema / DDL timeline	All DDL statements ordered by time; cascade-risk highlights
Live tail	fsnotify watcher + SSE push; appends from the committed boundary without re-scanning
Remote streaming	Connects as a MySQL/MariaDB replica, mirrors binlog files byte-for-byte into a local spool
> 4 GiB file support	Wrap-immune position accumulator; `pos_wrap` anomaly detector; amber row markers at each 2³² boundary
MySQL + MariaDB	Tested against MySQL 5.5–8.4 and MariaDB 10.6/11.4; Docker version matrix in CI

Install

Install script (macOS / Linux, amd64 / arm64)

curl -fsSL https://raw.githubusercontent.com/adrijshikhar/binsight/main/install.sh | sh

Detects your OS and architecture, verifies the SHA-256 checksum, installs to ~/.local/bin (never uses sudo), adds that directory to your PATH if needed, and clears the macOS quarantine attribute.

Options: BINSIGHT_VERSION=v0.1.1 to pin a version, BINSIGHT_INSTALL_DIR=/somewhere to change the location, BINSIGHT_NO_MODIFY_PATH=1 to leave your shell config alone.

Homebrew (macOS / Linux)

brew install adrijshikhar/tap/binsight

Docker

docker run --rm -p 8080:8080 -v /path/to/binlogs:/data \
  ghcr.io/adrijshikhar/binsight:0.2.0 serve /data

go install

go install github.com/adrijshikhar/binsight/cmd/binsight@v0.2.0

Prebuilt binaries

Prebuilt binaries: see the latest GitHub release.

Usage

Start the viewer

binsight serve /path/to/binlog/dir

Open http://localhost:8080.

Quickstart with a sample binlog

# Download the demo binlog (from the latest release) into samples/
curl -L https://github.com/adrijshikhar/binsight/releases/latest/download/sample-binlog.tar.gz \
  | tar -xz -C samples
binsight serve samples

# Or generate a local sample (requires make + a running MySQL):
make sample

Environment variables

Variable	Default	Description
`BINSIGHT_PORT`	`8080`	HTTP listen port
`BINSIGHT_BIND`	`127.0.0.1`	Bind address. Loopback by default (the UI has no auth); set `0.0.0.0` to deliberately expose it.
`BINSIGHT_DATA_DIR`	`/var/lib/binsight`	SQLite index + settings storage. On a local (non-Docker) install, set this to a writable path such as `~/.local/share/binsight`.
`BINSIGHT_WATCH_DIR`	`/data`	Binlog directory (overrides the CLI argument when set)
`BINSIGHT_WATCH`	`true`	Enable live file-watching (set `false` to disable)
`BINSIGHT_MYSQLBINLOG_PATH`	`mysqlbinlog`	Path to the `mysqlbinlog` binary (optional; enables the Diff adapter)
`BINSIGHT_STREAM_ENABLED`	`false`	Enable remote replication streaming
`BINSIGHT_STREAM_HOST`	(unset)	MySQL/MariaDB host
`BINSIGHT_STREAM_PORT`	`3306`	MySQL/MariaDB port
`BINSIGHT_STREAM_USER`	(unset)	Replication user
`BINSIGHT_STREAM_PASSWORD`	(unset)	Replication user password
`BINSIGHT_STREAM_FLAVOR`	`mysql`	Source flavor: `mysql` or `mariadb`
`BINSIGHT_STREAM_SERVER_ID`	`51789`	server-id sent to source; must not collide with another replica
`BINSIGHT_STREAM_MAX_SPOOL_BYTES`	`2147483648`	Spool cap in bytes (2 GiB); oldest files pruned when exceeded

Remote streaming (Phase 2)

Stream binlogs straight from a live MySQL/MariaDB server. binsight connects as a replica and mirrors the server's binlog files into DATA_DIR/spool/, where the normal index + live-tail pipeline picks them up.

Create a replication user on the source:

CREATE USER 'binsight'@'%' IDENTIFIED BY '<password>';
GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'binsight'@'%';

Enable in Settings → Remote streaming, or via env:

BINSIGHT_STREAM_ENABLED=true \
BINSIGHT_STREAM_HOST=db.internal \
BINSIGHT_STREAM_USER=binsight \
BINSIGHT_STREAM_PASSWORD=... \
binsight serve /data

Resume is GTID-based when gtid_mode=ON (always for MariaDB), else file+position — both at a transaction boundary, never mid-transaction.

Architecture

Pluggable decoder adapters → normalized event schema → SQLite metadata index → REST API + SSE → embedded React UI.

See docs/pluggable-architecture.html for a full diagram and adapter capability matrix.

License

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
binsight command
internal
adapter Package adapter defines the Decoder interface — the ONLY contract the core knows about binlog parsing libraries — plus the registry that assigns adapters to roles (indexer/detail/diff/stream).	Package adapter defines the Decoder interface — the ONLY contract the core knows about binlog parsing libraries — plus the registry that assigns adapters to roles (indexer/detail/diff/stream).
adapter/execadapter Package execadapter bridges any subprocess speaking the JSON-lines protocol into the Decoder interface.	Package execadapter bridges any subprocess speaking the JSON-lines protocol into the Decoder interface.
adapter/gomysql Package gomysql is the builtin adapter wrapping github.com/go-mysql-org/go-mysql/replication.	Package gomysql is the builtin adapter wrapping github.com/go-mysql-org/go-mysql/replication.
adapter/mysqlbinlog Package mysqlbinlog wraps the official mysqlbinlog CLI as an exec adapter.	Package mysqlbinlog wraps the official mysqlbinlog CLI as an exec adapter.
adapter/mysqlbinlog/probe command
anomaly Package anomaly defines a pluggable Detector interface and an Engine that runs detectors over the committed SQLite index, emitting findings into the anomalies table.	Package anomaly defines a pluggable Detector interface and an Engine that runs detectors over the committed SQLite index, emitting findings into the anomalies table.
config Package config implements settings precedence: env vars (BINSIGHT_*) → persisted UI settings (SQLite) → built-in defaults.	Package config implements settings precedence: env vars (BINSIGHT_*) → persisted UI settings (SQLite) → built-in defaults.
corpus Package corpus describes the multi-version conformance fixture set: the manifest schema shared by the offline generator (tools/gen-corpus) and the always-on conformance matrix (internal/conformance), plus the version→feature gating used to decide which workload add-ons and which assertions apply.	Package corpus describes the multi-version conformance fixture set: the manifest schema shared by the offline generator (tools/gen-corpus) and the always-on conformance matrix (internal/conformance), plus the version→feature gating used to decide which workload add-ons and which assertions apply.
ddl Package ddl parses MySQL/MariaDB CREATE/ALTER DDL SQL into a structured Schema model.	Package ddl parses MySQL/MariaDB CREATE/ALTER DDL SQL into a structured Schema model.
diffsvc Package diffsvc decodes one event with every adapter in the diff set and aligns the results.	Package diffsvc decodes one event with every adapter in the diff set and aligns the results.
hexsvc Package hexsvc reads raw event bytes straight from the binlog file — independent of all adapters — and annotates the 19-byte common header.	Package hexsvc reads raw event bytes straight from the binlog file — independent of all adapters — and annotates the 19-byte common header.
indexer Package indexer streams normalized events from an adapter into the SQLite index.	Package indexer streams normalized events from an adapter into the SQLite index.
scanner Package scanner discovers binlog files: via the *.index file when present (authoritative, like MySQL itself), else by treating every regular file in the directory as a candidate and keeping those whose first four bytes are the binlog magic (0xfe 'bin').	Package scanner discovers binlog files: via the *.index file when present (authoritative, like MySQL itself), else by treating every regular file in the directory as a candidate and keeping those whose first four bytes are the binlog magic (0xfe 'bin').
schema Package schema defines normalized event schema v1 — the contract between all decoder adapters and the core.	Package schema defines normalized event schema v1 — the contract between all decoder adapters and the core.
server Package server wires store, adapter registry, indexer, scanner and the embedded web UI behind an HTTP API.	Package server wires store, adapter registry, indexer, scanner and the embedded web UI behind an HTTP API.
sqlkw Package sqlkw provides lightweight, dependency-free detection of the leading keyword of a SQL statement.	Package sqlkw provides lightweight, dependency-free detection of the leading keyword of a SQL statement.
store Package store is the SQLite index.	Package store is the SQLite index.
streamer Package streamer connects to a remote MySQL/MariaDB server as a replica and spools raw binlog bytes into local files that byte-identically mirror the server's binlogs.	Package streamer connects to a remote MySQL/MariaDB server as a replica and spools raw binlog bytes into local files that byte-identically mirror the server's binlogs.
watcher Package watcher reports directory changes via a debounced callback.	Package watcher reports directory changes via a debounced callback.
tools
gen-corpus command Command gen-corpus is the OFFLINE maintainer tool that generates authentic per-version binlog fixtures for the conformance matrix.	Command gen-corpus is the OFFLINE maintainer tool that generates authentic per-version binlog fixtures for the conformance matrix.