Trazas Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require boson/trazas-bundle
   

   Enable it in config/bundles.php:

   Boson\TrazasBundle\BosonTrazasBundle::class => ['all' => true],
   

2. First Use Case Inject the TrazasService into a controller or service:

   use Boson\TrazasBundle\Service\TrazasService;
   
   class MyController extends AbstractController
   {
       public function __construct(private TrazasService $trazasService) {}
   
       public function index()
       {
           $this->trazasService->log('user_action', ['user_id' => 123]);
           return new Response('Logged!');
       }
   }
   

3. Where to Look First

   • Documentation: Check Resources/doc/index.rst for API details.
   • Configuration: Override defaults in config/packages/boson_trazas.yaml.
   • Event Listeners: Review EventListener/ for hooks (e.g., TrazasSubscriber).

Implementation Patterns

Core Workflows

1. Logging Traces Use TrazasService for structured logging:

   $this->trazasService->log('event_name', [
       'metadata' => ['key' => 'value'],
       'context' => ['user_id' => 123, 'ip' => $request->getClientIp()]
   ]);
   

2. Integration with Symfony Events Subscribe to kernel events to auto-log actions:

   # config/packages/boson_trazas.yaml
   boson_trazas:
       listeners:
           - { event: 'kernel.request', method: 'onKernelRequest' }
   

3. Database Storage Configure storage in boson_trazas.yaml:

   boson_trazas:
       storage:
           driver: 'doctrine'  # Options: 'doctrine', 'monolog', 'custom'
           options:
               table: 'app_trace_logs'
   

4. Custom Handlers Extend TrazasHandlerInterface for custom storage:

   class CustomTrazasHandler implements TrazasHandlerInterface
   {
       public function handle(array $trace): void
       {
           // Custom logic (e.g., send to external API)
       }
   }
   

Gotchas and Tips

Pitfalls

1. Doctrine Dependency

   • If using driver: 'doctrine', ensure doctrine/doctrine-bundle is installed.
   • Migrations may be required for the default table schema.

2. Performance Overhead

   • Heavy logging can impact performance. Use level filtering:

     boson_trazas:
         level: 'info'  # Options: 'debug', 'info', 'notice', 'warning', 'error'
     

3. Event Subscriber Conflicts

   • Overlapping event listeners (e.g., kernel.request) may cause duplicate logs.
   • Use unique IDs or disable built-in listeners if needed.

Debugging Tips

1. Check Log Levels Enable debug logs to verify trace storage:

   monolog:
       handlers:
           main:
               level: debug
   

2. Validate Configuration Use Symfony’s config validator:

   php bin/console debug:config boson_trazas
   

3. Custom Handler Debugging For driver: 'custom', implement TrazasHandlerInterface and verify the handle() method is called via:

   $this->trazasService->log('test', []); // Check if your handler processes it
   

Extension Points

1. Add Fields to Traces Extend the Trace entity (if using Doctrine) or modify the log() payload:

   $this->trazasService->log('custom_event', [
       'extra_field' => 'value',
       '_custom_metadata' => ['processed' => true] // Prefix for custom keys
   ]);
   

2. Create Custom Commands Build CLI tools to export/analyze traces:

   namespace App\Command;
   
   use Boson\TrazasBundle\Service\TrazasService;
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class ExportTracesCommand extends Command
   {
       protected static $defaultName = 'app:export-traces';
       private TrazasService $trazasService;
   
       public function __construct(TrazasService $trazasService)
       {
           $this->trazasService = $trazasService;
           parent::__construct();
       }
   
       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           $traces = $this->trazasService->getAllTraces();
           // Export logic...
       }
   }
   

3. Override Templates If the bundle includes views (e.g., for dashboards), override them in templates/boson_trazas/.