Logger Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require fluent/logger:^1.0.0
   

   Add to composer.json under require:

   "fluent/logger": "^1.0.0"
   

2. Basic Usage:

   use Fluent\Logger\FluentLogger;
   
   $logger = new FluentLogger('localhost', 24224); // Host, Port
   $logger->post('app.log', ['message' => 'Test log entry']);
   

3. First Use Case: Replace error_log() or Monolog in a Laravel app with Fluentd integration:

   $logger = new FluentLogger(config('fluent.host'), config('fluent.port'));
   $logger->post('laravel.errors', ['exception' => $e->getMessage()]);
   

Implementation Patterns

Core Workflows

1. Structured Logging:

   $logger->post('user.activity', [
       'user_id' => 123,
       'action' => 'login',
       'ip' => $_SERVER['REMOTE_ADDR'],
       'timestamp' => now()->toIso8601String()
   ]);
   

2. Error Handling Integration:

   // Register error handler (v1.0.1+)
   $logger->registerErrorHandler();
   // Unregister when needed
   $logger->unregisterErrorHandler();
   

3. Laravel Service Provider:

   // config/fluent.php
   return [
       'host' => env('FLUENT_HOST', 'localhost'),
       'port' => env('FLUENT_PORT', 24224),
       'tag_prefix' => 'laravel.'
   ];
   
   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton('fluent.logger', function () {
           return new FluentLogger(
               config('fluent.host'),
               config('fluent.port')
           );
       });
   }
   

4. Tag Prefixes: Use a consistent prefix (e.g., laravel.) for all logs to group them in Fluentd:

   $logger->post('laravel.requests', ['path' => $request->path()]);
   

5. Async Logging: Offload logging to a background process (recommended per README):

   PHP App → Local Fluentd Proxy → Central Fluentd Aggregator
   

Gotchas and Tips

Pitfalls

1. No Buffering:

   • Logs are sent immediately; no retry mechanism for failed connections.
   • Workaround: Use a local Fluentd proxy as a buffer (as recommended in README).

2. Deprecated Classes:

   • Only FluentLogger remains in v1.x. Other loggers (e.g., FluentHandler) are removed.
   • Tip: Use Monolog for alternative handlers if needed.

3. PHP Threading Limitation:

   • Blocking calls may stall PHP workers. Avoid logging in tight loops or critical paths.

4. Fluentd Version:

   • Requires fluentd v0.9.20+. Older versions may fail silently.

5. Error Handler Quirks:

   • registerErrorHandler() captures all errors (including notices). Use sparingly in production.

Debugging

1. Connection Issues:

   • Test Fluentd connectivity with telnet localhost 24224.
   • Check Fluentd logs for dropped packets:

     <match **>
       @type stdout
     </match>
     

2. Log Format:

   • Fluentd expects JSON payloads. Validate with:

     $logger->post('test', json_decode('{"key":"value"}', true));
     

3. Performance:

   • Measure latency with microtime():

     $start = microtime(true);
     $logger->post('test', ['data' => 'x']);
     error_log(microtime(true) - $start); // Should be < 100ms
     

Extension Points

1. Custom Transport: Override FluentLogger::send() to add retries or compression:

   class CustomFluentLogger extends FluentLogger {
       protected function send($data) {
           // Add retry logic here
           parent::send($data);
       }
   }
   

2. Log Level Filtering: Extend to support levels (e.g., debug, error):

   $logger->post('debug.app', ['message' => 'Debug info'], 'debug');
   

3. Laravel Log Channel: Create a custom channel (Laravel 5.5+):

   // app/Providers/AppServiceProvider.php
   Log::extend('fluent', function ($app) {
       return new class {
           protected $logger;
           public function __construct() {
               $this->logger = new FluentLogger(
                   config('fluent.host'),
                   config('fluent.port')
               );
           }
           public function log($level, $message, array $context = []) {
               $this->logger->post('laravel.log', $context);
           }
       };
   });
   

4. Tag Generation: Dynamically generate tags based on context:

   $logger->post("app.{$request->path()}", ['data' => $payload]);
   

Configuration Tips

1. Environment-Specific Hosts:

   $host = env('FLUENT_HOST', env('APP_ENV') === 'local' ? 'localhost' : 'fluent.prod');
   

2. Fluentd Proxy Setup: Use td-agent (Fluentd for Debian/Ubuntu) with:

   # /etc/td-agent/td-agent.conf
   <source>
     @type forward
     port 24224
     bind 0.0.0.0
   </source>
   <match **>
     @type forward
     <server>
       host fluent.prod
       port 24224
     </server>
   </match>
   

3. Log Retention: Configure Fluentd to manage disk space:

   <match **>
     @type file
     path /var/log/fluent/app.log
     <storage>
       @type local
       path /var/log/fluent
       timekey_wait 10s
       timekey_use_utc true
       timekey_format %Y%m%d
     </storage>
   </match>