Laravel Request Logger Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require the-caretakers/laravel-request-logger
   php artisan vendor:publish --provider="TheCaretakers\RequestLogger\Providers\RequestLoggerServiceProvider" --tag="request-logger-config"
   

   • Verify config/request-logger.php exists and matches your needs.

2. Enable Middleware Add the middleware to your HTTP kernel (app/Http/Kernel.php) in the $middleware or $middlewareGroups array:

   \TheCaretakers\RequestLogger\Http\Middleware\RequestLogger::class,
   

3. First Use Case

   • Debugging API Issues: Log all incoming requests to a dedicated disk (e.g., logs/requests) for later inspection.
   • Audit Trail: Track user actions or critical endpoints (e.g., /admin/*) by default.

Where to Look First

• Configuration: config/request-logger.php – Adjust disk, log_profile, and log_writer as needed.
• Middleware: \TheCaretakers\RequestLogger\Http\Middleware\RequestLogger – Inspect how requests/responses are captured.
• Log Format: Check the default log structure (e.g., JSON) in the package’s LogWriter class.

Implementation Patterns

Core Workflows

1. Logging All Requests

   • Enable middleware globally (as above) to log every request/response pair.
   • Example log entry structure:

     {
       "timestamp": "2023-10-01T12:00:00Z",
       "method": "GET",
       "path": "/api/users",
       "ip": "192.168.1.1",
       "user_agent": "Postman/10.0",
       "status_code": 200,
       "duration_ms": 120,
       "input": { "sanitized": true },
       "response": { "sanitized": true }
     }
     

2. Conditional Logging

   • Use log_profile to filter requests (e.g., log only /api/* or requests with X-Log-Request: true header).
   • Example custom profile:

     // app/Profiles/LogAdminRequests.php
     namespace App\Profiles;
     use TheCaretakers\RequestLogger\Contracts\LogProfile;
     
     class LogAdminRequests implements LogProfile {
         public function shouldLog(\Illuminate\Http\Request $request) {
             return str_starts_with($request->path(), '/admin');
         }
     }
     

   • Update config:

     'log_profile' => \App\Profiles\LogAdminRequests::class,
     

3. Custom Log Writers

   • Extend \TheCaretakers\RequestLogger\Contracts\LogWriter to modify log format or storage.
   • Example: Log to a database instead of filesystem.

     // app/Writers/DatabaseLogWriter.php
     namespace App\Writers;
     use TheCaretakers\RequestLogger\Contracts\LogWriter;
     
     class DatabaseLogWriter implements LogWriter {
         public function write(array $logEntry) {
             \App\Models\RequestLog::create($logEntry);
         }
     }
     

   • Update config:

     'log_writer' => \App\Writers\DatabaseLogWriter::class,
     

4. Log Rotation

   • Use the built-in rotate:request-logs command to clean up old logs:

     php artisan request-logger:rotate --days=30
     

   • Schedule it in app/Console/Kernel.php:

     $schedule->command('request-logger:rotate --days=30')->daily();
     

Integration Tips

• Sanitization: The package automatically sanitizes sensitive data (e.g., passwords, tokens) from logs. Override via config('request-logger.sanitize') if needed.
• Performance: Logging adds overhead. Exclude health checks or static assets from logging via log_profile.
• Testing: Mock the logger in tests:

  $this->app->instance(
      \TheCaretakers\RequestLogger\Contracts\LogWriter::class,
      new class implements \TheCaretakers\RequestLogger\Contracts\LogWriter {
          public function write(array $logEntry) {
              // Assert or store for testing
          }
      }
  );
  

Gotchas and Tips

Pitfalls

1. Disk Permissions

   • Ensure the configured disk (e.g., logs/requests) is writable by Laravel.
   • Debug: Check storage/logs/requests permissions or S3 bucket policies if using cloud storage.

2. Log Bloat

   • Unfiltered logging can fill disk space quickly. Use log_profile to limit scope.
   • Monitor log size with:

     du -sh storage/logs/requests
     

3. Middleware Order

   • Place RequestLogger after StartSession and Authenticate to capture user context (e.g., $request->user()).
   • Place it before TrimStrings or ConvertEmptyStringsToNull to log raw input.

4. Sanitization Overrides

   • Custom log_writer may bypass sanitization. Reapply it if needed:

     public function write(array $logEntry) {
         $logEntry['input'] = $this->sanitize($logEntry['input']);
         // ...
     }
     

Debugging

1. Missing Logs

   • Verify middleware is registered in Kernel.php.
   • Check config('request-logger.enabled') (defaults to true).
   • Test with a manual log entry:

     \TheCaretakers\RequestLogger\Facades\RequestLogger::log($request, $response);
     

2. Log Format Issues

   • Inspect the raw log file (e.g., storage/logs/requests/2023-10-01.json) to debug serialization errors.
   • Extend LogWriter to add error handling:

     try {
         file_put_contents($path, json_encode($logEntry));
     } catch (\Throwable $e) {
         \Log::error("Failed to write request log", ['error' => $e->getMessage()]);
     }
     

3. Rotation Failures

   • Ensure the rotate:request-logs command has access to log files.
   • Test manually with --dry-run:

     php artisan request-logger:rotate --days=1 --dry-run
     

Extension Points

1. Custom Log Fields

   • Add metadata to logs via a custom LogWriter:

     $logEntry['custom_field'] = $this->getCustomData($request);
     

2. Real-Time Monitoring

   • Stream logs to a service like Laravel Echo or use tail -f on log files:

     tail -f storage/logs/requests/*.json
     

3. Log Export

   • Create a command to export logs to CSV/JSON for analysis:

     // app/Console/Commands/ExportRequestLogs.php
     use Illuminate\Console\Command;
     use TheCaretakers\RequestLogger\Facades\RequestLogger;
     
     class ExportRequestLogs extends Command {
         protected $signature = 'request-logger:export {--path=}';
         public function handle() {
             $logs = RequestLogger::getAllLogs();
             file_put_contents($this->option('path'), json_encode($logs));
         }
     }
     

4. Conditional Logging in Code

   • Manually log specific requests:

     if ($request->is('critical-endpoint')) {
         \TheCaretakers\RequestLogger\Facades\RequestLogger::log($request, $response);
     }