ha-recorder

Home Assistant Recorder Integration

Guide for integrations that work with historical data, statistics, and the recorder.

When to Use Recorder Features

• Statistics: Energy monitoring, long-term trends
• History exclusion: High-frequency sensors, diagnostic entities
• Custom statistics: External data sources
• History queries: Historical analysis features

Excluding from Recorder

Exclude noisy entities from history to reduce database size:

# In your entity class
class MyDiagnosticSensor(SensorEntity):
    """Sensor that shouldn't be recorded."""

    # Disabling an entity keeps it out of the recorder; hiding only removes it from the
    # UI (it is still recorded). For true recorder exclusion, use the recorder config below.
    _attr_entity_registry_enabled_default = False  # Disabled (and not recorded) by default
    _attr_entity_registry_visible_default = False  # Hidden from the UI by default
    _attr_should_poll = True

Or use recorder configuration in the user's config:

# configuration.yaml (user config, not your integration)
recorder:
  exclude:
    entity_globs:
      - sensor.my_integration_debug_*
    domains:
      # `domains` takes entity domains (sensor, switch, ...), not the integration name.
      - sensor

Long-Term Statistics

For sensors that should appear in energy dashboard or statistics graphs:

from homeassistant.components.sensor import (
    SensorDeviceClass,
    SensorEntity,
    SensorStateClass,
)

class MyEnergySensor(SensorEntity):
    """Energy sensor with long-term statistics."""

    _attr_device_class = SensorDeviceClass.ENERGY
    _attr_state_class = SensorStateClass.TOTAL_INCREASING
    _attr_native_unit_of_measurement = "kWh"

    # These attributes enable long-term statistics:
    # - device_class: ENERGY, GAS, WATER, etc.
    # - state_class: MEASUREMENT, TOTAL, TOTAL_INCREASING
    # - unit_of_measurement: Standard units

State Classes

State Class	Use Case	Example
MEASUREMENT	Instantaneous value	Temperature
TOTAL	Resettable counter	Trip odometer
TOTAL_INCREASING	Monotonic counter	Energy meter