Advanced Agent Configuration

Beyond the basics covered in Agent Configuration, the agent supports additional options for production deployments.

Additional Config Fields

api:
  endpoint: https://api.usebasira.com
  key: dbm_ak_your_key

databases:
  - name: primary-pg
    dsn: postgres://basira_monitor:pass@host:5432/db
    instance_id: prod-pg-01           # optional
    poll_interval: 10s                # default: 10s
    pg_log_dir: /var/log/postgresql   # optional, for auto_explain
    enabled_collectors:               # optional, nil = all
      - pg_stat_statements
      - pg_stat_activity

Field Reference

Field	Default	Description
`instance_id`	Assigned by API	Pre-assign a stable ID for this database instance. If omitted, the API assigns one on first heartbeat. Useful when you want consistent IDs across agent restarts.
`pg_log_dir`	—	Path to PostgreSQL log directory. Required for the `auto_explain` collector to read slow query plans from log files.
`enabled_collectors`	All collectors	List of collector names to enable. Only these collectors will run. See Collector Reference for available names.

Environment Variables

Variable	Default	Description
`BASIRA_CONFIG`	`./config.yaml`	Path to the config file. Falls back to `/etc/basira/config.yaml`.
`BASIRA_AGENT_ID`	Hostname	Agent identifier sent with telemetry.
`BASIRA_HEALTH_ADDR`	—	Override the health endpoint listen address (e.g., `:8081`).
`LOG_FORMAT`	`text`	Set to `json` for structured JSON logging.

Offline Buffering

When the API is unreachable, the agent buffers telemetry locally in a SQLite database:

Buffer location — basira_buffer_{name}.db in the working directory
Retention — buffered data is kept for 1 hour, then discarded
Drain — every 30 seconds, the agent retries pushing up to 10 buffered batches
Push interval — telemetry is pushed every 10 seconds when the API is reachable

This ensures no data loss during brief API outages or network interruptions.

Heartbeat

The agent sends a heartbeat to the API every 60 seconds. The heartbeat includes the database version and engine info. The API responds with:

Poll interval — dynamically adjust base-rate collector intervals
Disabled collectors — turn off specific collectors server-side
Feature flags — enable/disable EXPLAIN plan collection and replication monitoring

Changes take effect immediately without restarting the agent.

Health Monitoring

The agent monitors its own database connections:

Ping interval — 10 seconds
Reconnection — triggered after 3 consecutive ping failures
Backoff — exponential backoff (5s base, 5m max) with ±20% jitter

When the agent first connects with a database, if instance_id is not set, the API assigns one via the heartbeat response. The agent then uses this ID for all subsequent telemetry pushes. This means you don't need to manually register databases in the webapp before deploying the agent — the agent handles it automatically if you've registered the database through the dashboard or API first.