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"}'

The direct $INS.db.query request returns at most db.query-max-rows rows (default 100000); a larger result is rejected with a 413, so add a LIMIT or switch to the streaming path. The insights query CLI streams results automatically and isn't subject to that cap:

insights query "SELECT * FROM hx.streams"

For clients that can't speak NATS, two subcommands expose the same read-only query API over other protocols: insights http runs an HTTP gateway for BI tools, dashboards, and scripts, while insights mcp runs a Model Context Protocol server for AI assistants. Both enforce the same read-only guard and row cap as the underlying NATS endpoints.

How do I configure check thresholds?

Insights includes a built-in audit checks framework that evaluates the health of your NATS infrastructure. Checks that expose tunable parameters can be overridden through the config file — there is no environment variable or CLI flag for these overrides.

Add a check-thresholds section, keyed by check code and parameter name:

check-thresholds:
  SERVER_003:
    cpu_percent: 80 # flag servers at or above 80% CPU (default 90)
  JETSTREAM_001:
    lag_percent: 20 # flag stream replica lag at or above 20% (default 10)

Only checks that declare configurable parameters can be overridden. To list the available checks and inspect a check's parameters, use the CLI:

insights checks list
insights checks info SERVER_003

How does TLS work for the web UI?

TLS is disabled by default. When you enable it with --web.tls=true, you must also supply your own certificate and key — enabling TLS without them fails at startup. Insights does not generate a self-signed certificate. For a public endpoint, terminate TLS at an ingress or provide a real certificate.

Supply the 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