Architecture

Insights is a single binary with independently toggleable subsystems. You can run everything in one process, or split responsibilities across multiple instances to match your environment.

Subsystems

Subsystem	Purpose
Scraper	Collects monitoring data from a target NATS system's system account.
Indexer	Processes collected data into a time-series store for query and audit.
Checks	Evaluates automated audit checks after each collection cycle.
Web UI	Dashboard for interactive exploration of indexed data.
API	NATS Micro service for programmatic access to indexed data.
Simulator	Optional in-process NATS deployment used for evaluation and demos.

Each subsystem can be enabled or disabled independently. This allows deployment topologies ranging from a single all-in-one process to distributed setups where scraping, indexing, and serving run on separate hosts. See the Deployment Guide for topology configurations.

Data Flow

Insights connects to the target NATS system using the system account, collects monitoring data on a recurring interval, and indexes it for query. Audit checks run after each indexing cycle. The Web UI and API serve the indexed data.

Collection is read-only. Insights does not modify the target system.

Epochs

Each collection cycle is called an epoch. An epoch captures a snapshot of the entire NATS deployment: servers, clusters, connections, streams, consumers, accounts, and their configuration and state. The default epoch interval is 1 minute.

Every piece of data Insights stores is associated with an epoch, which is what makes historical analysis (go back in time, compare states, audit what changed) possible.

Data Storage

Insights uses an embedded analytical database. By default, all data is held in memory and lost on process restart.

Set --data-dir to enable persistent storage. Insights will write:

The analytical database file containing all indexed time-series data.
Internal NATS JetStream state used for durable message transport between the scraper and indexer.

Retention is configurable by duration or by epoch count, so long-running deployments don't grow unbounded.

Deployment Topologies

Because subsystems toggle independently, Insights supports several operational shapes:

All-in-one. Every subsystem in a single process. The default and simplest topology.
Headless. No Web UI; the API remains available for programmatic access.
Indexer-only. Consume from an existing scrape stream produced by a separate scraper instance.
External sink. Use an external NATS cluster for the scraper-to-indexer transport, enabling multi-instance setups.

See the Deployment Guide for concrete configurations.

Audit Checks

After each epoch is indexed, Insights runs over 100 automated audit checks against the current state. Checks evaluate health, performance, error patterns, resource saturation, configuration consistency, and recent changes. Findings carry a severity, the affected entity, and remediation guidance. See Audit Checks.

Next Steps

Audit Checks. The automated audit framework.
Deployment Guide. Topologies and configuration.