Logging Laravel Package

Technical Evaluation

Architecture Fit

• Unified Logging Standardization: The package enforces a strict JSON schema (SchemaFormatterV1) for logs, ensuring consistency across microservices—ideal for distributed systems (e.g., Laravel/Symfony APIs, event-driven architectures). This aligns with modern observability practices (e.g., OpenTelemetry compatibility).
• Monolog Integration: Leverages Laravel’s native Monolog support (via illuminate/log) with minimal friction. The Symfony Bundle pattern can be adapted via Laravel’s service container (e.g., Laravel\Lumen\Framework\Application or Laravel\SymfonyBridge\BridgeServiceProvider).
• Trace Context Enrichment: OpenTelemetry integration enables distributed tracing without reinventing wheel, critical for debugging latency in microservices.

Integration Feasibility

• Laravel Compatibility:
  • Monolog: Laravel 8+ uses Monolog 2.x/3.x (compatible with package constraints).
  • Service Container: The Symfony Bundle can be manually registered in Laravel’s config/app.php under providers (similar to config/bundles.php in Symfony).
  • Configuration: Replace Symfony’s logging.yaml with Laravel’s config/logging.php (see Laravel Logging Configuration).
• Non-Symfony Path: The package provides a pure Monolog setup (docs/integration-guide.md#7), avoiding Symfony dependencies entirely.

Technical Risk

Key Questions

1. Trace Context Reliability:

   • How will OpenTelemetry spans be propagated in Laravel’s request lifecycle (e.g., middleware vs. service layer)?
   • Example: If using laravel-otel, ensure OpenTelemetryTraceContextProvider is injected into the logger.

2. Log Schema Evolution:

   • What’s the process for adding custom fields (e.g., user_id) to the JSON schema without forking the package?
   • Workaround: Extend SchemaFormatterV1 via Laravel’s service binding.

3. Legacy Handler Support:

   • Which Laravel log channels (e.g., single, daily) are compatible with SchemaFormatterV1?
   • Test: Verify channels.php handlers like Monolog\Handler\FingersCrossedHandler support setFormatter().

4. Observability Tooling:

   • How will logs be ingested (e.g., ELK, Datadog, Loki)?
   • Note: JSON schema must match parser expectations (e.g., timestamp format, level as integer).

5. Rollout Strategy:

   • Should logging be enabled in staging first to validate schema compatibility with downstream tools?
   • Recommendation: Use --dry-run mode (if available) or mock logging:scan.

Integration Approach

Stack Fit

• Laravel Core: Works with Laravel 8/9/10 via Monolog (no Symfony required).
• Lumen: Lightweight alternative; follow pure Monolog setup (docs/integration-guide.md#7).
• Laravel Octane: Compatible with Swoole/React; ensure async loggers (e.g., AsyncHandler) support formatters.
• Testing: Use laravel-debugbar or monolog-test-handler to validate log structure.

Migration Path

1. Phase 1: Schema Adoption (Low Risk)

   • Replace existing log channels with SchemaFormatterV1:

     // config/logging.php
     'channels' => [
         'structured' => [
             'driver' => 'monolog',
             'handler' => Monolog\Handler\StreamHandler::class,
             'with' => [
                 'formatter' => Adheart\Logging\Core\Formatters\SchemaFormatterV1::class,
                 'formatter_with' => [
                     'schema_version' => '1.0.0',
                     'service_name' => 'laravel-api',
                     'service_version' => env('APP_VERSION'),
                 ],
             ],
         ],
     ],
     

   • Add message_normalizer processor to critical loggers:

     $logger->pushProcessor(new Adheart\Logging\Core\Processors\MessageNormalizerProcessor());
     

2. Phase 2: Trace Integration (Medium Risk)

   • Install OpenTelemetry PHP SDK (open-telemetry/opentelemetry-php).
   • Configure otel_trace in config/logging.php (alias-based):

     logging:
       integrations:
         - otel_trace
       aliases:
         trace_providers:
           otel: '@opentelemetry.trace.provider'
     

   • Verify traces appear in logs:

     "trace": {
       "trace_id": "00000000000000000000000000000001",
       "span_id": "0000000000000001"
     }
     

3. Phase 3: Scan & Optimize (High Value)

   • Run logging:scan to audit logger usage:

     php artisan logging:scan --summary --paths=app/Http
     

   • Fix gaps (e.g., missing context in business logic layers).

Compatibility

Sequencing

1. Pre-requisites:

   • PHP 8.2+ (Laravel 9+).
   • Monolog 3.x (Laravel 10) or 2.9+ (Laravel 8).
   • OpenTelemetry SDK (if using traces).

2. Order of Operations:

   • Step 1: Add package to composer.json and register bundle.
   • Step 2: Configure SchemaFormatterV1 in logging.php.
   • Step 3: Add processors to core loggers (e.g., app, query).
   • Step 4: Enable otel_trace and validate traces.
   • Step 5: Run logging:scan and iterate.

3. Rollback Plan:

   • Disable bundle via config/app.php:

     'providers' => [
         // Adheart\Logging\LoggingBundle::class => false,
     ],
     

   • Revert to default Monolog formatters.

Operational Impact

Maintenance

• Pros:
  • Reduced Boilerplate: Centralized log formatting/processing.
  • Schema Enforcement: Prevents ad-hoc log field additions.
  • Auditability: logging:scan tracks logger usage over time.
• Cons:
  • Customization Limits: Extending schema requires subclassing SchemaFormatterV1.
  • Dependency on OpenTelemetry: Trace context relies on instrumentation.

Support

• Debugging:
  • Use logging:scan --list-loggers to identify misconfigured loggers.
  • Validate JSON output with:

    php artisan log:read --channel=structured | jq .
    

• Common Issues:
  • Missing Trace Data: Ensure OpenTelemetry spans are active when logging.
  • Formatter Not Applied: Check handler supports setFormatter() (e.g., StreamHandler vs. NullHandler).

Scaling

• Performance:
  • Processors add ~1–5ms per log; benchmark in production.
  • For high-volume logs (e.g., 10K+/s), use AsyncHandler:

    $handler = new Monolog\Handler\AsyncHandler(new StreamHandler('php://stdout'));
    

• Resource Usage:
  • logging:scan consumes CPU during analysis (run in CI or staging).

Failure Modes

| Scenario | Impact | Mitigation | |-----------------------------------|--------------------------------