---
title: Auto-Zero Debug Logging
description: Guide to enabling and interpreting debug logs for the Auto-Zero Metrics feature in the AutoPi Home Assistant integration
---

# Auto-Zero Debug Logging Guide

This guide explains the debug logging that tracks Auto-Zero Metrics behavior in real time, and how to read each log tag.

## Enable Debug Logging

Add this to your `configuration.yaml`:

```yaml
logger:
  default: info
  logs:
    custom_components.autopi: debug
```

## Log Tags and What They Mean

### Initialization Phase

- **`[AUTO-ZERO INIT]`** - Auto-zero manager initialization
  - Shows when the manager starts and whether auto-zero is enabled
  - Shows how many metrics are being restored from storage

- **`[SENSOR INIT]`** - Individual sensor creation
  - Shows each sensor being created and whether it supports auto-zero

### Startup/Restoration Phase

- **`RESTORED`** - A previously zeroed metric was restored from storage
  - Shows the metric name, vehicle, and how long ago it was zeroed
  
- **`SKIPPED`** - A stored zero state was too old (>24 hours) and not restored
  - Prevents ancient zero states from persisting forever

### Runtime Evaluation Phase

- **`[SENSOR AUTO-ZERO]`** - Sensor-level auto-zero checks
  - Shows when a sensor checks if it should be zeroed
  - Special note: "STARTUP PROTECTION" means preventing stale data on HA restart

- **`[SENSOR DATA]`** - Raw sensor data
  - Shows the actual value and age of data from the API
  
- **`[AUTO-ZERO EVAL]`** - Auto-zero manager evaluation
  - Shows the age of data vs. the 15-minute threshold
  - Shows whether the metric is currently zeroed

- **`is_metric_zeroed check`** - Quick check if a metric is already zeroed
  - Used during startup to prevent showing stale data

### Action Phase

- **`[AUTO-ZERO ACTION] ZEROING`** - Metric is being zeroed
  - Shows when data crosses the 15-minute threshold
  
- **`[AUTO-ZERO ACTION] UN-ZEROING`** - Metric is being restored
  - Shows when fresh data arrives (≤15 minutes old)

- **`[AUTO-ZERO UPDATE]`** - Updates to already-zeroed metrics
  - Shows when a zeroed metric gets new (but still stale) data

### Storage Phase

- **`[AUTO-ZERO SAVE]`** - Persistence operations
  - Shows when state is saved to disk
  - Lists all metrics being saved

## Example Log Flow

### Scenario 1: Home Assistant Startup with Stale Data

```text
[AUTO-ZERO INIT] Initializing auto-zero manager
[AUTO-ZERO INIT] Auto-zero manager initialized, auto_zero_enabled=True
Processing 3 zeroed metrics from storage
RESTORED zeroed state for Engine RPM (OBD) on vehicle 123 (zeroed 0.5 hours ago)
[SENSOR INIT] Created sensor Engine RPM for vehicle 123 (field_id: obd.rpm.value, auto-zero capable: True)
[SENSOR AUTO-ZERO] Checking Engine RPM on vehicle 123: auto_zero_enabled=True
is_metric_zeroed check: Engine RPM (OBD) on vehicle 123 IS ZEROED (zeroed 30.0 minutes ago)
[SENSOR AUTO-ZERO] Engine RPM for vehicle 123 is marked as zeroed and no data available, returning 0 (STARTUP PROTECTION)
```

### Scenario 2: Data Becoming Stale

```text
[SENSOR DATA] Engine RPM for vehicle 123 has value 0 (last_seen: 2025-01-15T10:00:00, age: 16.5 min)
[AUTO-ZERO EVAL] Engine RPM (OBD) on vehicle 123: last_seen 16.5 min ago (threshold 15 min), currently zeroed: False
[AUTO-ZERO ACTION] ZEROING Engine RPM (OBD) for vehicle 123 - data is 16.5 minutes old (threshold: 15 min)
[AUTO-ZERO SAVE] Scheduling save operation with 1 zeroed metrics
[SENSOR AUTO-ZERO] RETURNING 0 for Engine RPM on vehicle 123 (auto-zero applied)
```

### Scenario 3: Fresh Data Arriving

```text
[SENSOR DATA] Engine RPM for vehicle 123 has value 850 (last_seen: 2025-01-15T10:20:00, age: 2.1 min)
[AUTO-ZERO EVAL] Engine RPM (OBD) on vehicle 123: last_seen 2.1 min ago (threshold 15 min), currently zeroed: True
[AUTO-ZERO ACTION] UN-ZEROING Engine RPM (OBD) for vehicle 123 - fresh data received (2.1 minutes old)
[SENSOR AUTO-ZERO] Engine RPM on vehicle 123 NOT zeroed, returning actual value 850
```

## Troubleshooting with Logs

### Issue: Sensor shows stale value on startup

Look for:
- Missing `[SENSOR AUTO-ZERO] ... STARTUP PROTECTION` log
- Check if `is_metric_zeroed check` shows the metric as zeroed
- Verify `RESTORED` log shows the metric was loaded from storage

### Issue: Sensor not zeroing when expected

Look for:
- `[AUTO-ZERO EVAL]` to see the actual age vs. threshold
- Check if auto_zero_enabled=True in the logs
- Verify the field_id is in the auto-zero capable list

### Issue: Sensor zeroing too quickly

Look for:
- `[SENSOR DATA]` to see the actual last_seen timestamp
- The age calculation might show the data is older than expected
- Check your AutoPi device's reporting frequency

## Performance Note

These debug logs are verbose and should only be enabled when troubleshooting. Disable debug logging for normal operation to reduce log size.