Home Lab Projects

Home Assistant, InfluxDB and Grafana: Long-Term Sensor Dashboards

Send Home Assistant sensor data to InfluxDB and chart it in Grafana, with tips on choosing a version, filtering entities and keeping tokens safe.

On this page
  1. What Home Assistant already keeps
  2. Choose an InfluxDB version
  3. Install InfluxDB and Grafana
  4. Connect Home Assistant to InfluxDB
  5. Confirm that data is arriving
  6. Connect Grafana
  7. Starter queries
  8. Keep the database manageable
  9. Show Grafana on your dashboard
  10. Troubleshooting
  11. Common mistakes

Home Assistant’s recorder keeps detailed state history for 10 days by default, and long-term statistics last longer. If you want raw sensor history for longer, or charts that Home Assistant’s built-in graphs can’t show, you can send sensor data to InfluxDB and chart it in Grafana. This guide covers the setup, the filters that keep the database manageable and a few starter queries.

What Home Assistant already keeps

  • Recorder history. The recorder stores full state history for 10 days by default. You can change this with purge_keep_days in the recorder settings.
  • Long-term statistics. Hourly means, minimums, maximums or sums are kept for entities that have a state class. They persist beyond the 10-day window.
  • InfluxDB is not a replacement. It only receives data from the moment you set it up, and it doesn’t import earlier recorder history. Home Assistant’s history and energy views still use the recorder.

Choose an InfluxDB version

Version What Home Assistant needs Query language
InfluxDB 1.x Database, and a username and password if authentication is on InfluxQL
InfluxDB 2.x Organization, bucket and a token with write access Flux, or InfluxQL through DBRP mapping
InfluxDB 3 Depends on the integration’s current support SQL or InfluxQL

Check the Home Assistant InfluxDB documentation for the versions it supports today. InfluxDB 3 offers v1 and v2-compatible write APIs, but compatibility varies. Choose a version the documentation supports, and pick the query language you’re willing to learn.

Install InfluxDB and Grafana

Community add-ons exist for InfluxDB and Grafana on Home Assistant OS. You can also run both as containers on another machine. The default ports are 8086 for InfluxDB and 3000 for Grafana.

Put the database on an SSD rather than an SD card. A database writes continuously, and that wears out SD cards faster.

Connect Home Assistant to InfluxDB

Go to Settings > Devices & services, add the InfluxDB integration and enter the connection details for your version. Keep SSL verification on. If your server uses a self-signed certificate, provide its CA certificate rather than turning verification off.

Filters are set in configuration.yaml, so you control what gets written. Restart Home Assistant after you change them.

influxdb:
  include:
    domains:
      - sensor
      - binary_sensor
      - climate
  exclude:
    entities:
      - sensor.noisy_example

Filter aggressively. Writing every entity makes the database larger and fills it with noise from sensors that change often.

By default, the measurement name is the unit of measurement, such as °C, W or %. The entity ID without its domain becomes the entity_id tag, and the state is stored in the value field. The measurement_attr option changes how measurements are named, if the default doesn’t suit your queries.

Confirm that data is arriving

Check InfluxDB before you build any dashboards. Pick one sensor that isn’t critical, then query for it. For a 1.x database, this InfluxQL query returns the last hour of readings from sensors that report in °C:

SELECT * FROM "°C" WHERE time > now() - 1h

If nothing shows up, check the include and exclude filters, the token or user permissions, and the database or bucket name. The Home Assistant log also shows write errors.

Connect Grafana

In Grafana, go to Connections, select Add new connection and choose InfluxDB. Then add the data source. Enter the URL, such as http://<influx-host>:8086, and choose the product and query language that match your database. Fill in the fields for that language:

  • InfluxQL: database, user and password.
  • Flux: organization, default bucket and a token with read access.
  • SQL: database and token.

Click Save & test before you build any panels.

Use separate, read-only credentials for Grafana. Home Assistant needs write access, and Grafana only needs to read.

Starter queries

This InfluxQL panel query shows the mean value of one sensor over time:

SELECT mean("value") FROM "°C"
WHERE "entity_id" = 'living_room_temperature' AND $timeFilter
GROUP BY time($__interval)

The same idea in Flux:

from(bucket: v.defaultBucket)
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["_measurement"] == "°C")
  |> filter(fn: (r) => r["entity_id"] == "living_room_temperature")
  |> filter(fn: (r) => r["_field"] == "value")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)

Replace living_room_temperature with your sensor’s entity ID, without the domain. Use GROUP BY time or aggregateWindow on long time ranges. Without aggregation, a query can return a very large number of points, and the panel becomes slow.

Keep the database manageable

Retention policies and downsampling let you keep detailed data for a short period and summaries for longer. For example, you might keep raw data for 30 days and five-minute means after that. InfluxDB 1.x does this with retention policies and continuous queries. InfluxDB 2.x uses tasks.

Show Grafana on your dashboard

To place a Grafana panel in Home Assistant, use a webpage or iframe card. Grafana must allow embedding, which is set with allow_embedding = true in its configuration. Some setups also need anonymous access. That exposes the dashboard to anyone who can reach the page, so use a Grafana login where you can, and keep embedded dashboards on a private network.

Troubleshooting

  • No points in InfluxDB. Check the include and exclude filters, the token or user’s write permission, and the database name.
  • An empty panel. Check the time range, the measurement name and the entity_id value.
  • Flux queries fail on InfluxDB 3. Flux isn’t supported there, so use InfluxQL or SQL.
  • Slow panels on long ranges. Add aggregation, and check the timeout in the data source settings.

Common mistakes

  • Thinking Home Assistant forgets everything after 10 days. Long-term statistics persist.
  • Thinking InfluxDB replaces the recorder. It doesn’t. History and energy views still use the recorder.
  • Logging every entity. Filter to the sensors you chart.
  • Running the database on an SD card. Use an SSD.

The complete guide to home lab projects

Self-Hosted Apps That Integrate With Home Assistant: Immich, Donetick and TeslaMate
Read the guide

Keep exploring

Guides from other topics

All topics →