Log Laravel Package

Getting Started

1. Install via Composer: composer require amphp/log.
2. Create a logger with a handler — e.g., for console output:

   use Amp\ByteStream\OutputStream;
   use Amp\Log\ConsoleFormatter;
   use Amp\Log\StreamHandler;
   use Amp\Logging\Logger;
   
   $output = new OutputStream(STDOUT);
   $handler = new StreamHandler($output, new ConsoleFormatter());
   $logger = new Logger('app', [$handler]);
   

3. Log from coroutines — the logger is fully async-safe:

   $logger->info('Processing request', ['userId' => $userId, 'ip' => $ip]);
   

4. First use case: Logging in an aerys or custom AMPHP HTTP server to avoid blocking responses during I/O-bound operations.

Implementation Patterns

• Aggregate handlers: Use MultiHandler to route logs to multiple targets (e.g., stdout + file + HTTP sink):

  $handler = new MultiHandler([
      new StreamHandler($output, new ConsoleFormatter()),
      new StreamHandler($fileStream, new JsonFormatter()),
  ]);
  

• Context composition: Augment log context with request-scoped data via middleware or coroutine-local context (e.g., request ID, tenant ID) using ContextLogger:

  $logger = new ContextLogger($baseLogger, ['requestId' => $requestId]);
  $logger->info('Handling request'); // auto-includes requestId
  

• Async batch logging: Defer logging from hot paths via AsyncHandler (from amphp/log v2+), which batches and flushes off-loop:

  $handler = new AsyncHandler(new StreamHandler($stream));
  $logger = new Logger('app', [$handler]);
  

• Integration: Wire with AMPHP components like Amp\Http\Server via middleware that injects request context, or Amp\Artax for client request logging.

Gotchas and Tips

• Avoid echo/var_dump in async code — always use the logger instead; it avoids I/O contention and context loss.
• Thread safety: The logger is coroutine-safe but not thread-safe — never share logger instances across Amp::getLoop() threads (rare, but relevant for custom runners).
• Formatter quirks: JsonFormatter does not escape context values by default — wrap with Json::encode() or use JsonHandler if available in your version to prevent malformed logs.
• Memory leaks: If using AsyncHandler, always await $handler->close() in shutdown to flush pending logs — otherwise last logs vanish.
• Custom handlers: Extend Handler and implement handle(LogRecord $record): void. Keep it fast — handlers run in the coroutine context; offload heavy I/O (e.g., network) to AsyncHandler.
• Version note: v1 uses Amp\Logging; v2 (if used) uses Amp\Log namespace — ensure consistency across your stack.