Skip to content

attention-severity-logic.md

Latest commit

 

History

History
217 lines (154 loc) · 8.71 KB

attention-severity-logic.md

File metadata and controls

217 lines (154 loc) · 8.71 KB
Raw

Attention Severity Logic

Project: SMART Sniffer Module: attention.py, sensor.py, coordinator.py Purpose: Documents how SMART Sniffer classifies drive health into actionable states and notifies the user.

Architecture

SMART Sniffer exposes two sensors per drive for health assessment:

Sensor Entity type What it tracks Indicator type
Health Binary sensor SMART official pass/fail + NVMe critical_warning Lagging
Attention Needed Enum sensor Individual early-warning attributes Leading

The Health sensor reflects the drive's own self-assessment. It is a lagging indicator — drives can report PASSED right up until catastrophic failure.

The Attention Needed sensor is SMART Sniffer's proactive evaluation. It monitors individual attributes that research shows are predictive of failure before the SMART status flips, giving time to act.

Attention Needed States

The attention sensor is an enum sensor (device_class: enum) with four possible states:

State Severity Meaning Recommended action
NO none All monitored indicators clear. No action required.
MAYBE warning Early degradation signals detected. Monitor closely. Schedule replacement.
YES critical Data integrity at risk. Back up immediately. Replace drive at first opportunity.
UNSUPPORTED none Drive returned no usable SMART data. SMART monitoring is not possible for this drive. Common with USB enclosures.

Attributes

The attention sensor carries these attributes for automations and dashboards:

# When state is YES
severity: "critical"
reasons:
  - "Reallocated Sector Count: 3 (expected 0)"
  - "Current Pending Sector Count: 1 (expected 0)"
issue_count: 2

# When state is NO
severity: "none"
reasons:
  - "No issues detected"
issue_count: 0

# When state is UNSUPPORTED
severity: "none"
reasons:
  - "Drive data unavailable"
issue_count: 0

Classification Rules

Data-Quality Gate

Before evaluating any attributes, the system checks whether the drive returned usable SMART data. A drive has usable data if any of:

  • smart_status.passed field is present (even if false)
  • ata_smart_attributes.table has at least one entry
  • nvme_smart_health_information_log has any keys

If none of these conditions are met → state is UNSUPPORTED.

This handles USB enclosures that block SMART passthrough, drives where smartctl times out, and protocols we don't yet support (SAS/SCSI).

ATA / SATA Drives

CRITICAL (state: YES) — Any non-zero value

These attributes should always read 0 on a healthy drive. Non-zero indicates the drive has encountered unrecoverable errors or remapped bad sectors.

SMART Attribute Name(s) ID What it means
Reallocated_Sector_Ct 5 Drive remapped a bad sector. ~14× higher failure rate.
Current_Pending_Sector / Current_Pending_Sector_Ct / Total_Pending_Sectors 197 Sectors currently unreadable, waiting to be remapped. Urgent.
Offline_Uncorrectable / Reported_Uncorrect / Uncorrectable_Error_Cnt / Total_Offl_Uncorrectabl 198 / 187 Sectors failed during offline scan or ECC. Data loss likely. ~7.5× higher failure rate.

WARNING (state: MAYBE) — Any non-zero value

These indicate early degradation but don't necessarily mean data has been lost yet.

SMART Attribute Name(s) ID What it means
Reallocated_Event_Count 196 Individual reallocation events. Can increment even after ID 5 stops changing.
Spin_Retry_Count 10 HDD only. Motor struggling to spin up. Early mechanical wear.
Command_Timeout 188 Drive internally timed out. Controller or interconnect issues.

WARNING (state: MAYBE) -- SSD wear threshold

SMART Attribute Name(s) Condition What it means
Wear_Leveling_Count, Media_Wearout_Indicator, SSD_Life_Left, Remaining_Lifetime_Perc, Percent_Lifetime_Remain, Perc_Rated_Life_Remain, Percent_Life_Remaining, Drive_Life_Protection_Stat, Wear_Range_Delta >= 90% used (after inversion from normalized VALUE) SSD nearing end of rated write endurance. ATA normalized VALUE is inverted to "percentage used" for consistency with NVMe. Added in v0.5.6.

Note: When both critical and warning triggers are active, the state is YES (critical wins) and all reasons are combined in the reasons list -- critical reasons first, warning reasons appended.

NVMe Drives

CRITICAL (state: YES)

Field Condition What it means
critical_warning ≠ 0 Bitmask. Any set bit = act now. Bits: spare below threshold, temp out of range, reliability degraded, read-only mode, volatile backup failed.
media_errors > 0 Cumulative unrecoverable media errors. Should always be 0.
available_spare ≤ available_spare_threshold Drive's reserve block pool at or below manufacturer threshold.

WARNING (state: MAYBE)

Field Condition What it means
available_spare < 20% (but above threshold) Early warning before hitting official threshold.
percentage_used ≥ 90% Drive at 90%+ of rated write endurance. At 100% → read-only mode.

Health Binary Sensor (No-Data Fix)

The health binary sensor now returns three possible states:

is_on value HA rendering Meaning
False "OK" SMART PASSED, all clear.
True "Problem" SMART FAILED or critical attribute triggered.
None "Unknown" No usable SMART data — can't determine health.

Previously, drives with no usable data (like the external USB drive) would show "OK" because the evaluation fell through with no failures to detect. Now they show "Unknown" — which is accurate and not misleading.

Persistent Notification Behavior

The coordinator (coordinator.py) evaluates attention after every poll and manages HA persistent notifications automatically. No user automation is required.

Transition Rules

Previous state New state Action
(first poll) any Record baseline, no notification (avoids spam on HA restart)
NO MAYBE Fire ⚠️ WARNING notification
NO YES Fire 🔴 CRITICAL notification
MAYBE YES Update notification → escalate to CRITICAL
YES MAYBE Update notification → de-escalate to WARNING
YES / MAYBE NO Dismiss notification (resolved)
any UNSUPPORTED Fire ℹ️ informational notification
UNSUPPORTED any Dismiss informational notification
Drive removed — Dismiss notification, clean up state

Notification Examples

Critical:

🔴 Drive Attention Required — Samsung SSD 870 EVO 500GB (S6PXNS0L100992M)

CRITICAL — Back up your data immediately.

• Reallocated Sector Count: 3 (expected 0) • Current Pending Sector Count: 1 (expected 0)

Warning:

⚠️ Drive Attention Required — Seagate Barracuda ST2000DM008 (ZFN4XXXX)

WARNING — Monitor closely and plan for replacement.

• Spin Retry Count: 2 (expected 0)

Unsupported:

ℹ️ SMART Monitoring Unavailable — Proxmox External 1TB USB Drive

SMART Sniffer cannot read health data from this drive. This commonly happens with USB enclosures that block SMART passthrough. Health monitoring is not available for this drive.

Notification ID

Each drive has a stable notification ID: smart_sniffer_attention_{drive_id}

Escalations/de-escalations overwrite the existing notification (same ID). Dismissing the notification = user acknowledgment. If the condition changes again, a new notification fires.

Suppressing Known Alerts

For drives with permanent issues (e.g., a drive with reallocated sectors you've chosen to keep in service), create an input_boolean helper and a suppression automation:

automation:
  - alias: "Suppress known SMART alerts"
    trigger:
      - platform: state
        entity_id: binary_sensor.your_drive_attention_needed
        to: "on"
    condition:
      - condition: state
        entity_id: input_boolean.drive_sxxx_acknowledged
        state: "on"
    action:
      - service: persistent_notification.dismiss
        data:
          notification_id: "smart_sniffer_attention_your_drive_id"

Source References