Synadia Insights
Configuration
Insights uses a layered configuration system. Every setting can be specified through CLI flags, environment variables, or a YAML config file.
Priority Order
When the same setting is defined in multiple places, the highest-priority source wins:
- CLI flags (e.g.,
--nats.server nats://host:4222) - Environment variables (e.g.,
INSIGHTS_NATS_SERVER=nats://host:4222) - YAML config file (loaded via
--config config.yaml) - Built-in defaults
Config File
Load a YAML config file with the --config (or -c) flag:
./insights --config /etc/insights/config.yaml
For a complete annotated example, see config.example.yaml.
Environment Variable Naming
Every flag has a corresponding environment variable. The naming convention is:
- Start with the
INSIGHTS_prefix - Replace dots with underscores
- Convert to uppercase
| Flag | Environment Variable |
|---|---|
--log-level | INSIGHTS_LOG_LEVEL |
--data-dir | INSIGHTS_DATA_DIR |
--nats.server | INSIGHTS_NATS_SERVER |
--sys.creds | INSIGHTS_SYS_CREDS |
--scraper.interval | INSIGHTS_SCRAPER_INTERVAL |
--web.port | INSIGHTS_WEB_PORT |
--db.retention.duration | INSIGHTS_DB_RETENTION_DURATION |
--sink.retention | INSIGHTS_SINK_RETENTION |
--simulator.enabled | INSIGHTS_SIMULATOR_ENABLED |
Nested sections add their prefix. For example, a scraper NATS connection uses INSIGHTS_SCRAPER_NATS_SERVER.
Configuration Sections
log-level
Controls logging verbosity. Accepted values: debug, info, warn, error.
| Flag | Env | Default |
|---|---|---|
--log-level | INSIGHTS_LOG_LEVEL | info |
license
License key for production deployments. Provide either a raw JWT string or a path to a file containing the JWT. If both are set, the file takes precedence.
A license is required for production use. It is not required when the simulator is enabled (--simulator.enabled). See Installation › Configure a License for how to obtain and configure a license, and Trial for evaluation.
| Flag | Env | Default |
|---|---|---|
--license.token | INSIGHTS_LICENSE_TOKEN | (empty) |
--license.file | INSIGHTS_LICENSE_FILE | (empty) |
data-dir
Base directory for persistent storage. This directory holds the DuckDB database file (insights.db) and JetStream data (nats/).
When unset, a temporary directory is created and all data is lost on restart. Set this for any deployment where you want data to survive restarts.
| Flag | Env | Default |
|---|---|---|
--data-dir | INSIGHTS_DATA_DIR | (temp dir) |
sys.*: System Account Connection
NATS connection used to scrape the target NATS system. Insights issues $SYS requests over this connection to collect server metrics. This is required when the simulator is disabled.
| Flag | Env | Description |
|---|---|---|
--sys.server | INSIGHTS_SYS_SERVER | NATS server URL |
--sys.creds | INSIGHTS_SYS_CREDS | Path to credentials file (.creds) |
--sys.context | INSIGHTS_SYS_CONTEXT | NATS context name (from nats context) |
--sys.user | INSIGHTS_SYS_USER | Username for basic auth |
--sys.password | INSIGHTS_SYS_PASSWORD | Password for basic auth |
--sys.nkey | INSIGHTS_SYS_NKEY | NKey seed for authentication |
--sys.jwt | INSIGHTS_SYS_JWT | User JWT for authentication |
--sys.tls-cert | INSIGHTS_SYS_TLS_CERT | TLS certificate path |
--sys.tls-key | INSIGHTS_SYS_TLS_KEY | TLS key path |
--sys.tlsca | INSIGHTS_SYS_TLS_CA | TLS CA certificate path |
--sys.tls-first | INSIGHTS_SYS_TLS_FIRST | Perform TLS handshake before NATS protocol |
--sys.socks-proxy | INSIGHTS_SYS_SOCKS_PROXY | SOCKS proxy URL |
nats.*: Top-Level NATS Connection
NATS connection used by the API server and as the default for the indexer and scraper if they do not specify their own connections.
This connection is only needed when using an external NATS sink (--sink.embed=false). When the embedded sink is enabled (the default), Insights manages its own internal NATS server automatically.
The flags mirror sys.* above. Just swap the sys. prefix for nats. (for example, --nats.server, --nats.creds).
Connection fallback order: scraper.nats falls back to indexer.nats, which falls back to nats (top-level).
db.*: Database
DuckDB configuration options.
| Flag | Env | Default | Description |
|---|---|---|---|
--db.memory-limit | INSIGHTS_DB_MEMORY_LIMIT | 4GB | DuckDB memory limit. Caps the buffer pool to prevent swapping |
--db.threads | INSIGHTS_DB_THREADS | 0 | DuckDB worker threads (0 = auto, uses all cores) |
--db.retention.duration | INSIGHTS_DB_RETENTION_DURATION | 768h | How long to keep data in DuckDB (0 = disabled) |
--db.retention.interval | INSIGHTS_DB_RETENTION_INTERVAL | 10m | How often the retention sweep runs |
scraper.*: Scraper
Controls how Insights collects metrics from NATS servers.
| Flag | Env | Default | Description |
|---|---|---|---|
--scraper.enabled | INSIGHTS_SCRAPER_ENABLED | true | Enable or disable the scraper |
--scraper.interval | INSIGHTS_SCRAPER_INTERVAL | 1m | Time between scrape cycles |
--scraper.timeout | INSIGHTS_SCRAPER_TIMEOUT | 30s | Timeout for individual scrape requests |
The scraper optionally accepts its own NATS connection via --scraper.nats.* flags, falling back to the indexer NATS and then the top-level NATS connection.
indexer.*: Indexer
Controls how scraped data is processed and stored in DuckDB.
| Flag | Env | Default | Description |
|---|---|---|---|
--indexer.enabled | INSIGHTS_INDEXER_ENABLED | true | Enable or disable the indexer |
--indexer.stream-latest | INSIGHTS_INDEXER_STREAM_LATEST | false | Start consuming from the latest message |
--indexer.stream-epoch | INSIGHTS_INDEXER_STREAM_EPOCH | 0 | Start consuming from a specific epoch number |
--indexer.stream-filters | INSIGHTS_INDEXER_STREAM_FILTERS | (empty) | Comma-separated list of endpoints to process (e.g., varz,jsz,connz) |
--indexer.stream-interval | INSIGHTS_INDEXER_STREAM_INTERVAL | 0s | Downsample interval. Skip epochs closer together than this |
web.*: Web Server
Controls the built-in web UI and HTTP server.
| Flag | Env | Default | Description |
|---|---|---|---|
--web.enabled | INSIGHTS_WEB_ENABLED | true | Enable or disable the web server |
--web.hostname | INSIGHTS_WEB_HOSTNAME | 127.0.0.1 | Bind hostname (0.0.0.0 for all interfaces) |
--web.port | INSIGHTS_WEB_PORT | 8080 | Bind port |
--web.session-seed | INSIGHTS_WEB_SESSION_SEED | insights | Seed for secure session cookies |
--web.tls | INSIGHTS_WEB_TLS | false | Enable TLS (HTTPS). HTTP/2 is automatically available via ALPN |
--web.tls-cert | INSIGHTS_WEB_TLS_CERT | (empty) | Path to TLS certificate. Empty auto-generates a self-signed cert |
--web.tls-key | INSIGHTS_WEB_TLS_KEY | (empty) | Path to TLS private key. Empty auto-generates a self-signed key |
--web.metrics-timeout | INSIGHTS_WEB_METRICS_TIMEOUT | 30s | Timeout for collecting metrics |
--web.metrics-interval | INSIGHTS_WEB_METRICS_INTERVAL | 1s | Interval between metrics scrapes |
TLS behavior: When enabled, if no certificate or key paths are provided, a self-signed certificate is automatically generated. For production, supply your own certificate and key files.
Session seed: The default value "insights" preserves sessions across restarts but should be changed to a unique secret for production deployments.
sink.*: Embedded Sink
Controls the embedded NATS server used for storing scraped data as a JetStream stream.
| Flag | Env | Default | Description |
|---|---|---|---|
--sink.embed | INSIGHTS_SINK_EMBED | true | Use the embedded NATS server |
--sink.host | INSIGHTS_SINK_HOST | 127.0.0.1 | Bind host for the embedded server |
--sink.port | INSIGHTS_SINK_PORT | 0 | Bind port (0 = random) |
--sink.stream | INSIGHTS_SINK_STREAM | scrape | JetStream stream name |
--sink.batch-size | INSIGHTS_SINK_BATCH_SIZE | 500 | Batch size for sink operations |
--sink.retention | INSIGHTS_SINK_RETENTION | 24h | How long to keep scraped data in the sink stream (0 = unlimited) |
Set --sink.embed=false to use an external NATS cluster with JetStream instead of the embedded server. See the deployment guide for external sink topologies.
simulator.*: Simulator
The built-in simulator starts real in-process NATS clusters with traffic workloads, allowing you to explore Insights with zero external dependencies.
| Flag | Env | Default | Description |
|---|---|---|---|
--simulator.enabled | INSIGHTS_SIMULATOR_ENABLED | false | Enable the embedded simulator |
--simulator.profile | INSIGHTS_SIMULATOR_PROFILE | js-small | Simulator profile |
Available profiles control the size and topology of the simulated deployment:
| Profile Family | Variants | Description |
|---|---|---|
core- | small, medium, large | Core NATS servers |
js- | small, medium, large | NATS with JetStream |
super- | small, medium, large | Super-cluster topology |
leaf- | small, medium, large | Leaf node topology |
super-leaf- | small, medium, large | Super-cluster with leaf nodes |
backup.*: Backup
Controls database backup behavior. Backups are created via the NATS micro API and can optionally be uploaded to a NATS object store for remote access.
| Flag | Env | Default | Description |
|---|---|---|---|
--backup.object-store-ttl | INSIGHTS_BACKUP_OBJECT_STORE_TTL | 24h | TTL for backups uploaded to the NATS object store. After this duration, uploaded backups are automatically deleted |