Microservice Log Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require cashier/microservice-log-bundle
   

   Enable the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Cashier\MicroserviceLogBundle\CashierMicroserviceLogBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console cashier:log:config:init
   

   Update config/packages/cashier_microservice_log.yaml with your logging targets (e.g., ELK, Loki, or custom HTTP endpoints):

   cashier_microservice_log:
       targets:
           - { type: 'http', url: '%env(LOG_TARGET_URL)%' }
       include_context: true
   

3. First Use Case Inject the logger into a service:

   use Cashier\MicroserviceLogBundle\Logger\MicroserviceLoggerInterface;
   
   class OrderService {
       public function __construct(private MicroserviceLoggerInterface $logger) {}
   
       public function processOrder() {
           $this->logger->info('Order processed', ['order_id' => 123]);
       }
   }
   

   The log will automatically include:

   • Microservice metadata (e.g., service_name, instance_id).
   • Request context (if include_context: true).

Implementation Patterns

Core Workflows

1. Structured Logging Use structured data for observability:

   $this->logger->error('Payment failed', [
       'amount' => 99.99,
       'currency' => 'USD',
       'gateway' => 'stripe',
       'metadata' => ['customer_id' => 'cust_123']
   ]);
   

2. Context Propagation Attach request-scoped context (e.g., user ID, request ID):

   $this->logger->withContext(['user_id' => $user->id])->info('User action');
   

3. Batching Logs For high-throughput services, batch logs before sending:

   cashier_microservice_log:
       batch:
           enabled: true
           max_items: 50
           flush_interval: 300 # seconds
   

4. Integration with Symfony Monolog Extend existing Monolog handlers:

   // config/packages/monolog.yaml
   monolog:
       handlers:
           cashier_log:
               type: service
               id: Cashier\MicroserviceLogBundle\Logger\MicroserviceHandler
               level: debug
   

Advanced Patterns

• Dynamic Targets: Route logs based on severity or service:

  targets:
      - { type: 'http', url: '%env(DEBUG_LOG_URL)%', levels: [debug] }
      - { type: 'http', url: '%env(PROD_LOG_URL)%', levels: [info, warning, error] }
  

• Correlation IDs: Auto-inject trace IDs from headers:

  cashier_microservice_log:
      correlation_id_header: 'X-Request-ID'
  

• Async Processing: Offload logging to a queue (e.g., Symfony Messenger):

  cashier_microservice_log:
      async: true
      queue_name: 'log_queue'
  

Gotchas and Tips

Common Pitfalls

1. Missing Metadata Ensure service_name and instance_id are set in config. Defaults to unknown if omitted:

   cashier_microservice_log:
       service_name: 'order-service'
       instance_id: '%kernel.environment%.%hostname%'
   

2. Synchronous Blocking Avoid flush() in async mode—logs may be delayed or dropped:

   // ❌ Bad: Blocks execution
   $this->logger->flush();
   
   // ✅ Good: Let the bundle handle it
   $this->logger->info('Non-blocking log');
   

3. Target Failures HTTP targets throw exceptions on failure. Use retries or dead-letter queues:

   targets:
       - { type: 'http', url: '%env(LOG_URL)%', retries: 3, timeout: 5 }
   

4. Context Leakage Sensitive data (e.g., passwords) in withContext() may leak to logs. Sanitize explicitly:

   $this->logger->withContext(['user_id' => $user->id])->info('Login');
   // Avoid: $this->logger->info('Login', ['token' => $user->apiToken]);
   

Debugging Tips

• Log Levels: Use debug to inspect bundle behavior:

  cashier_microservice_log:
      debug: true
  

• Test Targets: Point to a local endpoint for testing:

  targets:
      - { type: 'http', url: 'http://localhost:3000/logs' }
  

• Check Headers: Verify correlation IDs are propagated:

  curl -H "X-Request-ID: test123" http://your-service/api
  

Extension Points

1. Custom Handlers Implement Cashier\MicroserviceLogBundle\Logger\TargetInterface for new targets (e.g., Kafka, S3):

   class S3Target implements TargetInterface {
       public function send(array $logs): void {
           // Upload to S3
       }
   }
   

   Register in config:

   targets:
       - { type: 's3', bucket: 'logs-bucket' }
   

2. Preprocessors Modify logs before sending via Cashier\MicroserviceLogBundle\Event\LogEvent:

   // config/services.yaml
   Cashier\MicroserviceLogBundle\EventListener\LogPreprocessorListener:
       tags:
           - { name: kernel.event_listener, event: cashier.log.preprocess, method: onPreprocess }
   

3. Metrics Track log volume/latency via Prometheus:

   cashier_microservice_log:
       metrics:
           enabled: true
           namespace: 'cashier_logging'