Log To Json Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require behnamhosseini/log-to-json
   

   Add the service provider to config/app.php under providers:

   BehnamHosseini\LogToJson\LogToJsonServiceProvider::class,
   

2. First Use Case Publish the config file (if needed) and ensure your Laravel logs are already configured in config/logging.php. The package automatically converts log entries to JSON format when writing to files (e.g., single, daily, or syslog channels).

   Test by forcing a log entry:

   \Log::info('Test JSON log entry');
   

   Check the log file (e.g., storage/logs/laravel.log)—entries should now appear in JSON format.

Implementation Patterns

Workflows

1. Log Channel Integration

   • Works seamlessly with Laravel’s built-in log channels (e.g., single, daily). No manual channel configuration is required.
   • For custom channels, extend the BehnamHosseini\LogToJson\Handlers\JsonHandler to integrate with third-party log handlers (e.g., Monolog).

2. Structured Logging

   • Leverage JSON for structured logs in monitoring tools (e.g., ELK, Datadog, Sentry):

     \Log::debug('User action', [
         'user_id' => 123,
         'action' => 'login',
         'metadata' => ['ip' => '192.168.1.1']
     ]);
     

     Output:

     {"level":"debug","message":"User action","context":{"user_id":123,"action":"login","metadata":{"ip":"192.168.1.1"}}}
     

3. Conditional JSON Conversion

   • Disable JSON conversion for specific log levels or contexts by overriding the shouldConvertToJson method in a custom handler.

4. Log Rotation

   • JSON logs are compatible with log rotation tools (e.g., logrotate). Ensure your rotation scripts handle JSON-formatted files correctly.

Integration Tips

• Monolog: If using Monolog directly, wrap the handler with JsonHandler:

  $handler = new \Monolog\Handler\StreamHandler(storage_path('logs/custom.log'));
  $jsonHandler = new \BehnamHosseini\LogToJson\Handlers\JsonHandler($handler);
  $logger->pushHandler($jsonHandler);
  

• API Responses: Use JSON logs to debug API errors by correlating logs with request IDs:

  \Log::error('API failure', ['request_id' => $request->header('X-Request-ID')]);
  

Gotchas and Tips

Pitfalls

1. File Permissions

   • Ensure the storage/logs directory is writable by the web server user. JSON logs may fail silently if permissions are incorrect.

2. Log Parsing Tools

   • Some log analysis tools (e.g., grep, tail) may not handle JSON natively. Use jq for CLI parsing:

     tail -f storage/logs/laravel.log | jq
     

3. Performance Overhead

   • JSON serialization adds minimal overhead (~1-5ms per log entry). Benchmark in high-throughput environments if critical.

4. Legacy Systems

   • Avoid mixing JSON logs with legacy systems expecting plaintext. Use separate log channels for compatibility.

Debugging

• Disabled Conversion: Verify the package is active by checking for the LogToJsonServiceProvider in config/app.php.
• Handler Issues: Temporarily disable other log handlers to isolate JSON conversion problems.
• Custom Formatting: Override the format method in JsonHandler to customize JSON structure:

  protected function format(array $record): string
  {
      return json_encode([
          'timestamp' => $record['datetime']->format('Y-m-d H:i:s'),
          'level' => $record['level_name'],
          'message' => $record['message'],
          'context' => $record['context'] ?? [],
          'extra' => $record['extra'] ?? [],
      ]);
  }
  

Extension Points

1. Custom Handlers Extend JsonHandler to add fields (e.g., user agent, request duration):

   class CustomJsonHandler extends \BehnamHosseini\LogToJson\Handlers\JsonHandler
   {
       protected function getContext(array $context): array
       {
           $context['request_duration'] = microtime(true) - LARAVEL_START;
           return $context;
       }
   }
   

2. Dynamic JSON Keys Use a closure in the config to dynamically rename keys:

   'json_keys' => [
       'message' => fn($record) => strtoupper($record['message']),
   ],
   

3. Log Anonymization Sanitize sensitive data before JSON serialization:

   \Log::info('User data', ['email' => 'user@example.com']);
   // Override in handler:
   protected function getContext(array $context): array
   {
       $context['email'] = '*****@example.com';
       return $context;
   }