PHPackages                             lfffd/laravel-logging - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. lfffd/laravel-logging

ActiveLibrary[Logging & Monitoring](/categories/logging)

lfffd/laravel-logging
=====================

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

017PHP

Since Oct 28Pushed 6mo agoCompare

[ Source](https://github.com/lfffd/laravel-logging)[ Packagist](https://packagist.org/packages/lfffd/laravel-logging)[ RSS](/packages/lfffd-laravel-logging/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Superlog - Advanced Laravel Logging Engine
==========================================

[](#superlog---advanced-laravel-logging-engine)

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

Features
--------

[](#features)

### 🔗 First-Class Correlation

[](#-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)
- **Non-HTTP context support**: Automatic trace ID generation for CLI commands, queue jobs, and webhooks
- **Temporary trace IDs**: Uses temporary IDs (prefixed with `tmp/`) until a permanent ID can be established, ensuring consistent correlation even before session initialization
- **Consistent correlation**: Maintains the same trace ID across all logs in a request, even in complex middleware stacks and webhooks

### 📊 Sections with Timing & Resources

[](#-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
- **\[MODEL/$model\_name/$VERB\]**: Eloquent model operations with SQL query, execution time, and record count (VERB is SELECT, INSERT, UPDATE, DELETE, etc.)
- **\[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

[](#-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

[](#-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

[](#-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

[](#-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
------------

[](#installation)

### From GitHub (Before Packagist Publication)

[](#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)

[](#from-packagist-after-publication)

```
composer require lfffd/laravel-logging
```

### Configuration

[](#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
---------------------

[](#configuration-options)

See `config/superlog.php` for all available options:

### Core Settings

[](#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'),
```

### Non-HTTP Context Logging

[](#non-http-context-logging)

```
'non_http_context' => [
    'enabled' => env('SUPERLOG_NON_HTTP_CONTEXT_ENABLED', true),
    'generate_trace_id' => true,
    'prefix_trace_id' => true, // Adds 'cli_', 'job_', etc. prefix to trace IDs
],
```

### Temporary Trace IDs

[](#temporary-trace-ids)

```
// Temporary trace IDs are automatically used before a permanent ID is established
// They are prefixed with 'tmp/' and are replaced with permanent IDs when available
// This ensures consistent correlation even before session initialization
```

### Sampling

[](#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-detection)

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

### Model Query Logging

[](#model-query-logging)

```
'model_query_logging' => [
    'enabled' => env('SUPERLOG_MODEL_QUERY_LOGGING', true),
    'log_level' => env('SUPERLOG_MODEL_QUERY_LOG_LEVEL', 'debug'),
    'include_bindings' => env('SUPERLOG_MODEL_QUERY_INCLUDE_BINDINGS', true),
    'slow_query_threshold_ms' => env('SUPERLOG_MODEL_SLOW_QUERY_MS', 100),
],
```

### PII Redaction

[](#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)

```
'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
--------------

[](#usage-examples)

### Basic Logging

[](#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,
]);

// Model operations are automatically logged with the ModelQueryProcessor
// Example output for User::find(1):
// [MODEL/User/SELECT] Model User SELECT operation {"sql":"SELECT * FROM users WHERE id = 1 LIMIT 1"} {"duration_ms":5.2,"record_count":1}
```

### Manual Correlation

[](#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');

// Set a permanent trace ID (replaces any temporary ID)
$correlation->setTraceId('permanent-trace-id');

// Check if the current trace ID is temporary
$isTemporary = strpos($correlation->getTraceId(), 'tmp/') === 0;
```

### Integration with Laravel Features

[](#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
-------------

[](#sample-output)

### JSON Format - Middleware Example

[](#json-format---middleware-example)

```
{
  "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
  }
}
```

### JSON Format - Model Query Example

[](#json-format---model-query-example)

```
{
  "timestamp": "2025-10-20T09:13:47.123456Z",
  "trace_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "req_seq": "0000000002",
  "span_id": "c6d7e8f9-a0b1-2345-6789-0abcdef12345",
  "level": "DEBUG",
  "section": "[MODEL/User/SELECT]",
  "message": "Model User SELECT operation",
  "context": {
    "sql": "SELECT * FROM users WHERE id = 1 LIMIT 1",
    "bindings": [1]
  },
  "metrics": {
    "duration_ms": 5.2,
    "record_count": 1,
    "connection": "mysql"
  },
  "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)

[](#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
------------------------------------

[](#advanced-shipping-to-elkopensearch)

### Environment Setup

[](#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

[](#queue-worker)

```
php artisan queue:work --queue=superlog
```

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

Performance Considerations
--------------------------

[](#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
----------------------

[](#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
-------

[](#support)

For issues, feature requests, or documentation, visit:

- GitHub:
- Docs:
- Issues:

License
-------

[](#license)

MIT License - see LICENSE file for details

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance49

Moderate activity, may be stable

Popularity6

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/4c538b6d3720dabfb0b0dd5d8558aef6036ae457f0ca1b6eea03673faf08edab?d=identicon)[lfffd](/maintainers/lfffd)

### Embed Badge

![Health badge](/badges/lfffd-laravel-logging/health.svg)

```
[![Health](https://phpackages.com/badges/lfffd-laravel-logging/health.svg)](https://phpackages.com/packages/lfffd-laravel-logging)
```

###  Alternatives

[psr/log

Common interface for logging libraries

10.4k1.2B9.1k](/packages/psr-log)[itsgoingd/clockwork

php dev tools in your browser

5.9k27.6M93](/packages/itsgoingd-clockwork)[graylog2/gelf-php

A php implementation to send log-messages to a GELF compatible backend like Graylog2.

41838.2M137](/packages/graylog2-gelf-php)[bugsnag/bugsnag-psr-logger

Official Bugsnag PHP PSR Logger.

32132.5M2](/packages/bugsnag-bugsnag-psr-logger)[consolidation/log

Improved Psr-3 / Psr\\Log logger based on Symfony Console components.

15462.2M7](/packages/consolidation-log)[datadog/php-datadogstatsd

An extremely simple PHP datadogstatsd client

19124.6M15](/packages/datadog-php-datadogstatsd)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)