README

Structured logging utilities for Laravel applications with formatters, writers, and middleware for comprehensive request tracking and debugging.

Features

• JSON Formatter - Single-line JSON logs for production (JSONL format)
• Hybrid Formatter - Human-readable logs with structured context for development
• Context-Aware Log Writer - HTTP request logging with automatic context inclusion
• HTTP Logger Middleware - Automatic HTTP request/response logging with context

Installation

This package is part of the Pixielity Framework and is automatically available.

Configuration

Log Format

Set the log format in your .env file:

# Development (human-readable)
LOG_FORMAT=hybrid

# Production (machine-readable JSON)
LOG_FORMAT=json

HTTP Logging

Configure HTTP logging in config/http-logger.php:

return [
    'enabled' => env('HTTP_LOGGER_ENABLED', true),
    'log_writer' => \Pixielitygging\Writers\ContextAwareLogWriter::class,
    'log_channel' => env('LOG_CHANNEL', 'stack'),
    'log_level' => 'info',
];

Formatters

JSON Formatter (Production)

Single-line JSON format for log aggregators (ELK, Datadog, CloudWatch):

{
    "timestamp": "2026-02-03T10:56:48.000000Z",
    "level": "INFO",
    "channel": "local",
    "message": "POST /api/v1/test",
    "context": {
        "request_id": "abc123",
        "ip": "127.0.0.1",
        "method": "POST",
        "route": "api/v1/test",
        "locale": "ar",
        "execution_time_ms": 5.45
    }
}

Usage with jq:

# Pretty print
tail -f storage/logs/laravel.log | jq '.'

# Filter by correlation_id
cat storage/logs/laravel.log | jq 'select(.context.correlation_id == "trace-123")'

# Get slow requests
cat storage/logs/laravel.log | jq 'select(.context.execution_time_ms > 100)'

Hybrid Formatter (Development)

Human-readable format with structured context:

[2026-02-03 10:56:48] local.INFO: POST /api/v1/test
Context: {"request_id":"abc123","ip":"127.0.0.1","method":"POST","route":"api/v1/test","locale":"ar","execution_time_ms":5.45}

Log Context

All logs automatically include comprehensive context:

• request_id - Unique request identifier
• correlation_id - For distributed tracing
• ip - Client IP address
• method - HTTP method (GET, POST, etc.)
• user_agent - Client user agent
• route - Route name or path
• session_id - Session identifier (if exists)
• timezone - Client timezone
• locale - Application locale
• user_id - Authenticated user ID (if authenticated)
• api_version - API version
• execution_time_ms - Request execution time
• memory_used_mb - Memory used by request

Middleware

HTTP Logger Middleware

Automatically logs all HTTP requests with full context:

#[Middleware(
    alias: 'http.logger',
    priority: 10
)]
class HttpLoggerMiddleware extends HttpLogger
{
    // Logs AFTER response is generated to include all context
}

The middleware is automatically registered as global middleware.

Writers

Context-Aware Log Writer

Custom log writer that includes Laravel's log context in HTTP logs:

class ContextAwareLogWriter implements LogWriter
{
    public function logRequest(Request $request): void
    {
        // Logs request with all context from Log::withContext()
    }
}

Usage Examples

Adding Custom Context

use Illuminate\Support\Facades\Log;

// Add context for all logs in this request
Log::withContext([
    'order_id' => $order->id,
    'payment_method' => 'stripe',
]);

// All subsequent logs will include this context
Log::info('Order processed');

Distributed Tracing

Send X-Correlation-ID header to trace requests across services:

curl -H "X-Correlation-ID: trace-abc-123" https://api.example.com/users

All logs for this request will include correlation_id: trace-abc-123.

Querying Logs

JSON Format:

# Find all requests for a specific user
cat storage/logs/laravel.log | jq 'select(.context.user_id == 42)'

# Find slow requests
cat storage/logs/laravel.log | jq 'select(.context.execution_time_ms > 1000)'

# Get all errors
cat storage/logs/laravel.log | jq 'select(.level == "ERROR")'

Hybrid Format:

# Find by request_id
grep "abc123" storage/logs/laravel.log

# Find by correlation_id
grep "trace-abc-123" storage/logs/laravel.log

License

MIT