Laravel-Docker-Dev-Template/docs/error-logging.md

Error Logging Setup

This template uses Flare + Ignition by Spatie for error logging.

Overview

Environment	Tool	Purpose
Development	Ignition	Rich in-browser error pages with AI explanations
Development	Telescope (optional)	Request/query/job debugging dashboard
Production	Flare	Remote error tracking, notifications

Architecture

Development:
  Error → Ignition → Beautiful error page with:
                     - Stack trace with code context
                     - AI-powered explanations
                     - Click-to-open in VS Code
                     - Suggested solutions

Production:
  Error → Flare (remote) → Notifications (Slack/Email)
        ↓
  User sees clean 500.blade.php error page

Setup

1. Run Post-Install Script

After creating your Laravel project:

# In Docker
make setup-tools

# Or manually
cd src
bash ../scripts/post-install.sh

2. Get Flare API Key

1. Sign up at flareapp.io
2. Create a new project
3. Copy your API key

3. Configure Environment

Development (.env):

FLARE_KEY=your_flare_key_here
IGNITION_THEME=auto
IGNITION_EDITOR=vscode

Production (.env):

APP_DEBUG=false
FLARE_KEY=your_flare_key_here

Ignition Features (Development)

AI Error Explanations

Ignition can explain errors using AI. Click "AI" button on any error page.

Click-to-Open in Editor

Errors link directly to the file and line in your editor.

Supported editors (set via IGNITION_EDITOR):

• vscode - Visual Studio Code
• phpstorm - PhpStorm
• sublime - Sublime Text
• atom - Atom
• textmate - TextMate

Runnable Solutions

Ignition suggests fixes for common issues that you can apply with one click.

Share Error Context

Click "Share" to create a shareable link for debugging with teammates.

Telescope (Optional)

Telescope provides a debug dashboard at /telescope with:

• Requests - All HTTP requests with timing
• Exceptions - All caught exceptions
• Logs - Log entries
• Queries - Database queries with timing
• Jobs - Queue job processing
• Mail - Sent emails
• Notifications - All notifications
• Cache - Cache operations

Installing Telescope

The post-install script offers to install Telescope. To install manually:

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

Telescope in Production

Telescope is installed as a dev dependency. For production debugging:

1. Install without --dev
2. Configure authorization in app/Providers/TelescopeServiceProvider.php
3. Access via /telescope (requires authentication)

Custom Error Pages

The post-install script creates custom error pages:

• resources/views/errors/404.blade.php - Not Found
• resources/views/errors/500.blade.php - Server Error
• resources/views/errors/503.blade.php - Maintenance Mode

These are shown to users in production while Flare captures the full error details.

Flare Dashboard

In your Flare dashboard you can:

• View all errors with full stack traces
• See request data, session, user info
• Group errors by type
• Track error frequency over time
• Set up notifications (Slack, Email, Discord)
• Mark errors as resolved

Testing Error Logging

Test in Development

Add a test route in routes/web.php:

Route::get('/test-error', function () {
    throw new \Exception('Test error for Flare!');
});

Visit /test-error to see:

• Ignition error page (development)
• Error logged in Flare dashboard

Test in Production

php artisan down  # Enable maintenance mode
# Visit site - should see 503 page

php artisan up    # Disable maintenance mode

Troubleshooting

Errors not appearing in Flare

1. Check FLARE_KEY is set correctly
2. Verify APP_ENV=production and APP_DEBUG=false
3. Check network connectivity from server

Ignition not showing AI explanations

1. Requires OpenAI API key in Flare settings
2. Available on paid Flare plans

Telescope not loading

1. Run php artisan telescope:install
2. Run php artisan migrate
3. Clear cache: php artisan config:clear