Skip to main content

Data Retention

The Data Retention page configures how long historical data is kept before automatic cleanup. Proper retention management balances storage capacity, performance, and reporting needs.

Overview​

Data retention controls every historical store in the system:

  1. Attribute History: Sensor readings, device states, zone changes
  2. Request History: Commands, macro executions, API calls
  3. Access Log: Physical access control events
  4. Automation History: Every trigger fire, schedule fire, and macro run, with the upstream cause preserved across nested calls
  5. Alarm History: Closed alarm events — open events, and latched events still awaiting acknowledgement, are never pruned regardless of age
  6. Monitor History: Per-check monitor results and tag rollup transitions (both tables share one retention setting)
  7. Site Mode History: Site and space mode changes

Current Data Overview​

Each store's row shows live statistics: total record count, on-disk size, and the oldest record's date. A summary strip at the top of the page totals records and disk usage across all stores.

Monitoring:

  • Watch for excessive growth (>1M records)
  • Large tables impact query performance
  • Regular cleanup maintains speed

Retention Settings​

Configure retention period for each data type:

Attribute History​

Description: Sensor readings, device states, temperature logs

Retention Period: Days to keep (1-3650)

Default: 7 days

Recommendations:

  • Production systems: 90-180 days
  • Analytics-heavy: 180-365 days
  • Compliance requirements: Per regulation
  • Simple systems: 30-60 days

Purge Now: Manually delete records older than configured days

Request History​

Description: Commands, macro executions, model changes, admin-only operations, and denied API requests. Each record includes the user, result (granted/denied), and denial reason. See Request History for details.

Retention Period: Days to keep

Default: 7 days

Recommendations:

  • Standard: 30-90 days
  • Troubleshooting active: 180 days
  • Security auditing: 180-365 days
  • Minimal logging: 7-14 days
  • High-traffic: 30 days

Purge Now: Immediate cleanup

Access Log​

Description: Access control events (PIN, RFID)

Retention Period: Days to keep

Recommendations:

  • Security requirements: 90-365 days
  • Compliance (may require 1-7 years)
  • Standard: 180 days
  • Minimal: 30 days

Purge Now: Manual purge

Automation History​

Description: Trigger fires, schedule fires, and macro runs. Each row captures the upstream cause (trigger/schedule/auth_user) so cause chains stay intact across nested macro calls. Surfaced under the Run History tab on the macro / trigger / schedule editor and as the trigger-fires overlay on Attribute History.

Retention Period: Two separate windows — successful/skipped runs and failed/aborted runs.

SettingDefaultNotes
success days14Applies to status of success, skipped, or debounced
failure days180Applies to status of failed or aborted — kept longer because they matter longer

A per-artifact cap of 10,000 rows applies as a noisy-neighbor safety net even within the retention window — one chatty trigger cannot drown the table.

Recommendations:

  • Most installs: defaults are fine
  • Heavy automation debugging: success 30, failure 365
  • Storage-constrained: success 7, failure 90

Purge Now: Deletes runs older than the failure retention window; in-flight (running) entries are always kept.

Alarm History​

Description: Closed alarm events, including their notification delivery logs.

Retention Period: Days to keep (default 90)

Open alarms and latched events still awaiting acknowledgement are never pruned, by the daily job or by Purge Now — the retention window only applies to fully closed events.

Monitor History​

Description: Per-check monitor results (monitor_history) and tag rollup transitions (monitor_tag_history). One setting covers both tables.

Retention Period: Days to keep (default 30)

Prior to the unified retention system, these tables were pruned hourly by the monitoring engine with a fixed 30-day window; they now follow the daily maintenance job and this configurable setting.

Site Mode History​

Description: Site and space mode changes (set, held, released).

Retention Period: Days to keep (default 180)

Automatic Cleanup​

Schedule: Runs daily at 3 AM (server time)

Process:

  1. Identifies records older than retention period
  2. Deletes in batches (prevents performance impact)
  3. Logs results
  4. Optimizes database tables

Enable: Automatic cleanup runs if db_maintenance_enabled = true — toggled directly on this page ("Automatic daily maintenance enabled")

Manual Operations​

Save Settings​

Click Save Settings to:

  • Store retention periods
  • Apply to automatic cleanup schedule
  • No immediate data deletion

Reset​

Click Reset to reload the current saved settings, discarding any unsaved changes.

Run Maintenance Now​

Click Run Maintenance Now to:

  • Execute cleanup immediately
  • Delete records per current retention settings across all stores (attribute, request, access, automation, alarm, monitor, and site mode history)
  • Show the total records deleted

Confirmation: Required (destructive operation)

Purge Individual Tables​

Click Purge Now next to any table to:

  • Delete only that table's old records
  • Use that table's retention setting
  • Leave other tables unchanged

Use Cases:

  • Attribute history growing too fast
  • Need space immediately
  • Testing retention settings

Important Warnings​

Irreversible: Deleted data cannot be recovered

Backup First:

  • Create backup before purging
  • Especially before testing new retention settings

Compliance: Verify retention meets:

  • Legal requirements
  • Industry regulations
  • Company policies

Recommendations:

  • Attribute History: ≥30 days
  • Request History: ≥7 days
  • Access Log: ≥90 days

Retention Strategy​

Small Systems (<100 zones)​

Conservative Retention:

Attribute History: 180 days
Request History: 90 days
Access Log: 180 days

Storage Impact: Minimal (few MB to few GB)

Large Systems (>500 zones)​

Aggressive Retention:

Attribute History: 30 days
Request History: 14 days
Access Log: 90 days (compliance)

Storage Impact: Significant (10+ GB possible)

Compliance-Driven​

Extended Retention:

Attribute History: 365 days (1 year)
Request History: 365 days
Access Log: 2555 days (7 years for some regulations)

Mitigation:

  • Increase server storage
  • Export old data to archive
  • Use database optimization

Performance Impact​

Record Count Guidelines​

Attribute History:

  • <100K records: No impact
  • 100K-1M: Minor impact
  • 1M-10M: Moderate impact

  • 10M: Significant impact

Request History:

  • <10K: No impact
  • 10K-100K: Minor impact

  • 100K: Moderate impact

Access Log:

  • <50K: No impact
  • 50K-500K: Minor impact

  • 500K: Moderate impact

Optimization​

When tables grow large:

  1. Reduce Retention: Shorten retention periods
  2. Run Maintenance: Execute cleanup
  3. Archive Data: Export old data before purging
  4. Disable Unnecessary History: Remove history flag from unneeded attributes