Architecture

Insights is a single binary made of parts you can turn on and off. Run everything in one process, spread the parts across several processes, or monitor several NATS systems from one process.

Subsystems

The Deployment Guide shows how to combine them.

Systems and Nodes

• A system is one NATS deployment you monitor. You give it an id with system.id (the default is default). Everything that belongs to the system, such as its database, checks, and API, uses that id in its NATS subjects: $INS.sys.<id>.*.
• A node is one running Insights process, named by node.id. A node that serves one system uses that system's id by default. A node that serves several systems needs its own name.

For each system, a node does one or both of these jobs:

• Scraping: connecting to the monitored system, collecting data, and writing it to a stream.
• Cataloging: storing that data in the database, running checks, and answering queries.

Clients address a system by its id and don't need to know which node does which job. Each node answers the $INS.ping discovery request, so insights system list and insights node list can show everything that is reachable.

A node can serve one system (with the system, sys, scraper, and sink settings) or several (with a systems: list). With a list, each system gets its own database, stream, indexer, check settings, and API subjects. Systems share nothing, so if one system's database fails to open, the others keep running.

Common ways to arrange nodes:

• One node scrapes and catalogs a system. This is the usual setup.
• Federated. Each site runs its own Insights node, and they share one NATS account. A web UI connected to that account shows every site. See Federated Deployment.
• Federated with collectors. A site runs a collector, which only scrapes, and a central node catalogs its data. The collector is the separate insights-collector binary.

Data Flow

Insights connects to the monitored system as its system account, collects monitoring data on an interval, and stores it. Checks run after each scrape is stored. The web UI and the API serve the stored data.

The web UI and API never open the database directly. They query it through a read-only API over NATS ($INS.sys.<id>.db.query.stream), even inside the same process. That is why the web UI can run as its own process, and it is the same API behind insights mcp and insights http. Every web UI page belongs to one system, under /systems/<id>.

Insights only reads. It never changes the system it monitors.

What Insights Collects

Insights requests monitoring data over NATS through the system account, so it doesn't need access to the servers' HTTP monitoring ports. Each scrape first finds the servers with $SYS.REQ.SERVER.PING, then requests these endpoints from each server:

Each scrape records how many servers it expected and how many answered, so a scrape that missed a server doesn't look complete.

Epochs

Each scrape is called an epoch. An epoch is a snapshot of the whole deployment: servers, clusters, connections, streams, consumers, accounts, and their configuration and state. By default Insights scrapes once a minute.

Everything Insights stores belongs to an epoch. That is what lets you go back in time and compare the state of the system before and after a change.

Data Storage

Insights stores data in an embedded database, one per monitored system. Without --data-dir, it uses a temporary directory and the data is lost when the process stops.

With --data-dir, Insights writes:

• The database: insights.db for a node with one system, or systems/<id>.db for each system in a systems: list.
• The JetStream data for the stream between the scraper and the indexer, when Insights runs its embedded NATS server. With an external NATS server, the stream lives there instead.
• identity.json, which records the node and system ids the directory belongs to. If you change those ids, insights config check reports it and insights config migrate moves the data to the new ids.

Data is kept for 32 days by default. You can change this.

Checks

After each epoch is stored, Insights runs more than 140 checks. Operational checks look at the state at that epoch. Optimization checks look at a window of recent epochs, six hours by default. Each finding has a severity, the affected entity, and steps to fix it. Every change to a finding is published on $INS.sys.<id>.feed.finding.>. See Checks.

Next Steps

• Checks. How checks and findings work.
• Deployment Guide. Deployment options and configuration.