Log Viewer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require arcanedev/log-viewer
   

   Publish the config (optional, but recommended for customization):

   php artisan vendor:publish --provider="ARCANE\LogViewer\LogViewerServiceProvider" --tag="config"
   

2. First Use Case Access the log viewer at /log-viewer (default route). No additional configuration is required for basic usage.

3. Where to Look First

   • Config File: config/log-viewer.php (customize paths, middleware, or log levels).
   • Documentation: Start with _docs/1.Installation-and-Setup.md for setup specifics.
   • API Endpoint: /api/log-viewer for programmatic access (e.g., from frontend apps or scripts).

Implementation Patterns

Core Workflows

1. Viewing Logs

   • Default UI: Navigate to /log-viewer for an interactive log viewer with pagination, filtering (by date/level), and search.
   • API Access: Fetch logs via /api/log-viewer with query params:

     curl -X GET "/api/log-viewer?level=error&date=2024-03-18&limit=50"
     

     Response: JSON array of log entries with metadata (level, date, message).

2. Filtering and Search

   • UI Filters: Use the dropdowns in the web UI to filter by:
     • Date range (calendar picker).
     • Log level (e.g., debug, error).
     • Keyword search (live search box).
   • API Filters: Pass query params to the API endpoint (e.g., ?search=error&level=critical).

3. Log Management

   • Deletion: Delete logs via the UI (checkbox selection + "Delete" button) or API:

     curl -X DELETE "/api/log-viewer?ids[]=123&ids[]=456"
     

   • Download: Export logs as a .txt or .json file via the UI download button or API:

     curl -X GET "/api/log-viewer/export?format=json"
     

4. Custom Log Paths

   • Override default log paths in config/log-viewer.php:

     'paths' => [
         storage_path('logs/custom'),
         database_path('logs'),
     ],
     

   • Useful for multi-environment setups (e.g., separating local and production logs).

5. Integration with Existing Systems

   • Frontend Apps: Use the API to fetch logs dynamically (e.g., React/Vue dashboard).
   • Monitoring Tools: Poll the API for critical logs (e.g., error level) and trigger alerts.
   • CI/CD Pipelines: Download logs post-deployment for debugging:

     curl -X GET "/api/log-viewer/export?format=json" --output deployment-logs.json
     

6. Middleware and Access Control

   • Restrict access by adding middleware to the web middleware group in app/Http/Kernel.php:

     'log-viewer' => [
         \App\Http\Middleware\CheckAdmin::class,
     ],
     

   • Or override the default middleware in config/log-viewer.php:

     'middleware' => ['auth', 'verified'],
     

Gotchas and Tips

Pitfalls and Debugging

1. Permission Issues

   • Symptom: Log files not loading or API returning 403 errors.
   • Fix: Ensure the Laravel storage directory and log files have proper permissions:

     chmod -R 775 storage/
     chown -R www-data:www-data storage/  # Adjust user/group as needed
     

2. Large Log Files

   • Symptom: Slow performance or timeouts when viewing large log files (e.g., >10MB).
   • Solutions:
     • Increase PHP memory limit in php.ini:

       memory_limit = 256M
       

     • Use the chunk parameter in the API to paginate results:

       curl "/api/log-viewer?chunk=1000"
       

     • Configure config/log-viewer.php to limit the number of logs loaded at once:

       'per_page' => 1000,
       

3. Custom Log Levels Not Displaying

   • Symptom: Custom log levels (e.g., alert) appear as unknown in the UI.
   • Fix: Define custom levels in config/log-viewer.php:

     'levels' => [
         'debug' => ['name' => 'Debug', 'icon' => 'bug'],
         'alert' => ['name' => 'Alert', 'icon' => 'exclamation-triangle', 'color' => 'red'],
     ],
     

4. Route Conflicts

   • Symptom: /log-viewer route not found or conflicts with existing routes.
   • Fix: Override the route in routes/web.php:

     ARCANE\LogViewer\LogViewerServiceProvider::routes(['prefix' => 'admin']);
     

5. API Rate Limiting

   • Symptom: API requests failing with 429 Too Many Requests.
   • Fix: Adjust rate limits in config/log-viewer.php or implement caching for frequent API calls.

Tips and Tricks

1. Localization

   • Customize log level names and labels by publishing the language files:

     php artisan vendor:publish --provider="ARCANE\LogViewer\LogViewerServiceProvider" --tag="lang"
     

   • Override translations in resources/lang/en/log-viewer.php.

2. Log Level Icons

   • Change default Font Awesome icons by modifying config/log-viewer.php:

     'levels' => [
         'error' => ['icon' => 'fire-alt'], // Replace 'times-circle'
     ],
     

3. Excluding Sensitive Logs

   • Filter out sensitive logs (e.g., containing passwords) by extending the LogViewer class:

     use ARCANE\LogViewer\Facades\LogViewer;
     
     LogViewer::filter(function ($log) {
         return !preg_match('/password|secret/i', $log->message);
     });
     

4. Programmatic Log Access

   • Use the facade to fetch logs in code:

     use ARCANE\LogViewer\Facades\LogViewer;
     
     $logs = LogViewer::getLogs(['level' => 'error', 'limit' => 10]);
     

5. Custom Storage Adapters

   • Extend the package to support non-file storage (e.g., database logs) by implementing the LogViewer\Contracts\LogStorage interface.

6. Dark Mode Support

   • Override the default CSS in resources/css/log-viewer.css to match your app’s theme:

     .log-viewer {
         --bg-color: #1a1a1a;
         --text-color: #e0e0e0;
     }
     

7. Log Retention Policy

   • Automate log cleanup by scheduling a command (e.g., php artisan log:clean) and integrating it with LogViewer’s API to delete old logs:

     curl -X DELETE "/api/log-viewer?older_than=30"  # Delete logs older than 30 days