Home Assistant Log Analysis

A custom Home Assistant integration that automatically analyzes error logs using Google Gemini AI and provides actionable fixes. This integration tracks issues, allows you to mark them as complete, and intelligently reopens them if they occur again.

Features

• 🤖 AI-Powered Analysis: Uses the Home Assistant Google Generative AI Conversation integration with Gemini to analyze errors
• 📊 Issue Tracking: Automatically tracks unique issues with deduplication
• ✅ Completion Tracking: Mark issues as completed and track resolution
• 🔄 Smart Reopening: Automatically reopens completed issues if they recur
• 📈 Statistics: Track error counts, warnings, and issue occurrences
• 🔍 Detailed Action Plans: Get step-by-step instructions to fix each error
• 💾 Persistent Storage: Issues are stored and survive Home Assistant restarts

Prerequisites

Before installing this integration, you must have:

1. Home Assistant (version 2024.1 or newer)
2. Google Generative AI Conversation integration configured in Home Assistant
   • Go to Settings → Devices & Services → Add Integration
   • Search for "Google Generative AI Conversation"
   • Configure with your Google API key
   • Create a conversation agent

Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Click on "Integrations"
3. Click the three dots in the top right corner
4. Select "Custom repositories"
5. Add this repository URL: https://github.com/ncecowboy/Home-Assistant-Log-Analysis
6. Select category: "Integration"
7. Click "Add"
8. Click "Install" on the Home Assistant Log Analysis card
9. Restart Home Assistant

Manual Installation

1. Copy the custom_components/ha_log_analysis folder to your Home Assistant custom_components directory
2. Restart Home Assistant

Configuration

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for "Home Assistant Log Analysis"
4. Fill in the configuration:
   • Google Generative AI Conversation Agent: Select your configured Gemini conversation agent
   • Scan Interval: How often to scan logs in seconds (default: 300 seconds / 5 minutes)

Note: This integration reads logs from the systemd journal using either the systemd-python library or the journalctl command. If systemd-python is not available, it will automatically fall back to using the journalctl command.

Usage

Automatic Log Monitoring

Once configured, the integration will:

• Automatically scan your Home Assistant logs from systemd journal at the configured interval
• Extract errors and warnings
• Use Google Gemini AI to analyze each unique error
• Generate actionable fix plans
• Track all issues with persistence

Sensor

The integration creates a sensor: sensor.home_assistant_log_analysis

State: Number of open issues

Attributes:

• issues: List of all tracked issues with details
• error_count: Number of errors found in last scan
• warning_count: Number of warnings found in last scan
• last_analysis: Timestamp of last log analysis

Services

ha_log_analysis.analyze_logs

Trigger an immediate full log analysis.

service: ha_log_analysis.analyze_logs

ha_log_analysis.mark_issue_complete

Mark a tracked issue as completed.

service: ha_log_analysis.mark_issue_complete
data:
  issue_id: "a1b2c3d4e5f6"

ha_log_analysis.get_issues

Get all tracked issues (returns data in response).

service: ha_log_analysis.get_issues

Issue Structure

Each tracked issue contains:

• issue_id: Unique identifier for the issue
• error_message: The error message from the log
• component: The Home Assistant component that generated the error
• severity: ERROR, WARNING, or CRITICAL
• action_plan: AI-generated steps to fix the issue
• traceback: Stack trace if available
• status: "open" or "completed"
• created_at: When the issue was first seen
• last_seen: When the issue was last seen
• occurrences: Number of times this issue has occurred
• reopened_count: Number of times a completed issue was reopened

Automation Examples

Get Daily Error Report

automation:
  - alias: "Daily Error Report"
    trigger:
      - platform: time
        at: "09:00:00"
    action:
      - service: ha_log_analysis.analyze_logs
      - delay: "00:00:30"
      - service: notify.mobile_app
        data:
          title: "Daily Log Analysis"
          message: >
            Open Issues: {{ states('sensor.home_assistant_log_analysis') }}
            Errors: {{ state_attr('sensor.home_assistant_log_analysis', 'error_count') }}
            Warnings: {{ state_attr('sensor.home_assistant_log_analysis', 'warning_count') }}

Alert on New Critical Issues

automation:
  - alias: "Alert on Critical Issues"
    trigger:
      - platform: state
        entity_id: sensor.home_assistant_log_analysis
    condition:
      - condition: template
        value_template: >
          {{ state_attr('sensor.home_assistant_log_analysis', 'issues') 
             | selectattr('severity', 'equalto', 'CRITICAL')
             | selectattr('status', 'equalto', 'open')
             | list | length > 0 }}
    action:
      - service: notify.persistent_notification
        data:
          title: "Critical Error Detected"
          message: "Check sensor.home_assistant_log_analysis for details"

How It Works

1. Log Scanning: The integration periodically reads your Home Assistant logs from systemd journal
2. Error Extraction: Parses logs to extract errors, warnings, and critical messages
3. Deduplication: Generates unique IDs for each error based on the message and component
4. AI Analysis: Sends errors to Google Gemini AI via the HA conversation integration
5. Issue Tracking: Stores issues with their AI-generated action plans
6. Smart Updates:
   • New errors create new issues
   • Recurring errors increment occurrence counter
   • Completed issues that recur are automatically reopened

Troubleshooting

Integration won't load

• Ensure you have the Google Generative AI Conversation integration installed and configured
• Check Home Assistant logs for errors
• The integration will work with or without systemd journal access

No conversation agents available

• Make sure you've set up the Google Generative AI Conversation integration
• Go to Settings → Voice Assistants and verify your Gemini agent is configured

Issues not being created

• Verify errors exist in your logs (check with journalctl -u home-assistant@homeassistant.service -f on the host system)
• Check that the Gemini conversation agent is responding
• Look for errors in the Home Assistant logs related to ha_log_analysis

systemd-python installation errors

• The systemd-python library is now optional
• If systemd-python fails to install, the integration will automatically fall back to using the journalctl command
• The journalctl command must be available on your system for log reading to work
• You can view logs manually using journalctl -u home-assistant@homeassistant.service on the host system

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please visit the GitHub repository.