178 lines
4.2 KiB
Markdown
178 lines
4.2 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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](https://flareapp.io)
|
|
2. Create a new project
|
|
3. Copy your API key
|
|
|
|
### 3. Configure Environment
|
|
|
|
**Development (.env):**
|
|
```env
|
|
FLARE_KEY=your_flare_key_here
|
|
IGNITION_THEME=auto
|
|
IGNITION_EDITOR=vscode
|
|
```
|
|
|
|
**Production (.env):**
|
|
```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:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
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`
|