Logging Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require adheart/logging
   

   Register the bundle in config/bundles.php (if not using Symfony Flex):

   Adheart\Logging\LoggingBundle::class => ['all' => true],
   

2. Basic Configuration (config/packages/logging.yaml):

   logging:
     processors:
       - message_normalizer
     formatter:
       schema_version: '1.0.0'
       service_name: 'your-service'
       service_version: '%env(RELEASE_ID)%'
   

3. First Log Test:

   $logger = $this->container->get('logger');
   $logger->info('Test log', ['key' => 'value']);
   

   Verify output is a valid JSON with service and version fields.

Implementation Patterns

Core Workflow

1. Unified Logging Structure:

   • All logs follow SchemaFormatterV1 (JSON format with timestamp, level, message, context, service, trace, version).
   • Example:

     {
       "service": {"name": "your-service", "version": "1.0.0"},
       "trace": {"trace_id": "..."}
     }
     

2. Processor Integration:

   • message_normalizer: Auto-detects JSON messages and moves them to context.message_json.

     $logger->info('{"error": "invalid"}'); // Moves JSON to context
     

   • trace: Enriches logs with OpenTelemetry trace context (if otel_trace integration is enabled).

3. Trace Context:

   • Enable otel_trace in logging.yaml to inject trace_id, span_id, and cf-ray headers:

     logging:
       integrations:
         - otel_trace
     

4. Non-Symfony Projects:

   • Manually configure Monolog stack:

     use Adheart\Logging\Core\Formatters\SchemaFormatterV1;
     use Adheart\Logging\Core\Processors\MessageNormalizerProcessor;
     
     $handler = new StreamHandler('php://stdout');
     $handler->setFormatter(new SchemaFormatterV1('1.0.0', 'your-service', '1.0.0'));
     
     $logger = new Logger('app');
     $logger->pushHandler($handler);
     $logger->pushProcessor(new MessageNormalizerProcessor());
     

5. Custom Processors/Providers:

   • Define aliases in logging.yaml:

     logging:
       aliases:
         processors:
           custom_processor: '@app.logging.processor.custom'
         trace_providers:
           app_provider: '@app.trace.provider'
     

Gotchas and Tips

Pitfalls

1. Formatter Not Applied:

   • Cause: Handler lacks setFormatter() support (e.g., FingersCrossedHandler).
   • Fix: Use compatible handlers (e.g., StreamHandler, SyslogHandler).

2. Missing Trace Fields:

   • Cause: otel_trace integration not enabled or no active OpenTelemetry span.
   • Fix: Verify logging.integrations and ensure spans are created before logging.

3. Configuration Errors:

   • Unknown alias: Validate logging.integrations and aliases sections.
   • Service not found: Ensure custom processors/providers are registered in DI container.

4. JSON Message Handling:

   • message_normalizer moves JSON to context.message_json but loses the original JSON structure in message. Use explicitly:

     $logger->info('Custom message', ['json_data' => json_encode(['key' => 'value'])]);
     

Debugging Tips

• Validate Logs: Use logging:scan --summary to audit logger usage.

  php bin/console logging:scan --format=json
  

• Check Trace Context: Ensure OpenTelemetry\API is initialized before logging.
• Environment Variables: Use %env(RELEASE_ID)% for dynamic service_version.

Extension Points

1. Custom Processors:

   • Implement Monolog\Processor\ProcessorInterface and register via aliases.processors.
   • Example:

     logging:
       aliases:
         processors:
           custom: '@app.processor.custom'
     

2. Trace Providers:

   • Extend Adheart\Logging\Core\Trace\TraceContextProviderInterface for custom trace sources (e.g., AWS X-Ray).
   • Register via aliases.trace_providers.

3. Integrations:

   • Define custom integrations in aliases.integrations:

     logging:
       aliases:
         integrations:
           custom_integration:
             processors: ['trace']
             trace_providers: ['app_provider']
     

Performance

• Avoid Overhead: Disable unused processors (e.g., trace if not using OpenTelemetry).
• Handler Optimization: Use BufferHandler for batching logs in high-throughput services.

Production Checklist

1. Validate Schema: Ensure all logs conform to SchemaFormatterV1.
2. Trace Correlation: Test trace_id propagation across microservices.
3. Scan for Gaps: Run logging:scan to identify missing loggers or severity levels.
4. Monitor Log Volume: High log rates may impact performance; consider async handlers.