Logger Plugin Laravel Package

Technical Evaluation

Architecture Fit

• Enhanced Observability: The addition of request uri to log context in 1.5.0 improves traceability for debugging and monitoring, especially in distributed systems where HTTP requests may span multiple services. This aligns with Laravel’s observability goals (e.g., tracking API calls across microservices or third-party integrations).
• PSR-3/HTTPlug Synergy: The change remains non-intrusive, as it only augments existing log metadata without altering the plugin’s core functionality or Laravel’s integration patterns (e.g., Monolog, Guzzle).
• Debugging Workflow: The request uri field simplifies correlation between logs and specific API endpoints, reducing the need for manual log parsing or context-switching during troubleshooting.

Integration Feasibility

• Zero Breaking Changes: The new field is additive and backward-compatible. Existing Laravel applications using the plugin will continue to function without modification.
• Log Format Evolution: The update aligns with best practices for structured logging (e.g., including uri alongside method, status_code, and headers). Laravel’s Monolog can handle this extension seamlessly, especially if using structured handlers (e.g., Monolog\Handler\BufferHandler with JSON formatting).
• Tooling Compatibility: Enhanced logs will improve compatibility with observability tools (e.g., ELK, Datadog, Loki) that rely on URI-based filtering or correlation. For example:

  {
    "level": "info",
    "message": "Request completed",
    "context": {
      "uri": "/api/v1/users",
      "method": "GET",
      "status_code": 200
    }
  }
  

Technical Risk

• Log Bloat: Including uri in logs may increase storage/transmission costs for high-volume systems. Mitigation:
  • Configure the plugin to exclude uri in production (if not critical) via LoggerPlugin::FORMAT_TIDY or custom context filtering.
  • Use log sampling or retention policies (e.g., Monolog’s FingersCrossedHandler).
• Tooling Assumptions: Some log aggregation tools may require reconfiguration to parse the new field. For example:
  • ELK: Update logstash grok patterns or filebeat processors.
  • Datadog: Ensure the uri field is mapped to the correct attribute in the APM/Logs UI.
• Performance: Minimal impact expected, as the uri is likely cached or extracted during request processing (not dynamically computed per log event).

Key Questions

1. Log Structure Strategy:
   • How are logs currently structured/parsed in your observability pipeline? Will the new uri field require updates to:
     • Logstash grok patterns?
     • Datadog/Fluentd filters?
     • Custom log processors (e.g., Laravel’s Log::stack)?
   • Is there a need to standardize log formats across services (e.g., via a shared Monolog configuration package)?
2. Sensitive URI Handling:
   • Are there URIs containing sensitive data (e.g., /api/v1/users/{id} with PII)? If so, will the uri be masked or excluded in production?
   • Example: Configure the plugin to redact paths:

     $plugin = new LoggerPlugin($logger, true, [
         'exclude' => ['uri' => '/api/v1/users/\d+']
     ]);
     

3. Tooling Validation:
   • Have you tested the new log format with your primary observability tools (e.g., Kibana dashboards, Datadog service maps)?
   • Will the uri field enable new use cases (e.g., URI-based alerting, latency tracking)?
4. Backward Compatibility:
   • Are there existing scripts or tools parsing logs that might break with the new field? If so, plan a phased rollout to update consumers first.
5. Configuration Management:
   • How will the uri inclusion/exclusion be managed across environments (dev/staging/prod)? Example:

     $loggerPlugin = config('http.logger.enabled') ?
         new LoggerPlugin($logger, config('http.logger.include_uri')) : null;
     

Integration Approach

Stack Fit

• Laravel-Specific Enhancements:
  • Log Channel Customization: Leverage Laravel’s log channel configuration to control uri inclusion. Example in config/logging.php:

    'channels' => [
        'http' => [
            'driver' => 'single',
            'handler' => Monolog\Handler\StreamHandler::class,
            'with' => [
                'uri_included' => env('HTTP_LOG_URIS', true),
            ],
        ],
    ],
    

  • Service Provider Integration: Extend the existing HttpPluginServiceProvider to pass the uri flag dynamically:

    $this->app->singleton(\Http\Client\PluginClient::class, function ($app) {
        $logger = $app->make(\Psr\Log\LoggerInterface::class);
        $includeUri = config('http.logger.include_uri', true);
        return new PluginClient(
            new Guzzle6Adapter(new \GuzzleHttp\Client()),
            [new LoggerPlugin($logger, $includeUri)]
        );
    });
    

• Observability Pipeline:
  • ELK Stack: Update logstash.conf to handle the new field:

    filter {
      grok {
        match => { "message" => "%{HTTPDATE:timestamp} %{LOGLEVEL:level} %{GREEDYDATA:context}" }
        remove_field => ["message"]
      }
      mutate {
        add_field => { "uri" => "%{context:uri}" }
      }
    }
    

  • Datadog: Ensure the uri field is mapped in datadog.yaml:

    logs:
      - type: file
        path: storage/logs/laravel.log
        source: laravel
        service: my-app
        fields:
          uri: context.uri
    

Migration Path

1. Phase 0: Validation (0.5 Days)

   • Goal: Verify the new uri field works with your logging stack.
   • Steps:
     • Update dependencies:

       composer require php-http/logger-plugin:^1.5.0
       

     • Test locally with a sample request:

       $client = new PluginClient(
           new Guzzle6Adapter(new \GuzzleHttp\Client()),
           [new LoggerPlugin(\Log::getMonolog(), true)]
       );
       $response = $client->sendRequest(new \GuzzleHttp\Psr7\Request('GET', 'https://api.example.com/data'));
       

     • Check logs for the uri field:

       {
         "context": {
           "uri": "https://api.example.com/data",
           ...
         }
       }
       

     • Validate with your log aggregation tool (e.g., Kibana query: log.context.uri: "api.example.com").

2. Phase 1: Configuration Rollout (1 Day)

   • Goal: Centralize uri control via Laravel config.
   • Steps:
     • Add to .env:

       HTTP_LOG_URIS=true
       

     • Update config/http.php (if using a custom config):

       'logger' => [
           'include_uri' => env('HTTP_LOG_URIS', true),
       ],
       

     • Update the service provider to respect the config (as shown above).

3. Phase 2: Tooling Updates (2–3 Days)

   • Goal: Align observability tools with the new field.
   • Steps:
     • ELK: Deploy updated logstash/filebeat configs.
     • Datadog: Update service mappings or dashboards to use the uri field.
     • Custom Scripts: Audit and update any log-parsing scripts (e.g., Python grep, jq filters).

4. Phase 3: Monitoring (1 Week)

   • Goal: Ensure the uri field doesn’t introduce noise or performance issues.
   • Steps:
     • Set up alerts for log volume spikes (e.g., Datadog anomaly detection).
     • Monitor latency impact (e.g., compare request times with/without uri logging).
     • Gather feedback from developers using the logs (e.g., Slack survey or retrospective).

Compatibility

• Laravel Versions:
  • Tested with Laravel 8/9 (Guzzle 7). No known conflicts, but verify if using custom Guzzle middleware that might interfere with HTTPlug’s request lifecycle.
• Log Handlers:
  • Monolog: Fully compatible. Use Processor\UidProcessor or custom processors to enrich logs further.
  • Symfony Logger: Works if wrapped in a PSR-3 adapter (e.g., Monolog\Handler\SymfonyBridgeHandler).
• HTTPlug Plugins:
  • No conflicts expected with other plugins (e.g., RetryPlugin, CachePlugin), as the uri