Agent Configuration

Use the same YAML format whether you are monitoring one database or many. One database is just one entry in databases.

YAML Config Format

api:
  endpoint: https://api.usebasira.com  # optional, defaults to http://localhost:8080
  key: dbm_ak_your_api_key             # required

health:
  listen_addr: :8081                   # optional

databases:
  - name: primary-pg                   # required — unique name
    dsn: postgres://basira_monitor:password@pg-primary:5432/myapp?sslmode=require
    engine: postgres                   # optional, auto-detected from DSN
    poll_interval: 10s                 # optional, defaults to 10s

  - name: analytics-ch
    dsn: clickhouse://basira_monitor:password@ch-analytics:9000/analytics
    poll_interval: 30s

Field Reference

`api` (required)

Field	Required	Default	Description
`endpoint`	No	`http://localhost:8080`	Basira API URL
`key`	Yes	—	API key from the dashboard

`health` (optional)

Field	Required	Default	Description
`listen_addr`	No	disabled	Health server listen address, e.g. `:8081`

`databases[]` (at least one required)

Field	Required	Default	Description
`name`	No	`db-{index}`	Name for this database
`engine`	No	Auto-detected from DSN	`postgres` or `clickhouse`
`dsn`	Yes	—	Connection string (must point to a single instance — see warning below)
`poll_interval`	No	`10s`	How often to collect metrics (Go duration: `10s`, `1m`, etc.)

Engine auto-detection: If engine is omitted, the agent detects PostgreSQL vs ClickHouse from the DSN.

Use a direct instance endpoint

⚠ Do not use cluster, load-balancer, or proxy endpoints (e.g. Aurora cluster endpoints, Cloud SQL connection poolers, or ClickHouse load-balanced URLs) as the DSN host.

The agent assumes every connection reaches the same physical database instance. A load-balanced endpoint can route successive connections to different backends, which causes:

Inconsistent query stats — pg_stat_statements counters differ per backend, so deltas between polls become meaningless.
Mixed active-query snapshots — each poll may show sessions from a different node.
Divergent table/index stats — replicas can lag behind the primary.

Always use a specific instance endpoint — the primary writer for write-path monitoring, or a specific replica if you want read-traffic telemetry. To monitor multiple nodes, add each as a separate entry in databases.

Validation rules:

api.key is required
Database names must be unique
At least one database entry is required
dsn is required per database
engine, when set, must be postgres or clickhouse

Hot Reload

The agent watches the config file for changes. When you update the file, the agent automatically starts, stops, or restarts per-database collectors to match.

Examples

One PostgreSQL Database

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

databases:
  - name: app-primary
    dsn: postgres://basira_monitor:pass@pg-primary:5432/app?sslmode=require
    poll_interval: 10s

One ClickHouse Database

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

databases:
  - name: events-ch
    dsn: clickhouse://basira_monitor:pass@ch-events:9000/events
    poll_interval: 30s

Mixed PostgreSQL + ClickHouse

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

databases:
  - name: app-pg
    dsn: postgres://basira_monitor:pass@pg-primary:5432/app?sslmode=require

  - name: analytics-ch
    dsn: clickhouse://basira_monitor:pass@ch-analytics:9000/analytics
    poll_interval: 30s

Kubernetes and Helm

Helm Values Shape

The Helm chart uses the same idea: a databases list. One database means one item; multiple databases means multiple items.

# values.yaml
apiKey: "dbm_ak_your_key"
apiEndpoint: "https://api.usebasira.com"
databases:
  - name: app-pg
    dsn: postgres://basira_monitor:pass@pg-host:5432/app?sslmode=require
    pollInterval: 10s

Add more entries under databases to monitor more databases from the same agent release.

Raw Config File

If you are not using Helm, mount a config file with the same YAML shape shown above.

Health Endpoint

If you set health.listen_addr, the agent exposes /healthz on that address.

Troubleshooting

Verify Installation

Check the agent logs:

# Docker
docker logs basira-agent --tail=20

# Kubernetes
kubectl logs deployment/basira-agent --tail=20

Check the health endpoint if you enabled it:

curl -s http://localhost:8081/healthz | jq .

Then open Basira and confirm the database appears and starts reporting telemetry.

Common Issues

"no config file found" — Set BASIRA_CONFIG to point to your YAML config file, or place config.yaml in the agent's working directory.

"at least one database entry is required" — Your config file has an empty databases list.

"duplicate name" — Two databases have the same name. Names must be unique.

"unsupported engine" — The engine field must be postgres or clickhouse. Remove it to auto-detect from the DSN.

"poll_interval: time: invalid duration" — poll_interval must be a Go duration like 10s, 30s, or 1m.

Health endpoint is missing — Set health.listen_addr in your YAML config.

Database does not appear in Basira — Check connectivity, DSNs, API key, and agent logs.

Agent Configuration

On this page