Skip to main content

Frequently Asked Questions

What NATS server versions are supported?​

Insights requires NATS Server 2.10.27 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.

The floor sits inside the 2.10 patch series rather than at 2.10.0 because raftz and ipqueuesz were added part-way through it. Earlier 2.10 releases answer the other endpoints and will collect, but leave Raft group and internal queue data empty.

Every supported minor is covered by a test matrix that replays recorded monitoring responses from 2.10.27, 2.11.17, 2.12.14 and 2.14.4 through the indexer on each change. Versions outside that range may work but are not 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 being monitored:

  • CPU: 1-2 cores is sufficient for most deployments. The scraper, indexer, and web UI each run concurrently.
  • Memory: A small deployment needs under 500 MiB. Memory grows with the amount of data collected and queried, so deployments with many connections, streams, and accounts need more.
  • Disk: Only required when --data-dir is set for persistent storage. The DuckDB database and JetStream data grow based on the number of entities being monitored and the configured retention period.

For a large deployment, contact Synadia for an assessment and sizing guidance. For evaluation, the simulator mode (--simulator) runs 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).

--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.

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

What is the simulator and when should I use it?​

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

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

Enable it with --simulator. No external NATS servers are required: everything runs inside the Insights process.

Profiles control the simulated topology and scale:

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

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

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

The simulator is not intended for production use. All simulated data is ephemeral unless --data-dir is set.

Can I run Insights without the web UI?​

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

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

Without the web UI, Insights still scrapes, indexes, and runs checks. The NATS micro API remains available, so you can query data programmatically:

# Direct query via the NATS CLI, addressed to the system whose id is "default"
nats req '$INS.sys.default.db.query' '{"sql": "SELECT * FROM hx.servers LIMIT 5"}'

Every API subject names the system it addresses, as in $INS.sys.<id>.db.query; default is the system.id a single-system node uses unless configured otherwise, and insights system list shows the ids that answer. db.query buffers its result and is capped at db.query-max-rows (default 100000); the insights db query CLI uses the streaming endpoint (db.query.stream) instead, which is not subject to that cap and stops a query at db.query-stream.max-rows (default 1000000). For clients that don't speak NATS, run insights http (an HTTP gateway over the read-only query API) or insights mcp (a read-only MCP server for AI assistants).

How do I configure check thresholds?​

Insights includes a built-in checks framework that evaluates the health of your NATS infrastructure. Each check has default thresholds that can be overridden without code changes.

Add a check-thresholds section to your config file, keyed by check code:

check-thresholds:
  server-003:
    cpu_percent: 90.0
  stream-002:
    lag_percent: 10.0
  connection-001:
    rtt: 500ms

Threshold overrides are config-file only; there is no equivalent environment variable or CLI flag. To discover available checks and their configurable parameters, run insights checks list (or insights checks info <CODE> for one check's parameters), or see the Checks Reference.

Only checks that declare configurable parameters can be overridden. Every check's parameters and defaults are listed in the Threshold column of the Checks Reference, and config.example.yaml has an annotated example. An unknown check code or parameter name fails startup with an error naming it.

Can I turn a check off entirely?​

Yes. List its code under disabled-checks:

disabled-checks:
  - account-012

This is for checks that are structurally unactionable in your topology, not for noisy ones. Raise the threshold for those. account-012 (High Gateway Traffic Ratio) is the common example: in a single-account supercluster, cross-cluster gateway traffic is most of the traffic by design, so the check is above any threshold you set.

A disabled check keeps running and stays visible, marked disabled, with its real findings. It is left out of the health grades and never delivered as a notification: no advisory, no webhook, no alert. Re-enabling it changes nothing about its history; it simply starts counting and delivering again.

Like check-thresholds, this is config-file only, and it can also be set per entry under systems:. A per-system list adds to the top-level one and cannot re-enable a check disabled there. A code matching no check fails startup with an error naming it, and a code in the uppercase, underscored form (ACCOUNT_012) is reported with its current spelling; insights config check runs the same validation without starting the node.

How does TLS work for the web UI?​

TLS is disabled by default. Enable it with --web.tls, and supply your own certificate and key. Insights does not generate a self-signed certificate, and enabling TLS without a cert/key fails at startup:

./insights \
  --web.tls \
  --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.

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 Configuration: scraper.