SynadiaDocs

Synadia Insights

Frequently Asked Questions

What NATS server versions are supported?

Insights requires NATS Server 2.10.27 or later, and system account access. It collects every standard monitoring endpoint: varz, connz, jsz, routez, gatewayz, leafz, subsz, accountz, accstatz, healthz, raftz, and ipqueuesz.

The minimum is 2.10.27 rather than 2.10.0 because raftz and ipqueuesz were added during the 2.10 releases. Earlier 2.10 releases still work, but Raft group and internal queue data stays empty.

Each change to Insights is tested against recorded monitoring data from NATS Server 2.10.27, 2.11.17, 2.12.14, and 2.14.4. Other versions may work but aren't tested or supported.

What are the system requirements?

Insights is a single binary for Linux, macOS, and Windows. What it needs depends on the size of the NATS deployment it monitors:

  • CPU. 1 to 2 cores is enough for most deployments.
  • Memory. A small deployment needs under 500 MiB. Memory use grows with the amount of data collected and queried, so deployments with many connections, streams, and accounts need more.
  • Disk. Needed only with --data-dir. The database grows with the number of monitored entities and the retention period.

For a large deployment, contact Synadia for an assessment and sizing guidance.

How long is data kept?

The database keeps data for --db.retention.duration, 32 days (768h) by default. Set it to 0 to keep everything. Insights removes old data every --db.retention.interval, 10 minutes by default.

Without --data-dir, Insights uses a temporary directory and the data is lost when the process stops. Set --data-dir to keep it.

The stream between the scraper and the indexer has its own limit, --sink.retention, which controls how long scraped data waits in the stream before it is stored.

Can Insights monitor several clusters?

Yes. Insights sees whatever the system account can see. If your clusters are connected with gateways or leaf nodes, one Insights node with system account credentials sees all of them.

The web UI shows each cluster and how they connect: gateways, routes, and leaf nodes.

To monitor separate NATS systems at different sites, see Federated Deployment.

What is the simulator for?

The simulator runs real NATS servers inside the Insights process with generated traffic. Use it to:

  • Evaluate Insights without connecting to a production system.
  • Demo Insights with realistic data.
  • Test against a known NATS setup.

Start it with --simulator. You don't need any NATS servers.

Profiles set the topology and size:

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

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

The profile families are core-, js-, super-, leaf-, and super-leaf-, each in small, medium, and large.

The simulator isn't for production. Its data is lost on restart unless you set --data-dir.

Can I run Insights without the web UI?

Yes. Turn it off with --web=false:

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

Insights still scrapes, stores data, and runs checks, and you can query it over NATS:

# Query the system whose id is "default"
nats req '$INS.sys.default.db.query' '{"sql": "SELECT * FROM hx.servers LIMIT 5"}'

Every API subject includes the system id, as in $INS.sys.<id>.db.query. default is the id a node uses unless you set one. insights system list shows the ids that answer.

A db.query request returns at most db.query-max-rows rows (100,000 by default). A larger result is rejected with a 413, so add a LIMIT or use the streaming query. insights db query streams results automatically, up to db.query-stream.max-rows (1,000,000 by default):

insights db query "SELECT * FROM hx.streams"

For tools that don't use NATS, insights http serves the same read-only queries over HTTP for BI tools, dashboards, and scripts, and insights mcp serves them to AI agents over MCP. Both have the same read-only rules and row limits. See AI Agents.

How do I change check thresholds?

Add a check-thresholds section to the config file, keyed by check code and parameter name. There are no flags or environment variables for thresholds.

check-thresholds:
  server-003:
    cpu_percent: 80 # flag servers above 80% CPU per core
  stream-002:
    lag_percent: 20 # flag stream replicas more than 20% behind the leader
  connection-001:
    rtt: 500ms # flag client connections with RTT above 500ms

Only checks with parameters can be changed. The Checks Reference lists each check's parameters and defaults. An unknown check code or parameter name stops Insights from starting and is named in the error. To list checks and see a check's parameters:

insights checks list
insights checks info server-003

Can I turn a check off?

Yes. List its code under disabled-checks:

disabled-checks:
  - account-012

Use this for checks that don't apply to your setup. For checks that are too noisy, raise the threshold instead. account-012 (High Gateway Traffic Ratio) is a common example: in a single-account super cluster, most traffic crosses gateways by design, so the check always fires.

A disabled check still runs and its findings stay visible, marked as disabled. It doesn't count toward grades and never sends a notification. If you enable it again, it starts counting and sending notifications again, with its history intact.

Like check-thresholds, this can only be set in the config file. You can also set it for one system in a systems: entry, which adds to the top-level list but can't enable a check that the top level disables. An unknown code stops Insights from starting, and an old-style code such as ACCOUNT_012 is reported with its current name. insights config check runs the same checks without starting the node.

How does TLS work for the web UI?

TLS is off by default. To turn it on, pass --web.tls with your own certificate and key. Turning on TLS without them fails at startup, because Insights doesn't generate a certificate. For a public endpoint, end TLS at an ingress or load balancer, or use a real certificate.

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

With TLS on, HTTP/2 is available automatically.

Can I scrape only some servers?

Yes. Use scraper.filter to allow or deny servers by exact server name, cluster, or tag. Excluded servers receive no monitoring requests. See the scraper section of the Configuration reference.

Next
SBOM