Backup, retention and disk usage

Backup, retention and disk usage

BxLens has no database. It writes a few small files, and with BoxLang+ a store folder. This page lists all of them, says which ones matter and shows how retention and the size cap work.

What is written, and where

Paths are relative to the BoxLang home (the runtime home), unless a setting says otherwise.

The store folder, for one server web-a:

lens-data/
  web-a/
    instance.json                heartbeat: who this is, last write
    errors.json                  error groups with samples
    reports.json                 report totals
    health.json                  the health snapshot, saved every minute
    notifications.json           notification settings of the cluster (no secrets)
    alert-state.json             what was already announced, per person and channel
    reports-state.json           which report was sent last
    daily-2026-10-21.json        the day's numbers for the email reports
    http-rollup-2026-10-21.json  outgoing HTTP, buckets of ten minutes
    ai-rollup-2026-10-21.json    AI numbers, buckets of ten minutes
    ai-runs-2026-10-21.jsonl     one line per AI run
    http-calls-2026-10-21.jsonl  one line per outgoing call (collect.level full)

Everything in it is redacted data. No request bodies, no bound query values, no text of a sent mail and no secret in plain text. See The store.

Never in the store, and lost at a restart: the request history, the query statistics, in flight data and the list of Mail messages. They are in memory only.

On Free the store is not used. The files that remain are the registration file, the Secret Store, the audit log, and the settings and layout files when you have saved something.

What to back up

A lost key does not harm BxLens. The stored secrets stay closed: BxLens uses boxlang.json again for the console password, and you enter the SMTP password, the AI key and the channel addresses again. See Restore.

Retention

Saved data is kept by day (UTC). Three rules, all boxlang.json only because they delete data of other servers:

Pruning runs every ten minutes and at the first start.

• The monthly email report covers the calendar month before this one, from the days that are saved. With a retention of 15 days it finds about half a month, and says so ("Data found for N of M server days"). Set store.retentionDays to 30 if you want full monthly reports.
• The fair share matters on a shared volume: with maxMB 500 and 10 servers, each keeps about 50 MB. Raise maxMB with the number of servers.
• A folder over the cap comes back under it after every server has pruned once.
• Settings, Storage shows the current values read only. A change needs a restart.

{
	"modules": {
		"bxLens": {
			"settings": {
				"store": { "retentionDays": 30, "maxMB": 2000, "staleAfterHours": 24 }
			}
		}
	}
}

Disk usage

• Settings, Storage (admin) shows Used against of N MB, the records written, dropped, failed and queued, the last error, and each server in the folder with its size and last write.
• The System page lists the volumes and the folders BxLens writes to, with amber and red at volumes.warnPct (80) and volumes.critPct (90). The Disk space alert (BoxLang+) mails you at 90 percent by default.
• Dropped above zero means the queue (store.queueSize, 20000) was full and records were thrown away. Failed above zero means a write error: read the last error. A full disk or a read only volume is counted and never blocks a request.
• How much a server writes depends on your traffic and on collect.level. At light the HTTP rollups hold totals by host and endpoint. At full the list of single calls is written too. Watch Used for a few days before you set the cap.
• The audit log has no limit of its own. BxLens does not rotate or trim it. It writes through the BoxLang logging service, so check how your BoxLang logging configuration rotates the logs directory.

Restore

1. Stop BoxLang.
2. Put back boxlang.json, the config/bxlens-* files and the secrets folder. Put the key where it was: secrets.key in the secrets folder, or LENS_SECRETS_KEY in the environment.
3. Put back notifications.json into store.dir/<your folder name>/ if you use alerts. A server reads the newest copy from any server folder, so the one in the restored folder is found.
4. Start BoxLang. Open Settings, Storage: the Secrets card should say This server can open them: yes, and the servers list should show your folder.

If the key is missing, the card says no. The values are not damaged. Restore the key and they open. If a console password was set in the console and its hash cannot be opened, the page says the console value is unreadable and boxlang.json is used.

To start clean, stop BoxLang and delete store.dir/<your folder name>/. You lose history and, for that folder, the notification settings and the alert state.