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)

Add the repository to your composer.json:

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

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

Publish configuration:

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

Update config/logging.php:

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

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:

GitHub: https://github.com/lfffd/laravel-logging
Docs: https://github.com/lfffd/laravel-logging
Issues: https://github.com/lfffd/laravel-logging/issues

License

MIT License - see LICENSE file for details

lfffd / laravel-logging

Maintainers

Details