Skip to main content

Quick Start

The fastest way to explore Insights is with the built-in simulator. It creates a multi-cluster NATS topology with realistic traffic patterns, so you can see every feature without setting up external infrastructure.

Start the Simulator​

./insights --simulator

This starts everything in a single process:

  • A simulated NATS deployment with multiple clusters, servers, accounts, streams, consumers, and connections
  • The scraper, collecting data from the simulated servers every minute
  • The indexer, storing time-series snapshots into a DuckDB database in a temporary directory
  • The web UI, serving the dashboard on port 8080

All data is ephemeral: it lives in a temporary directory and is lost on restart.

Open the Web UI​

Navigate to http://127.0.0.1:8080 in your browser.

What You Will See​

Overview Page​

The landing page shows the system-wide overview: cluster status, server counts, connection counts, JetStream usage, and active check findings. Summary sparklines show trends over time as data accumulates.

The left sidebar provides access to all entity types:

  • Clusters: cluster health, server membership, and resource usage
  • Servers: individual server metrics, connections, and JetStream state
  • Accounts: account-level views with connection, stream, and consumer breakdowns
  • Streams: stream configuration, replication status, and throughput
  • Consumers: consumer health, delivery rates, and ack pending state
  • Connections: active client connections with metadata and traffic
  • KV Stores and Object Stores: JetStream-backed key-value and object storage assets

Click any entity to see its detail page. Detail pages show full metadata, time-series metrics, related entities, and any active check findings for that entity.

Time Controls​

The time control bar at the top of the page lets you navigate through historical data:

  • Live mode (default): the view updates in real time as new epochs arrive
  • Pin to a point in time: click anywhere on the timeline or use the time picker to freeze the view at a specific moment. This lets you see exactly what the system looked like at that epoch.

In live mode, data refreshes automatically. When pinned, the view is static until you return to live mode.

A window can land where there is nothing to show, because retention has pruned it or the scrape had not started yet. Every count then reads zero and every check passes for want of anything to fail on, which looks like a healthy idle system. The interface says so instead: the toolbar shows a No data in this range warning (hover it for the range that does hold data), the overall grade is withheld rather than reported as 100%, and Jump to now returns the view to live.

Checks​

As data accumulates, you will see check findings appear. These are automated assessments that run on every epoch. Findings are displayed on entity detail pages and on the overview page, categorized by severity (critical, warning, info) and organized into six analytical categories.

Simulator Profiles​

The default simulator profile (js-small) creates a modest JetStream deployment. You can choose larger or different topologies:

# A medium-sized super cluster
./insights --simulator --simulator.profile super-medium

# A large core NATS deployment (no JetStream)
./insights --simulator --simulator.profile core-large

# A leaf node topology
./insights --simulator --simulator.profile leaf-small

Available profile families:

FamilyDescription
core-{small,medium,large}Core NATS clusters without JetStream
js-{small,medium,large}JetStream-enabled clusters with streams and consumers
super-{small,medium,large}Super clusters connected via gateways
leaf-{small,medium,large}Leaf node topologies
super-leaf-{small,medium,large}Super clusters with leaf nodes

Larger profiles generate more entities and traffic, giving a richer dataset to explore at the cost of higher resource usage on your machine.

The simulator is a single NATS system: a config that also sets a systems: list is rejected with the simulator is single-system: it cannot run with a systems: list.

Persist Simulator Data​

By default, all data is lost when the process exits. To keep your data across restarts:

./insights --simulator --data-dir ./insights-data

This writes the DuckDB database and JetStream state to the specified directory.

Connect to a Real NATS Server​

When you are ready to monitor a real deployment (NATS Server 2.10.27 or later), provide system account credentials:

./insights \
  --sys.server nats://your-nats:4222 \
  --sys.creds /path/to/sys.creds

A trial build also needs --license.file. Insights connects to the target NATS system using the system account to issue $SYS monitoring requests. This is a read-only operation: Insights does not modify the target system.

See the Deployment Guide for production topologies, persistence, authentication options, and advanced configuration.

Next Steps​