Skip to main content

Attribute History

The Attribute History page displays historical data for any attribute with history tracking enabled. It provides charts, statistics, and analysis of how attribute values change over time.

Overview​

Attribute History enables:

  • Time-Series Charts: Visual representation of attribute changes
  • Statistics: Count, first, and last for any attribute; min, max, and average for numeric ones
  • Aggregation: No aggregation, 5-minute, hourly, or daily rollups
  • Comparison: Multiple attributes on same chart
  • Export: Download data as CSV

Selecting Data​

System Target​

Choose entity type to analyze:

  • zone
  • device
  • subsystem
  • variable
  • monitor
  • etc.

Target Object​

Select specific entity:

  • After choosing system target, dropdown populates with entities
  • Example: Select zone → dropdown shows all zones

Once a target is selected, an open <name> link appears under the dropdown. It opens that record in a reference modal over the chart, so reading a spike and then checking the device or zone that produced it doesn't cost you the chart, the date window, or any series you have already added. Targets with no editor of their own (variable, monitor) show no link.

Attribute​

Select which attribute to chart:

  • Only shows attributes with history enabled
  • Example: temperature, power, level, etc.

Chart Configuration​

Date Range​

Start Date: Beginning of historical period End Date: End of historical period

Quick Range Buttons:

  • 1H - Last 1 hour
  • 1D - Last 1 day
  • 1W - Last 1 week
  • 1M - Last 1 month

Aggregation​

No Aggregation: Raw recorded data points

note

"Raw" means every row in the history table, which is not necessarily every value the device reported. Fast-polling analog values (power, energy, flow) are sampled with a deadband before they are stored — see History Deadband. Integer, string, and boolean attributes are stored on every change.

5 Minutes: Aggregate into 5-minute buckets

1 Hour: Aggregate by hour

  • Average value per hour

1 Day: Aggregate by day

  • Average value per day
note

Automatic aggregation only applies to numeric (int/float) attributes. A long date range on a bool, string, json, or date attribute stays on the raw path so the individual transitions are preserved — averaging a state value would throw away exactly what makes it readable. You can still pick a bucket size explicitly for those attributes; each bucket then charts its representative value rather than an average.

Chart Type​

Line: Default, shows trends Bar: Good for discrete values Area: Emphasizes magnitude Scatter: Individual data points Heatmap (DoW × HoD): Averages bucketed by day-of-week × hour-of-day. Best for surfacing routines (when does HVAC run hardest, when is the room occupied). Requires numeric data.

Compare to Previous​

Toggle to overlay the same attribute from the previous period of equal length. The overlay renders as a dashed series labeled previous: <attribute> with timestamps shifted forward so the prior week (or day, or month) lines up visually with the current window. Most useful for spotting week-over-week or day-over-day deviations.

Trigger Fires Overlay​

When enabled, vertical markers appear on the chart at every point in the visible window where an attribute trigger fired for the displayed attribute. Marker colors:

  • Green: trigger fired successfully
  • Red: trigger fired but an action failed
  • Grey (dashed): trigger conditions matched but the fire was skipped — usually because the day/hour mask blocked it or because the debounce window was still active

Marker data is sourced from the automation_history table — see Automation History below.

Automation History​

GEM records every automation execution to an automation_history table, complementing the per-artifact summary rows used for reactive debugging:

  • Triggers: every fire (and every condition-matching skip due to mask/debounce)
  • Schedules: every cron fire, plus the macro it dispatched
  • Macros: every run, with the upstream cause (trigger/schedule/ui) preserved across nested macro calls so you can answer "what real-world event caused this?"

Rows include started_at, finished_at, status (success/failed/skipped), caused_by_type/caused_by_id, parent_run_id, and a context JSON with type-specific extras (the attribute that changed, the macro that ran, error messages, etc.). caused_by_* stays pinned to the root cause (the trigger, schedule, or UI action that started the chain), while parent_run_id records the immediate parent row — so a macro that runs another macro gets the calling macro's row id as its parent, building an edge-by-edge call graph.

Retention is configured under Data Retention with two windows:

  • success days (default 14): how long to keep success, skipped, and debounced rows
  • failure days (default 180): how long to keep failed and aborted rows

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

Statistics Panel​

Shows computed statistics for selected data:

  • Min: Lowest value in range
  • Max: Highest value in range
  • Avg: Mean value
  • Count: Number of data points
  • First: First value in range
  • Last: Most recent value in range

Min, Max, and Avg describe a magnitude, so they only appear for int and float attributes. With an aggregation selected, a bool, string, json, or date attribute shows just Count, First, and Last — printed as the stored value (true, armed, a timestamp) rather than as a rounded number. With No Aggregation, the panel is shown for numeric series only.

Non-Numeric Attributes​

bool, string, and json attributes chart on a category axis: each distinct value gets its own line on the chart (disarmed, armed_home, armed_away) and the y-axis is labeled by value instead of by magnitude. That is the right way to read a state series — what you want from it is when it changed and what it changed to. (date values chart as timestamps, on a normal numeric axis.)

note

Earlier versions failed outright on these attributes: the statistics query asked the database for a minimum, maximum, and average of a boolean or text column, which it cannot compute, so the whole report errored and the chart reported "Failed to fetch aggregated data". Only int and float attributes charted at all. Nothing needs to be re-enabled — existing history rows chart correctly as soon as the page is reloaded.

Export​

Click Export CSV to download the currently displayed data as a CSV file for external analysis.

Multiple Attributes​

Compare multiple attributes on same chart:

  1. Select first attribute, add to chart
  2. Select different attribute, add to chart
  3. Both series display on same chart with independent colors
  4. Useful for correlation analysis

Examples:

  • Temperature vs. setpoint
  • Power consumption vs. outside temperature
  • Multiple room temperatures

Common Use Cases​

Temperature Monitoring​

Track HVAC performance:

Configuration:

System Target: zone
Target: living_room_thermostat
Attribute: temperature
Date Range: Last 7 days
Aggregation: Hour

Analysis:

  • Temperature stability
  • HVAC cycle frequency
  • Correlation with setpoint changes
  • Energy efficiency

Energy Usage​

Monitor power consumption:

Configuration:

System Target: device
Target: main_power_meter
Attribute: power_usage
Date Range: Last 30 days
Aggregation: Day

Analysis:

  • Daily usage patterns
  • Peak consumption times
  • Day-of-week variations
  • Month-over-month trends

Zone Usage Patterns​

Understand room utilization:

Configuration:

System Target: zone
Target: conference_room_occupancy
Attribute: occupied
Date Range: Last 90 days
Aggregation: Day

Analysis:

  • Room occupancy rates
  • Busiest days
  • Underutilized spaces

Monitor environmental sensors:

Configuration:

System Target: zone
Target: outdoor_sensor
Attribute: humidity
Date Range: Last year
Aggregation: Week

Analysis:

  • Seasonal humidity patterns
  • Irrigation scheduling
  • Mold risk assessment

Storage and Performance​

Attribute history is the highest-volume table in the system, and two mechanisms keep it usable:

  • Deadband sampling on fast-moving analog values, so the table records signal rather than jitter. Configured with the history_deadband_percent and history_deadband_max_interval system attributes, or per attribute from Top Attribute History Writers — see History Deadband.
  • Indexes on (system_target, target_id, name, timestamp) and on timestamp, covering the per-series chart reads on this page, the "latest value" lookups, and the nightly retention prune. They are created automatically at startup; on a large existing table the first boot after upgrading spends a few seconds building them.

Retention is configured under Data Retention, and the nightly prune deletes in bounded batches so a large sweep doesn't block live attribute writes.