SynadiaDocs

Synadia Insights

Frequently Asked Questions

What NATS server versions are supported?

Insights requires NATS Server 2.10 or later. The scraper collects metrics via the $SYS account monitoring API, which requires system account access. All standard NATS monitoring endpoints (varz, connz, jsz, routez, gatewayz, leafz, subsz, accountz, accstatz, healthz, raftz, ipqueuesz) are supported.

Older server versions may work for basic metrics but aren't tested or officially supported.

What are the system requirements?

Insights is a single statically-linked Go binary that runs on Linux, macOS, and Windows. Resource requirements scale with the size of the NATS deployment you're monitoring:

  • CPU. 1 to 2 cores is enough for most deployments. The scraper, indexer, and web UI each run concurrently.
  • Memory. Baseline usage is modest (under 500 MB). Large deployments with many connections, streams, and accounts will push memory higher thanks to DuckDB's in-process analytical engine.
  • Disk. Only required when --data-dir is set for persistent storage. The DuckDB database and JetStream data grow with the number of entities monitored and the configured retention period.

For evaluation, simulator mode (--simulator.enabled) runs entirely in memory with no external dependencies.

How is data retained and what are the defaults?

Database retention is controlled via --db.retention.duration (default 768h / 32 days). Set to 0 to disable retention and keep all data indefinitely. The sweep interval is controlled via --db.retention.interval (default 10m).

Additionally, --data-dir controls whether data survives restarts. Without it, Insights uses a temporary directory and all data is lost when the process stops. Set --data-dir to a stable path for persistent deployments.

The sink stream (JetStream) has a separate retention control via --sink.retention, which limits how long scraped data is kept in the stream before the indexer processes it.

Does it support multi-cluster monitoring?

Yes. Insights monitors whatever the system account has visibility into. If your NATS deployment spans multiple clusters connected via gateways, super-clusters, or leaf nodes, a single Insights instance with system account credentials to the super-cluster will observe all connected clusters.

The web UI organizes data by cluster, showing cross-cluster relationships such as gateway connections, route topology, and leaf node mappings.

What is the simulator and when should I use it?

The simulator starts real, in-process NATS server clusters with synthetic traffic workloads. It's useful for:

  • Evaluation. Explore the Insights UI without connecting to a production system.
  • Demos. Show off Insights capabilities with realistic data.
  • Development. Test against a controlled NATS environment.

Enable it with --simulator.enabled. No external NATS servers required. Everything runs inside the Insights process.

Profiles control the simulated topology and scale:

# Small JetStream cluster (default)
./insights --simulator.enabled

# Large super-cluster with leaf nodes
./insights --simulator.enabled --simulator.profile super-leaf-large

Available profile families: core-, js-, super-, leaf-, super-leaf-, each in small, medium, and large variants.

The simulator isn't meant for production use. All simulated data is ephemeral unless --data-dir is set.

Can I run Insights without the web UI (headless)?

Yes. Disable the web server with --web.enabled=false:

./insights \
  --sys.server nats://target:4222 \
  --sys.creds /path/to/sys.creds \
  --web.enabled=false

In headless mode, Insights still scrapes, indexes, and runs audit checks. The NATS micro API remains available, so you can query data programmatically:

# Direct query via the NATS CLI
nats req '$INS.db.query' '{"sql": "SELECT * FROM hx.servers LIMIT 5"}'

How does TLS work for the web UI?

TLS is disabled by default. Enable it with --web.tls=true. When no certificate or key paths are provided, Insights automatically generates a self-signed certificate, so HTTPS works out of the box — though browsers will show a certificate warning.

For production, supply your own certificate and key:

./insights \
  --web.tls-cert /path/to/cert.pem \
  --web.tls-key /path/to/key.pem

When TLS is enabled, HTTP/2 is automatically available via ALPN negotiation.

Next
SBOM