Logentries Monolog Handler Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (ensure compatibility with PHP/Monolog versions):

   composer require logentries/logentries-monolog-handler
   

2. Basic Configuration Update config/logging.php to use the new ingestion endpoint (data.logentries.com):

   'logentries' => [
       'driver' => 'monolog',
       'handler' => Logentries\Handler::class,
       'url' => env('LOGENTRIES_URL', 'https://data.logentries.com/logs/your-token/'), // Updated endpoint
       'level' => env('LOG_LEVEL', \Monolog\Logger::DEBUG),
       'tags' => ['laravel', 'app'],
   ],
   

3. First Use Case Log a test entry in a controller or service:

   use Illuminate\Support\Facades\Log;
   
   Log::debug('Testing Logentries integration', ['context' => 'test']);
   

Where to Look First

• Handler Class: Logentries/Handler (verify updated endpoint logic).
• Monolog Docs: Monolog Handlers for handler behavior.
• Environment Variables: Check .env for LOGENTRIES_URL (now pointing to data.logentries.com).

Implementation Patterns

Workflows

1. Conditional Logging Use the level config to filter logs (e.g., INFO for production):

   'level' => env('APP_ENV') === 'production' ? \Monolog\Logger::INFO : \Monolog\Logger::DEBUG,
   

2. Contextual Tags Dynamically add tags via tags config or runtime:

   Log::withContext(['user_id' => auth()->id()])->info('User action');
   

3. Error Handling Catch exceptions and log them:

   try {
       // Risky operation
   } catch (\Exception $e) {
       Log::error('Operation failed', ['exception' => $e]);
   }
   

Integration Tips

• Laravel’s app/Exceptions/Handler.php Extend the report() method to log unhandled exceptions:

  Log::emergency('Unhandled exception', ['exception' => $exception]);
  

• Queue Failed Jobs Log job failures in app/Jobs/Job.php:

  protected function failed(\Throwable $exception) {
      Log::error('Job failed', ['job' => $this, 'exception' => $exception]);
  }
  

• Custom Formatter Override the default JSON formatter for structured logs:

  'formatter' => new \Monolog\Formatter\LineFormatter(
      "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n"
  ),
  

Gotchas and Tips

Pitfalls

1. Archived Package

   • No updates since 2023 (v2.1), but critical fixes (timeout/endpoint) are included.
   • Test thoroughly with your PHP version (e.g., 8.0+ may need adjustments).

2. URL Format

   • Critical: Update LOGENTRIES_URL to use data.logentries.com (not api.logentries.com).
   • Incorrect URL will fail silently. Verify with Logentries’ API docs.

3. Connection Timeouts

   • v2.1 fixes timeout issues, but high-latency networks may still require retries.
   • Monitor logs for ConnectionException or TimeoutException.

4. Context Size

   • Large context arrays may exceed Logentries’ payload limits (~1MB). Trim or serialize data:

   Log::debug('Large data', ['truncated' => array_slice($data, 0, 100)]);
   

Debugging

• Check Handler Output Temporarily add a stream handler to debug locally:

  'handlers' => [
      'stream' => [
          'driver' => 'stream',
          'path' => storage_path('logs/laravel.log'),
      ],
      'logentries' => [...],
  ],
  

• Validate Webhook Use Logentries’ test URL to verify logs arrive (updated endpoint).

Extension Points

1. Custom Transport Extend Logentries\Handler to support HTTPS proxies or retries (now with timeout fixes):

   class CustomLogentriesHandler extends \Logentries\Handler {
       protected function send($record) {
           // Add retry logic for timeouts
           parent::send($record);
       }
   }
   

2. Dynamic Token Rotation Rotate LOGENTRIES_URL via Laravel’s env() or a config listener:

   Config::listen('logging.logentries.url', function ($value) {
       // Update token periodically
   });
   

3. Log Sampling Implement a wrapper to sample logs (e.g., 1% of DEBUG logs):

   if (rand(0, 99) < 1) {
       Log::debug('Sampled log');
   }