lfffd/laravel-logging

Advanced Laravel logging engine with structured correlation, PII guard, and performance diagnostics

Maintainers

Details

github.com/lfffd/laravel-logging

Source

Issues

Installs: 16

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/lfffd/laravel-logging

dev-main 2025-10-20 13:01 UTC

Requires

Requires (Dev)

MIT 74467ec0fae25054e584f76d208ab38687781bcb

This package is auto-updated.

Last update: 2025-10-20 13:05:35 UTC

README

An enterprise-grade structured logging package for Laravel with built-in correlation tracking, PII redaction, performance diagnostics, and seamless ELK/OpenSearch integration.

Features

🔗 First-Class Correlation

  • trace_id (UUID v4): Spans the entire request/job lifecycle
  • req_seq (fixed-width 10 chars): Incremental ID per log line within a request
  • span_id: Per-section correlation (startup, middleware, db, http, shutdown)

📊 Sections with Timing & Resources

  • [STARTUP]: Route, HTTP verb, IP, user/tenant, session ID, payload sizes, user-agent
  • [MIDDLEWARE START/END]: Auto-emitted with duration (ms) and response status
  • [DATABASE]: Aggregated query count, total query time, slowest query, slow query list
  • [HTTP-OUT]: Guzzle taps with URL, method, status, duration, retry count, circuit state
  • [CACHE]: Hits, misses, sets, duration
  • [SHUTDOWN]: Request time, response status, peak memory, response bytes, PHP opcache status

🔐 Redaction & PII Guard

  • Smart defaults + zero-config safe defaults
  • Configurable key blacklist (email, password, token, authorization, IBAN, NIF, CC, SSN, phone, cookies)
  • Binary payloads and files summarized, not dumped
  • Customizable masking strategies

📈 Adaptive Verbosity & Sampling

  • Always log sections; sample noisy info/debug at configurable rates
  • Escalate to debug automatically on 4xx/5xx responses
  • Slow-request trigger (> 750ms default) adds extra diagnostics

⚡ Performance-Friendly

  • Processors (cheap) + deferred heavy collectors until shutdown
  • Optional async shipping via queue + HTTP handler
  • Minimal overhead even in high-traffic environments

📝 Structured JSON + Human Header

  • Pure JSON context for grep/ELK/OpenSearch shipping
  • Human-readable prefix for local development
  • Single daily file (standard Laravel rotation)

Installation

From GitHub (Before Packagist Publication)

  1. Add the repository to your composer.json:

    {
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/lfffd/laravel-logging.git"
    }
  ],
  "require": {
    "lfffd/laravel-logging": "dev-main"
  }
}

  2. Or run via command line:

    composer config repositories.superlog vcs https://github.com/lfffd/laravel-logging.git
composer require lfffd/laravel-logging:dev-main

From Packagist (After Publication)

composer require lfffd/laravel-logging

Configuration

  1. Publish configuration:

    php artisan vendor:publish --provider="Superlog\SuperlogServiceProvider"

  2. Update config/logging.php:

    'channels' => [
    // ... other channels
    'superlog' => [
        'driver' => 'superlog',
        'name' => 'superlog',
        'level' => 'debug',
    ],
],

  3. Register middleware in app/Http/Kernel.php:

    protected $middlewareGroups = [
    'web' => [
        // ... existing middleware
        \Superlog\Middleware\RequestLifecycleMiddleware::class,
    ],
];

Configuration Options

See config/superlog.php for all available options:

Core Settings

'enabled' => env('SUPERLOG_ENABLED', true),
'auto_capture_requests' => env('SUPERLOG_AUTO_CAPTURE', true),
'trace_id_header' => env('SUPERLOG_TRACE_ID_HEADER', 'X-Trace-Id'),

Sampling

'sampling' => [
    'enabled' => env('SUPERLOG_SAMPLING_ENABLED', false),
    'info_rate' => 0.1,   // 10% of INFO logs
    'debug_rate' => 0.05, // 5% of DEBUG logs
],

Slow Request Detection

'slow_request' => [
    'threshold_ms' => env('SUPERLOG_SLOW_REQUEST_MS', 750),
    'collect_queries' => true,
    'collect_cache_stats' => true,
    'collect_bindings_count' => true,
],

PII Redaction

'redaction' => [
    'enabled' => env('SUPERLOG_REDACTION_ENABLED', true),
    'mode' => 'mask', // 'mask' or 'remove'
    'smart_detection' => true,
    'custom_keys' => explode(',', env('SUPERLOG_REDACT_KEYS', '')),
],

Async Shipping

'async_shipping' => [
    'enabled' => env('SUPERLOG_ASYNC_ENABLED', false),
    'queue' => env('SUPERLOG_QUEUE', 'default'),
    'batch_size' => 100,
    'batch_timeout_ms' => 5000,
],

'external_handlers' => [
    [
        'driver' => 'http',
        'url' => env('SUPERLOG_HTTP_URL', 'http://localhost:9200'),
        'auth' => [
            'username' => env('SUPERLOG_HTTP_USER'),
            'password' => env('SUPERLOG_HTTP_PASS'),
        ],
        'timeout' => 10,
        'retry_count' => 3,
    ]
],

Usage Examples

Basic Logging

use Superlog\Facades\Superlog;

// Simple log with section
Superlog::log('info', 'CUSTOM_SECTION', 'User login successful', [
    'user_id' => 123,
], [
    'duration_ms' => 45.2,
]);

// Database logging
Superlog::logDatabase([
    'query_count' => 12,
    'total_query_ms' => 234.5,
    'slowest_query_ms' => 89.2,
    'slow_queries' => [
        'SELECT * FROM users WHERE email = ?',
    ],
]);

// HTTP outbound call
Superlog::logHttpOut('GET', 'https://api.example.com/users', 200, 567.8, [
    'retry_count' => 1,
    'circuit_breaker' => 'closed',
]);

// Cache statistics
Superlog::logCache([
    'hits' => 234,
    'misses' => 56,
    'sets' => 45,
    'duration_ms' => 12.3,
]);

Manual Correlation

use Superlog\Facades\Superlog;

// Get current correlation context
$correlation = Superlog::getCorrelation();
echo $correlation->getTraceId(); // UUID v4
echo $correlation->getDurationMs(); // Request duration

// Initialize custom trace (e.g., in queue jobs)
Superlog::initializeRequest('QUEUE', 'process_order', '127.0.0.1', 'custom-trace-id');

Integration with Laravel Features

The middleware automatically captures:

  • Request startup with route, IP, user/tenant info
  • Response status and timing
  • Memory peak usage
  • Included files count
  • Queue jobs dispatched

Sample Output

JSON Format

{
  "timestamp": "2025-10-20T09:13:46.343976Z",
  "trace_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "req_seq": "0000000001",
  "span_id": "b5c6d7e8-f9a0-1234-5678-90abcdef1234",
  "level": "INFO",
  "section": "[MIDDLEWARE END]",
  "message": "[MIDDLEWARE END] VerifyCsrfToken - SUCCESS",
  "context": {},
  "metrics": {
    "duration_ms": 11.75,
    "response_status": 200,
    "csrf_verified": true
  },
  "correlation": {
    "trace_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "method": "GET",
    "path": "/users",
    "client_ip": "192.168.1.100",
    "request_duration_ms": 245.32
  }
}

Text Format (Development)

[2025-10-20 09:13:46] local.INFO: [MIDDLEWARE END] VerifyCsrfToken - SUCCESS {"duration_ms":11.75,"response_status":200,"csrf_verified":true}

Advanced: Shipping to ELK/OpenSearch

Environment Setup

SUPERLOG_ASYNC_ENABLED=true
SUPERLOG_HTTP_URL=http://elasticsearch:9200/_bulk
SUPERLOG_HTTP_USER=elastic
SUPERLOG_HTTP_PASS=changeme
SUPERLOG_QUEUE=superlog

Queue Worker

php artisan queue:work --queue=superlog

The logs will be shipped in batches of 100 (configurable) to your Elasticsearch cluster.

Performance Considerations

  • Light processors: Correlation and sampling use minimal CPU
  • Deferred collectors: Memory and opcache stats gathered at shutdown only
  • Async shipping: Queue-based HTTP shipping prevents blocking requests
  • Sampling: Reduce noise on info/debug logs by 90%+ while keeping errors/warnings

Security & Privacy

By default, Superlog masks:

  • Passwords and tokens
  • Authorization headers
  • Credit card numbers
  • Social security numbers
  • Email addresses
  • Phone numbers
  • Cookie values

Customize via config/superlog.php or environment variables.

Support

For issues, feature requests, or documentation, visit:

License

MIT License - see LICENSE file for details