Tactician Logger Laravel Package

Technical Evaluation

Architecture Fit

• Event-Driven & Command Bus Alignment: The package integrates seamlessly with Laravel’s command bus (e.g., via league/tactician or Laravel’s native Artisan/Bus systems). It extends Tactician’s middleware pipeline, making it ideal for CQRS, event sourcing, or workflow-heavy applications where command logging is critical for debugging, auditing, or observability.
• PSR-3 Compliance: Leverages Laravel’s built-in Monolog (PSR-3 logger), ensuring zero additional dependencies beyond Laravel’s core. No vendor lock-in; works with any PSR-3 logger (e.g., monolog/monolog, react/promise-stream).
• Non-Invasive: Adds logging as a middleware layer, preserving existing command handlers, buses, and middleware. No refactoring of core business logic required.

Integration Feasibility

• Laravel-Specific Leverage:
  • Service Container: Can be registered via Laravel’s AppServiceProvider or bind() methods, aligning with Laravel’s DI principles.
  • Logging Channels: Integrates with Laravel’s Log::channel() system, enabling route-specific logging (e.g., stack, single, daily).
  • Artisan Commands: Logs command execution for CLI-driven workflows (e.g., queue workers, migrations).
• Tactician Integration:
  • Works with Tactician’s CommandBus (if used) or Laravel’s Bus facade.
  • Supports command metadata (e.g., timestamps, user context) via Tactician’s CommandMetadata interface.

Technical Risk

Key Questions

1. Logging Granularity:
   • Should logs include command payloads, handler execution time, or stack traces for failures?
   • Example: Log UserCreatedCommand with payload but exclude PasswordResetCommand for security.
2. Log Destination:
   • Use Laravel’s default single channel, or route to external systems (e.g., ELK, Datadog) via Log::build()?
3. Performance Sensitivity:
   • For high-frequency commands (e.g., API requests), should logging be async or sampled (e.g., 1% of requests)?
4. Audit vs. Debugging:
   • Distinguish between audit logs (immutable, long-term storage) and debug logs (ephemeral, local dev).
5. Context Enrichment:
   • Add user ID, request ID, or geolocation via Tactician’s CommandMetadata or Laravel’s Log::withContext().

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Primary Use Case: Debugging command handlers, auditing business logic, or tracing workflows in Laravel-based CQRS/event-driven apps.
  • Alternatives: If not using Tactician, consider Laravel’s native Bus + Log::info() or Spatie’s Laravel Activity Log for simpler cases.
• Non-Laravel PHP:
  • Works with any PSR-3 logger (e.g., Symfony’s MonologBundle), but loses Laravel-specific conveniences (e.g., channels, stack traces).

Migration Path

1. Assess Current Logging:
   • Audit existing command logging (e.g., Log::debug('Command executed') in handlers). Identify gaps (e.g., missing payloads, no timing).
2. Install & Configure:

   composer require league/tactician-logger
   

   Register the logger middleware in AppServiceProvider:

   use League\Tactician\Logger\CommandLoggerMiddleware;
   use League\Tactician\Logger\Handler\CommandLoggerHandler;
   use Psr\Log\LoggerInterface;
   
   public function register()
   {
       $this->app->bind(CommandLoggerMiddleware::class, function ($app) {
           return new CommandLoggerMiddleware(
               new CommandLoggerHandler($app->make(LoggerInterface::class))
           );
       });
   }
   

3. Integrate with Command Bus:
   • For Tactician:

     $bus = new CommandBus([
         new CommandLoggerMiddleware($logger),
         // ... other middleware
     ]);
     

   • For Laravel’s Bus: Wrap the bus in Tactician’s CommandBus or use a custom middleware to log before/after execution.
4. Customize Logging:
   • Extend CommandLoggerHandler to filter sensitive data or add context:

     $handler = new CommandLoggerHandler($logger, [
         'exclude_commands' => ['PasswordResetCommand'],
         'include_context' => ['user_id', 'request_id']
     ]);
     

Compatibility

Sequencing

1. Phase 1: Pilot Logging
   • Enable logging for non-critical commands (e.g., SendEmailCommand) to validate format and performance.
2. Phase 2: Audit Integration
   • Route logs to an external system (e.g., ELK) for long-term storage.
3. Phase 3: Context Enrichment
   • Add request IDs, user contexts, or performance metrics (e.g., handler execution time).
4. Phase 4: Error Handling
   • Configure log levels (ERROR, CRITICAL) for failed commands and integrate with Laravel’s error reporting.

Operational Impact

Maintenance

• Dependency Management:
  • Minimal: Only league/tactician-logger and PSR-3 logger (already in Laravel).
  • Update strategy: Tie to Laravel’s minor version updates (e.g., update when Laravel 11 drops PHP 8.1 support).
• Configuration Drift:
  • Centralize logger settings in config/logging.php or environment variables (e.g., LOG_LEVEL=debug).
  • Use Laravel’s Log::extend() to dynamically switch log handlers.

Support

• Debugging Workflow:
  • Pros: Reduces manual dd()/Log::debug() in handlers. Logs include command payloads, timestamps, and middleware context.
  • Cons: Over-logging may obscure errors. Use log level filtering (e.g., INFO for production, DEBUG for local).
• Support Team Training:
  • Document log format for devs/SREs (e.g., JSON structure, context keys).
  • Example log entry:

    {
      "level": "info",
      "command": "App\\Commands\\CreateUserCommand",
      "payload": {"name": "John", "email": "john@example.com"},
      "handler": "App\\Handlers\\CreateUserHandler",
      "duration_ms": 42,
      "context": {"user_id": 123, "request_id": "abc123"}
    }
    

Scaling

• Performance at Scale:
  • Async Logging: Use monolog/handler-async to avoid blocking command execution.
  • Log Sampling: For high-volume systems, sample logs (e.g., 1% of commands) using a custom CommandLoggerHandler.
  • Log Retention: Offload to external storage (e.g., S3,