Long-Term Home Assistant History With InfluxDB and Grafana

The built-in history page forgets everything after ten days — here's keeping years

Contents

I wanted to know whether my heating had actually gotten more efficient after adding insulation last winter, and Home Assistant had no answer for me. The built-in history page shows a nice graph of any entity’s recent state — but “recent” means whatever purge_keep_days is set to, ten days by default, and the SQLite database backing it isn’t designed for the kind of long-range aggregate queries I wanted anyway. Comparing this January’s average living-room temperature to last January’s is a question Home Assistant’s own storage simply cannot answer, by design — the recorder exists to make the UI responsive today, not to be a historical archive. Getting a real answer meant sending the data somewhere actually built for that job.

Why the built-in recorder isn’t the right tool for this

Home Assistant’s recorder writes every state change to a relational database — SQLite by default, though Postgres and MariaDB are supported — and that database backs the Logbook and the recent-history graphs you see in the UI. It’s optimised for exactly that: fast lookups of an entity’s recent states, rendered as a chart on demand. It was never meant to be a data warehouse, and pushing purge_keep_days up into the hundreds to fake long-term storage makes the database progressively slower for the job it’s actually doing, since every state change for every entity accumulates in a schema not designed for that scale.

A DHT22 temperature and humidity sensor module on a small circuit board.
A hobby-grade temperature and humidity sensor of the kind that produces the steady stream of readings a time-series database stores. Photo: DHT22 digital temperature and humidity sensor module pcb by Suyash Dwivedi, CC BY-SA 4.0, via Wikimedia Commons.

InfluxDB is a time-series database, built from the ground up for exactly the shape of data Home Assistant produces — timestamped numeric and categorical values, queried in aggregates over ranges, not as individual rows. Pointing Home Assistant at it doesn’t replace the recorder; it runs alongside it, receiving a live stream of every state change and storing it in a format that stays fast to query no matter how many years of history you keep.

Wiring it up

I run InfluxDB 2.x, which is the current line and the one Home Assistant’s integration targets by default. A minimal compose service:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
services:
  influxdb:
    image: influxdb:2.7
    ports:
      - "8086:8086"
    volumes:
      - influxdb-data:/var/lib/influxdb2
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=admin
      - DOCKER_INFLUXDB_INIT_PASSWORD=changeme
      - DOCKER_INFLUXDB_INIT_ORG=home
      - DOCKER_INFLUXDB_INIT_BUCKET=homeassistant

volumes:
  influxdb-data:

After the first boot, generate an API token from the InfluxDB UI (localhost:8086) scoped to write access on the homeassistant bucket — don’t reuse the admin token for the Home Assistant integration, since it should only ever be able to write, not administer the database. Then point the influxdb integration at it in configuration.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
influxdb:
  api_version: 2
  host: influxdb.example.com
  port: 8086
  token: !secret influxdb_token
  organization: home
  bucket: homeassistant
  exclude:
    domains:
      - automation
      - updater
  include:
    domains:
      - sensor
      - binary_sensor
      - climate

That include/exclude pair matters more than it looks like a minor detail — without it, every entity Home Assistant knows about gets a point written on every state change, including chatty, low-value domains like automation (which changes state every time any automation fires) and updater. On a system with a few hundred entities that’s a meaningful and mostly useless write volume. Scoping to the domains you actually want long-term history for — sensors, binary sensors, climate — keeps the bucket both smaller and, more importantly, actually queryable without wading through noise.

Grafana, and the query that started this whole project

Grafana connects to InfluxDB as a standard data source (Configuration → Data Sources → InfluxDB, Flux query language, same URL/org/token as above), and from there it’s building dashboards against Home Assistant’s own history exactly like you would against any other time-series source. The query that answered my original question — this January against last January — looks like this in Flux:

1
2
3
4
5
6
from(bucket: "homeassistant")
  |> range(start: -400d)
  |> filter(fn: (r) => r._measurement == "°C")
  |> filter(fn: (r) => r.entity_id == "living_room_temp")
  |> filter(fn: (r) => r._field == "value")
  |> aggregateWindow(every: 1d, fn: mean)

Rendered as a Grafana time-series panel with the current and prior year overlaid, that answered the actual question in about ten seconds of looking at a graph — average living-room temperature had gone up roughly a degree and a half at the same outdoor conditions, for noticeably less heating runtime, which was exactly the insulation payoff I was trying to confirm. That’s the entire value proposition of this setup in one example: a question the built-in ten-day history literally cannot answer becomes a straightforward query once the data’s somewhere designed to hold it.

Building a dashboard worth looking at daily

Beyond the one-off investigation query, the dashboard I actually keep open day to day is simpler: current readings as stat panels, a 24-hour graph per room, and a power consumption panel pulling from a smart plug’s sensor.*_power entities. The pattern that’s worth stealing is grouping panels by room rather than by entity type — a single row per room with temperature, humidity, and any relevant binary sensors together tells a more useful story at a glance than a wall of identically-styled graphs sorted alphabetically by entity ID.

For anything cardinality-sensitive — a household with dozens of sensors reporting every few seconds — it’s worth knowing that InfluxDB isn’t the only option here. If you’re already running Prometheus and Grafana for other homelab monitoring, Home Assistant can also export directly to a Prometheus-scrapeable endpoint, which avoids running a second time-series database purely for this. I chose InfluxDB specifically because the official integration is more mature and the include/exclude domain filtering is more granular than the Prometheus exporter offers, but either is a legitimate answer depending on what you’re already running.

Two dashboard habits paid off more than I expected. First, a single “annotations” panel marking events like “added loft insulation” or “replaced thermostat” directly on the time axis — Grafana supports this natively, and without it, a graph showing a step-change in efficiency six months from now is a mystery rather than a confirmation. Second, keeping raw entity dashboards and investigation dashboards separate: the daily-use dashboard stays simple and fast, while a second, messier dashboard exists purely for one-off comparisons like the January-over-January query above, rebuilt and discarded as needed rather than cluttering the one you actually look at every morning.

How this differs from Home Assistant’s own long-term statistics

Home Assistant’s recorder has grown a feature that sounds like it solves this already: since the statistics engine landed, sensors with a recognised device_class and state_class get an hourly mean/min/max written to a separate statistics table that survives the normal purge, indefinitely, without any external database. It’s worth knowing exactly where that stops being enough, because it isn’t the same capability as the setup above. The built-in statistics table only covers entities Home Assistant recognises as statistics-eligible — a custom template sensor without a proper state_class set is invisible to it, silently, with no warning that it’s being excluded. It stores hourly aggregates only, with no path back to the raw per-change data once the short-term history purges, so a question that needs finer resolution than an hourly mean is unanswerable after the purge window regardless of how long the statistics table itself has been running. And it has no query language beyond what the Home Assistant UI’s own history and statistics graph cards expose — no arbitrary date-range comparison, no cross-entity correlation, nothing like the January-over-January Flux query above. It’s a genuinely useful improvement over the raw ten-day purge for simple long-run graphs, and if all you want is “show me this sensor’s monthly trend for the past two years” inside Home Assistant itself, it may be all you need. InfluxDB and Grafana earn their keep once the question gets more specific than that.

Retention, and not paying for storage you don’t need

Unlike the recorder’s blunt day-count purge, InfluxDB lets you set retention per bucket, and — more usefully — combine that with downsampling, so old data shrinks in resolution rather than disappearing outright. A task that runs nightly, aggregating anything older than 90 days down to hourly means and writing it into a second, longer-retention bucket, keeps raw high-resolution data for recent trends while keeping years of coarser history at a fraction of the storage cost:

1
2
3
4
5
6
option task = {name: "downsample-old-data", every: 1d}

from(bucket: "homeassistant")
  |> range(start: -91d, stop: -90d)
  |> aggregateWindow(every: 1h, fn: mean)
  |> to(bucket: "homeassistant-longterm")

That’s the difference between “years of history” being an actual practical claim and a bucket that quietly grows until it fills the disk — a raw sensor writing every 30 seconds accumulates fast, and nobody actually needs second-by-second resolution on data from two years ago.

Home Assistant automations are good at threshold alerts — “notify me if the freezer goes above -10°C” is a one-line automation. What they’re not built for is alerting on a trend, because the automation engine only ever evaluates current state, with no memory of where a value has been. Grafana alerting, by contrast, is built entirely around querying a range and evaluating a condition against it, which makes trend-based alerts straightforward in a way they simply aren’t in Home Assistant natively.

The alert I actually run watches for a slow water heater efficiency decline — the 7-day rolling average of energy-per-degree drifting upward over weeks, a symptom of scale buildup long before it ever becomes a symptom of a cold shower:

1
2
3
4
5
from(bucket: "homeassistant")
  |> range(start: -14d)
  |> filter(fn: (r) => r.entity_id == "water_heater_energy_efficiency")
  |> aggregateWindow(every: 1d, fn: mean)
  |> movingAverage(n: 7)

Grafana’s alert rule fires when that moving average crosses a threshold I set after watching a full season of normal variation — the kind of baseline you can only establish once you actually have months of history to look at, which loops back to the entire reason this setup exists.

Backing up the time-series data

It’s easy to treat a metrics database as disposable — “it’s just graphs, who cares if I lose it” — right up until you’ve built two years of comparisons on top of it and a disk failure erases the lot. InfluxDB 2.x backups are a single command and worth scripting into whatever backup routine already covers the rest of the homelab:

1
2
3
influx backup /backups/influxdb/$(date +%F) \
  --org home \
  --token "$INFLUX_ADMIN_TOKEN"

I run that nightly alongside the rest of my 3-2-1 backup routine, pushed offsite the same way everything else is — the whole point of this project was building a historical record that the ten-day recorder purge can’t provide, and an unbacked-up database undermines that just as thoroughly as never having set it up.

Troubleshooting

The most common failure is data simply not showing up in Grafana despite the integration apparently running — check Home Assistant’s own log for influxdb errors first; a wrong org or bucket name fails silently from the dashboard’s perspective (empty graph, no error visible in Grafana) but loudly in the Home Assistant log. Second most common: field names not matching what a Flux query expects. Home Assistant writes the measurement name as the unit by default ("°C", "%"), which surprises people expecting the entity name there — entity_id is a tag, not the measurement, and getting that backwards is the single most common reason a first Flux query returns nothing.

A third, quieter failure worth knowing about: timezone mismatches between the InfluxDB container and Home Assistant. InfluxDB stores everything in UTC internally, which is correct, but a Grafana panel left on browser-local time while you’re debugging via SSH from a different timezone can make data look like it’s arriving hours out of sequence when nothing is actually wrong. Setting the dashboard’s timezone explicitly rather than leaving it on “browser default” removes an entire category of “is my data broken” false alarms.

A fourth failure that only shows up months in: aggregate queries quietly skewed by unknown and unavailable states. Every sensor has brief gaps — a Zigbee device missing a poll, Home Assistant restarting, a battery-powered sensor sleeping between reports — and Home Assistant writes those gaps as literal string states rather than simply omitting a point. A naive mean() over a field that occasionally contains a non-numeric string either errors outright or, depending on the client library, gets coerced into something that drags the average down without an obvious cause. The fix is filtering before aggregating rather than after noticing the numbers look wrong: |> filter(fn: (r) => r._value != "unknown" and r._value != "unavailable") ahead of any aggregateWindow call. It’s a one-line addition that’s easy to forget until a dashboard reports a plausible-looking but quietly wrong number for weeks.

Worth the second database

Running InfluxDB purely for Home Assistant history is a genuinely small operational cost — one more container, one more thing to back up — against a capability the built-in recorder structurally cannot provide. If you only ever want “what happened in the last few days,” skip this entirely and leave the defaults alone. If you want to answer questions that span months or years — did the new heating actually help, is a supposedly independent sensor drifting, how much has your baseline power draw crept up — this is the tool built for exactly that, and it pairs naturally with the computed sensors you’ll build with Jinja templating, since every template sensor is just another entity as far as the InfluxDB integration is concerned.

Smarc
Written by Smarc

Founder and editor of Aside House. A lifelong tinkerer who self-hosts far more than is sensible, hardens Linux boxes for fun, and prods the latest AI tools to see what they can really do. The how-to guides here are the notes Smarc wishes had existed the first time round.

Smarc is the editor of Aside House. The homelab, the hardware and the opinions are real; the guides are drafted with AI assistance. Infrastructure details are genericised on purpose.