Ecs Logging Bundle Laravel Package

Getting Started

To quickly integrate this package into a Laravel project, start by installing it via Composer:

composer require vendor/package-name

For Symfony users, refer to the new docs/symfony-logs.md for a baseline ECS log example. Laravel developers should focus on the package's core processors (e.g., HttpRequestProcessor, UserProcessor) and the EcsUserProvider for user context enrichment.

First Use Case: Enable basic ECS logging in Laravel by publishing the config:

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"

Configure the processors array in config/package-name.php to include:

'processors' => [
    \Vendor\PackageName\Processors\HttpRequestProcessor::class,
    \Vendor\PackageName\Processors\UserProcessor::class,
],

Then inject the EcsLogger into your controller/service:

use Vendor\PackageName\EcsLogger;

class ExampleController
{
    public function __construct(private EcsLogger $logger) {}

    public function index()
    {
        $this->logger->info('Example log message');
    }
}

Implementation Patterns

Laravel-Specific Workflows

1. Contextual Logging: Use EcsUserProvider to attach user data (e.g., ID, roles) to logs. Example:

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

   Ensure EcsUserProvider is registered in config/package-name.php under providers.

2. HTTP Request Tracking: The HttpRequestProcessor automatically enriches logs with:

   • URI, method, IP, user agent.
   • Enable via the processors config array (see Getting Started).

3. OpenTelemetry Integration (Advanced): For distributed tracing, combine with the package’s advanced example. Add the OpenTelemetryProcessor to your config and ensure the OpenTelemetry PHP SDK is installed:

   composer require open-telemetry/opentelemetry
   

Symfony Integration

• Follow the Symfony logs guide for ECS-formatted logs.
• In FrankenPHP worker mode, the package now resets cached state between requests (see Gotchas).

Service Provider Binding

Bind custom processors or providers in your AppServiceProvider:

public function register()
{
    $this->app->bind(
        \Vendor\PackageName\Contracts\UserProvider::class,
        \App\Providers\CustomUserProvider::class
    );
}

Gotchas and Tips

FrankenPHP Worker Mode Fix

• Issue: Processors like HttpRequestProcessor and EcsUserProvider may retain stale state between requests in FrankenPHP’s worker mode.
• Fix: The package now tags these with kernel.reset, forcing Symfony to clear their state. No action required unless you’ve overridden their lifecycle.

Dependency Injection (DI) for EcsUserProvider

• Change: security.token_storage is now injected explicitly via DI arguments (instead of autowiring).
• Impact: If you extended EcsUserProvider, update your constructor to accept the token storage:

  public function __construct(private TokenStorageInterface $tokenStorage) {}
  

Debugging Tips

1. Processor Order Matters: Logs are processed in the order defined in config/package-name.php. Place UserProcessor before HttpRequestProcessor if user data should override request metadata.

2. Symfony-Specific Quirks:

   • Ensure your monolog bundle is configured to use the ecs formatter.
   • For FrankenPHP, verify the kernel.reset tag is applied to custom processors if they cache state.

3. OpenTelemetry Setup:

   • The advanced example includes a full stack trace setup. Test locally with:

     OTLP_ENDPOINT="http://localhost:4317" vendor/bin/otelcli
     

Extension Points

• Custom Processors: Extend \Vendor\PackageName\Contracts\ProcessorInterface to add fields (e.g., DatabaseProcessor for query logs). Example:

  class DatabaseProcessor implements ProcessorInterface
  {
      public function __invoke(array $record): array
      {
          $record['context']['db'] = DB::getQueryLog();
          return $record;
      }
  }
  

  Register it in config/package-name.php.

• Overriding EcsUserProvider: Create a custom provider and bind it (see Implementation Patterns). Example:

  class CustomUserProvider implements UserProvider
  {
      public function getUser(): ?array
      {
          return ['id' => auth()->id(), 'custom_field' => 'value'];
      }
  }