SynadiaDocs

Synadia Insights

Quick Start

You can run Insights in two ways:

  • Against the simulator. Explore the web UI, search, and checks with generated data. You don't need a NATS system or a license.
  • Against a real NATS system. Point Insights at your own deployment using system account credentials. A trial build also needs its license.

Run Against the Simulator

./insights --simulator

This starts everything in one process:

  • A simulated NATS deployment with clusters, servers, accounts, streams, consumers, and connections.
  • The scraper, which collects data from the simulated servers every minute.
  • The indexer, which stores each scrape in a database in a temporary directory.
  • The web UI on port 8080.

Open http://127.0.0.1:8080. The data is lost when the process stops.

To simulate a different topology, choose a profile:

# 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

The profiles are core-{small,medium,large}, js-{small,medium,large}, super-{small,medium,large}, leaf-{small,medium,large}, and super-leaf-{small,medium,large}.

The simulator is a single NATS system, so you can't combine it with a systems: list in the config file.

To keep the simulator's data across restarts:

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

Run Against a Real NATS System

Insights connects to your NATS system as the system account and requests the monitoring data the servers publish. It only reads. It never changes the system it monitors.

Prerequisites

  • NATS Server 2.10.27 or later.
  • Credentials for the system account ($SYS), as a .creds file or a NATS context.
  • Network access from Insights to the NATS servers.
  • For a trial build, the trial license. Add --license.file /etc/insights/license.jwt to the commands below.

Connect with credentials

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

Connect with a NATS context

If you already use the NATS CLI, reuse a saved context:

./insights \
  --sys.context my-system

Authentication options

--sys.* accepts the same authentication methods as any NATS client:

MethodFlags
Credentials file--sys.creds /path/to/sys.creds
NATS context--sys.context my-context
Basic auth--sys.user USER --sys.password PASS
NKey--sys.nkey SEED
JWT--sys.jwt TOKEN

TLS (--sys.tls-cert, --sys.tls-key, --sys.tls-ca-cert, --sys.tls-first) and SOCKS proxies (--sys.socks-proxy) are also supported. If the system account can't subscribe to _INBOX.>, set --sys.inbox-prefix to a prefix it can use.

Keep the data

Add --data-dir to keep the database across restarts:

./insights \
  --sys.server nats://your-nats:4222 \
  --sys.creds /path/to/sys.creds \
  --data-dir /var/lib/insights

The Deployment Guide covers production settings.

Open the Web UI

Open http://127.0.0.1:8080. To reach the UI from other machines, add --web.hostname 0.0.0.0.

The overview page shows cluster status, server and connection counts, JetStream usage, and current check findings. The sidebar leads to clusters, servers, accounts, streams, consumers, connections, and KV and object stores. The time controls switch between live data and a point in the past.

If the selected time range has no data, for example because retention already removed it, the toolbar shows No data in this range and no overall grade is shown. Hover over the warning to see the range that does have data. Jump to now returns to live data.

As data builds up, check findings appear on the overview and on each entity's page, labeled by severity and grouped into six categories.

Next Steps

Next
Concepts