Configuration

./insights --config /etc/insights/config.yaml

# Insights Configuration Example
#
# Annotated example of the common configuration options with their defaults.
# Load this config with: insights --config config.yaml
#
# Configuration priority (highest wins):
#   1. CLI flags (e.g., --server)
#   2. Environment variables (e.g., INSIGHTS_NATS_SERVER)
#   3. Config file (this file)
#   4. Defaults

# Log level: debug, info, warn, error
log-level: 'info'

# License configuration.
# Provide either a raw JWT string or a path to a file containing the JWT.
# If both are set, the file takes precedence.
# Required in production builds. Not required when simulator is enabled or in dev builds (--tags insights_nolicense).
license:
  # Raw license JWT token string.
  # Env: INSIGHTS_LICENSE_TOKEN
  token: ''

  # Path to a file containing the license JWT.
  # Env: INSIGHTS_LICENSE_FILE
  file: ''

# Base directory for persistent storage (DuckDB database + JetStream data).
# If empty, a temporary directory is created and data is lost on restart.
# Set this for persistent deployments.
data-dir: ''

# Top-level NATS connection for serving the API.
# These credentials are used by the API server and as defaults
# for indexer and scraper if not explicitly configured.
nats:
  # NATS server URL
  server: ''

  # Path to credentials file (.creds)
  creds: ''

  # NATS context name (from nats context)
  context: ''

  # Username for basic auth
  user: ''

  # Password for basic auth
  password: ''

  # NKey seed for NKey+JWT auth (requires jwt to also be set)
  nkey: ''

  # User JWT for authentication.
  # If nkey is also set, used as NKey-signed JWT auth.
  # If standalone, used as a bearer token (server must have bearer_token enabled).
  jwt: ''

  # TLS certificate path
  tls-cert: ''

  # TLS key path
  tls-key: ''

  # TLS CA certificate path
  tls-ca-cert: ''

  # Perform TLS handshake first (before NATS protocol)
  tls-first: false

  # SOCKS proxy URL for connections
  socks-proxy: ''

# NATS system account credentials for the target system being scraped.
# This connection is used to issue $SYS requests to collect metrics.
# This is required if the simulator is disabled.
sys: {}

# Database configuration for DuckDB.
db:
  # DuckDB memory limit. Caps the buffer pool to prevent swapping on large databases.
  # Examples: "4GB", "8GB", "16GB". Default: "4GB".
  # Env: INSIGHTS_DB_MEMORY_LIMIT
  memory-limit: '4GB'

  # DuckDB worker threads. 0 uses DuckDB's default (all cores).
  # Reduce to leave cores for the indexer and web server.
  # Env: INSIGHTS_DB_THREADS
  threads: 0

  # Max wall-clock time a single $INS.db.query statement may run before it is interrupted.
  # Guards against a pathological query (e.g. a count over a cartesian relation, which is pure
  # CPU and never trips the memory limit) pegging the server. 0 disables the cap.
  # Env: INSIGHTS_DB_QUERY_TIMEOUT
  query-timeout: 2m

  # Max rows the non-streaming $INS.db.query endpoint may return. That endpoint buffers the
  # whole result before responding, so an unbounded SELECT * could return enough rows to run
  # the server out of memory (the DuckDB memory_limit does not bound this buffered reply).
  # Oversized results are rejected with a 413 pointing at the streaming endpoint
  # $INS.db.query.stream. 0 disables the cap.
  # Env: INSIGHTS_DB_QUERY_MAX_ROWS
  query-max-rows: 100000

  # Streaming query endpoint ($INS.db.query.stream). Pushes results as windowed Arrow IPC
  # chunks (rendered to CSV/JSON client-side) so arbitrarily large results never accumulate
  # in memory on either side, so it is not subject to the query-max-rows cap (it carries only
  # the large query-stream.max-rows safety limit below).
  query-stream:
    # Max chunks kept in flight unacknowledged before the server pauses producing. Bounds
    # client-side buffering to roughly window × chunk-size.
    # Env: INSIGHTS_DB_QUERY_STREAM_WINDOW
    window: 16

    # Target size of each chunk message (IEC units). Clamped below the connection max_payload.
    # Env: INSIGHTS_DB_QUERY_STREAM_CHUNK_SIZE
    chunk-size: 512KiB

    # Max time to produce each Arrow batch (incl. the first), bounding a stalled or slow-to-
    # first-row query. 0 disables.
    # Env: INSIGHTS_DB_QUERY_STREAM_BATCH_TIMEOUT
    batch-timeout: 30s

    # Abort the scan if the client sends no acknowledgement within this window (dead/Ctrl-C'd
    # consumer). 0 disables.
    # Env: INSIGHTS_DB_QUERY_STREAM_ACK_IDLE_TIMEOUT
    ack-idle-timeout: 30s

    # Per-buffer Arrow IPC compression for streamed chunks: none, lz4, or zstd. Clients
    # decompress transparently. Compression uses additional CPU; leave none unless bandwidth
    # is the bottleneck.
    # Env: INSIGHTS_DB_QUERY_STREAM_COMPRESSION
    compression: none

    # Abort a streamed query after this many rows, failing fast with guidance to scope it.
    # Streaming stays memory-bounded, so this is not a memory guard — it is a safety limit
    # against an unscoped SELECT * over a per-epoch table/view tying up the endpoint. Bounded
    # queries (epoch-scoped, entity-scoped, or LIMITed) never reach it. 0 disables the cap.
    # Env: INSIGHTS_DB_QUERY_STREAM_MAX_ROWS
    max-rows: 1000000

  # Retention policy for automatic epoch cleanup from DuckDB.
  retention:
    # How long to keep data. 0 disables retention.
    # Env: INSIGHTS_DB_RETENTION_DURATION
    duration: 768h

    # How often the retention sweep runs.
    # Env: INSIGHTS_DB_RETENTION_INTERVAL
    interval: 10m

  # Live memory profiler: samples duckdb_memory() so `ops sizing` and
  # `ops memory` can use measured peaks instead of estimates.
  memory-profile:
    # Enable the background memory profiler.
    # Env: INSIGHTS_DB_MEMORY_PROFILE_ENABLED
    enabled: true

    # How often to sample duckdb_memory() (metadata-cheap).
    # Env: INSIGHTS_DB_MEMORY_PROFILE_INTERVAL
    interval: 2s

    # Rolling window retained in memory for the peak and the Realtime chart.
    # Env: INSIGHTS_DB_MEMORY_PROFILE_WINDOW
    window: 15m

# Scraper configuration for collecting metrics from NATS servers.
scraper:
  # Enable or disable the scraper
  enabled: true

  # Timeout for scrape requests
  timeout: 30s

  # Interval between scrapes
  interval: 1m

  # Optional NATS connection for publishing scraped data.
  # If not specified, uses the indexer NATS config (or top-level NATS).
  nats: {}

# Indexer configuration for processing and storing scraped data.
indexer:
  # Enable or disable the indexer
  enabled: true

  # Start consuming from the latest message in the stream
  stream-latest: false

  # Start consuming from a specific epoch number
  stream-epoch: 0

  # Filter specific Z endpoints to process (comma-separated: varz,jsz,connz)
  stream-filters: ''

  # Downsample interval for consuming epochs
  stream-interval: 0s

  # Optional NATS connection for consuming scraped data.
  # If not specified, uses the top-level NATS config.
  nats: {}

# Sink configuration for the embedded NATS server.
sink:
  # Use an embedded NATS server for storing scraped data.
  embed: true

  # Optional NATS server config file for the embedded server.
  # The file is parsed first, then Insights-specific settings are applied on top.
  # config-file: /path/to/nats-server.conf

  # Host to bind the embedded NATS server to
  host: '127.0.0.1'

  # Port to bind the embedded NATS server to (0 = random)
  port: 0

  # JetStream stream name for storing scraped data
  stream: 'scrape'

  # Batch size for sink operations
  batch-size: 500

  # How long to keep scraped data in the sink stream. 0 disables retention.
  # Env: INSIGHTS_SINK_RETENTION
  retention: 24h

# Embedded NATS simulator configuration.
# When enabled, starts real in-process NATS clusters with traffic workloads
# so you can try insights with zero configuration.
simulator:
  # Enable the embedded simulator
  enabled: false

  # Profiles: core-{small,medium,large}, js-{small,medium,large},
  #   super-{small,medium,large}, leaf-{small,medium,large},
  #   super-leaf-{small,medium,large}
  profile: 'js-small'

# Web server configuration for the Exo-based UI.
web:
  # Enable or disable the web server
  enabled: true

  # Hostname to bind the web server to
  hostname: '127.0.0.1'

  # Port to bind the web server to
  port: 8080

  # Session seed for secure cookies.
  # The default "insights" preserves sessions across restarts but should be
  # changed to a unique value for production deployments.
  session-seed: 'insights'

  # Enable TLS (HTTPS). When enabled, HTTP/2 is automatically available via ALPN.
  # You must provide tls-cert and tls-key below; enabling TLS without them fails at
  # startup (no self-signed certificate is generated).
  tls: false

  # Path to TLS certificate file.
  tls-cert: ''

  # Path to TLS private key file.
  tls-key: ''

  # Path to TLS CA certificate file for verifying client certificates.
  tls-ca-cert: ''

  # Timeout for collecting metrics
  metrics-timeout: 30s

  # Interval between metrics scrapes
  metrics-interval: 1s

# Prometheus metrics endpoint configuration.
# Exposes check failure counts as Prometheus gauges for external scraping.
prometheus:
  # Enable or disable the Prometheus metrics endpoint
  enabled: true

  # Hostname to bind the Prometheus metrics server to
  hostname: '127.0.0.1'

  # Port to bind the Prometheus metrics server to
  port: 9091

# Backup configuration for creating transactionally safe DuckDB backups.
# Backups are created via NATS micro service endpoints and optionally
# uploaded to a NATS object store for remote access.
backup:
  # TTL for backup files uploaded to the NATS object store.
  # After this duration, uploaded backups are automatically deleted.
  # Env: INSIGHTS_BACKUP_OBJECT_STORE_TTL
  object-store-ttl: 24h

# Version checker configuration.
# When enabled, periodically checks GitHub for a newer release and notifies
# via a log message and a badge in the web UI. Does not download or restart.
# The release repository is baked into the binary at build time, so there is
# no URL or channel to configure.
# For licensed builds, the info dialog shows a direct download link for
# the current OS/architecture. For nolicense builds, users are directed
# to purchases.synadia.com.
updater:
  # Enable or disable version checking
  enabled: true

  # Interval between update checks
  interval: 1h
# Per-check threshold overrides for the audit checks (optional, YAML-only — there
# is no equivalent flag or environment variable).
# Many audit checks accept tunable parameters (a CPU percentage, a lag percentage,
# a byte size, ...) that control when they produce a finding. Defaults suit most
# deployments; override only what you need, keyed by check code and parameter name.
# Run `insights checks list` for codes and `insights checks info <CODE>` for the
# parameters a check accepts. Duration parameters take Go duration strings (e.g.
# 5m, 1h) and must be >= the scrape interval. Unknown parameters are logged and
# ignored; unknown check codes are silently skipped.
# Example (uncomment and adjust):
# check-thresholds:
#   SERVER_003:
#     cpu_percent: 80        # flag servers at or above 80% per-core CPU (default 90)
#   JETSTREAM_001:
#     lag_percent: 20        # flag stream replica lag at or above 20% (default 10)
#   OPT_COST_002:
#     max_memory_mib: 500    # flag memory-backed streams above 500 MiB (default 100)
#   # Optimization checks (codes prefixed OPT_) also accept `lookback`, the analysis
#   # window for range-based checks (default 6h):
#   OPT_PLACE_001:
#     lookback: 4h

# Outbound notification endpoints (optional, YAML-only). Delivers an alert to an
# external endpoint when an audit check changes state. `webhook` endpoints receive
# the full Alertmanager-compatible envelope; `alertmanager` endpoints receive a bare
# alert array for the Alertmanager v2 /api/v2/alerts API. Set web.external-url so
# alert links resolve. Example (uncomment and adjust):
# notifications:
#   webhook:
#     - name: "PagerDuty Relay"
#       url: "https://example.com/webhook"
#       auth-type: "bearer"           # "", basic, bearer, hmac
#       auth-token: "…"
#       subscriptions: [SERVER_001, JETSTREAM_001]
#   alertmanager:
#     - name: "local-am"
#       url: "http://localhost:9093/api/v2/alerts"
#       subscriptions: [SERVER_001]

check-thresholds:
  SERVER_003:
    cpu_percent: 80 # flag servers >= 80% CPU (default: 90)
  JETSTREAM_001:
    lag_percent: 20 # flag replica lag >= 20% (default: 10)
  OPT_COST_002:
    max_memory_mib: 500 # memory-backed streams > 500 MiB

check-thresholds:
  OPT_PLACE_001:
    lookback: 4h

notifications:
  webhook:
    - name: 'PagerDuty Relay'
      url: 'https://example.com/webhook'
      auth-type: 'bearer'
      auth-token: '…'
      subscriptions: [SERVER_001, JETSTREAM_001]
  alertmanager:
    - name: 'local-am'
      url: 'http://localhost:9093/api/v2/alerts'
      subscriptions: [SERVER_001]