README

A powerful, modular Laravel package for logging to Supabase (PostgreSQL) with advanced features including deduplication, occurrence tracking, smart tagging, and batch processing.

Features

🔄 Log Deduplication: Automatically deduplicates identical log messages using MD5 hashing
📊 Occurrence Tracking: Counts how many times each unique log has occurred
🏷️ Smart Auto-Tagging: Automatically tags logs based on routes, users, exceptions, and context
📦 Batch Processing: Efficiently processes logs in configurable batches to optimize API usage
🔄 Fallback Logging: Graceful error handling with automatic fallback to local file logging
⚡ High Performance: Built with performance in mind using efficient HTTP client with retry logic
🛠️ Management Commands: Artisan commands for testing, flushing, and tailing logs
🔒 Security: Configurable sensitive data sanitization
🎯 Production Ready: Robust error handling and comprehensive logging

Requirements

PHP 8.2 or higher
Laravel 10.x, 11.x, or 12.x
Supabase project with PostgreSQL database

Installation

Install the package via Composer:

composer require codexpedite/laravel-supabase-logger

Publish the configuration file:

php artisan vendor:publish --tag=supabase-logger-config

Database Setup

Create the laravel_logs table in your Supabase database:

CREATE TABLE laravel_logs (
    id BIGSERIAL PRIMARY KEY,
    hash VARCHAR(32) NOT NULL UNIQUE,
    level VARCHAR(20) NOT NULL,
    message TEXT NOT NULL,
    context JSONB,
    app VARCHAR(100) NOT NULL,
    environment VARCHAR(50) NOT NULL,
    occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
    first_occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
    last_occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
    occurrences INTEGER DEFAULT 1,
    tags TEXT[],
    status VARCHAR(20) DEFAULT 'new',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Create indexes for better performance
CREATE INDEX idx_laravel_logs_hash ON laravel_logs(hash);
CREATE INDEX idx_laravel_logs_level ON laravel_logs(level);
CREATE INDEX idx_laravel_logs_app_env ON laravel_logs(app, environment);
CREATE INDEX idx_laravel_logs_occurred_at ON laravel_logs(occurred_at);
CREATE INDEX idx_laravel_logs_status ON laravel_logs(status);
CREATE INDEX idx_laravel_logs_tags ON laravel_logs USING GIN(tags);

Configuration

Add your Supabase credentials to your .env file:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Add the Supabase logging channel to your config/logging.php:

'channels' => [
    // ... other channels

    'supabase' => [
        'driver' => 'custom',
        'via' => \Codexpedite\LaravelSupabaseLogger\SupabaseLoggerCreator::class,
        'level' => env('LOG_LEVEL', 'debug'),
    ],
],

Basic Usage

use Illuminate\Support\Facades\Log;

// Basic logging
Log::channel('supabase')->info('User logged in', ['user_id' => 123]);

// Error logging with context
Log::channel('supabase')->error('Payment failed', [
    'user_id' => 456,
    'order_id' => 789,
    'amount' => 99.99,
    'error' => $exception->getMessage()
]);

// Warning with tags
Log::channel('supabase')->warning('High memory usage detected', [
    'memory_usage' => '512MB',
    'tags' => ['performance', 'monitoring']
]);

Management Commands

Test Connection

Test your Supabase connection and configuration:

php artisan supabase-logger:test

View Recent Logs

Display recent logs from Supabase:

php artisan supabase-logger:tail

# With options
php artisan supabase-logger:tail --limit=100 --level=error

Force Flush Logs

Force flush any pending logs from memory buffer:

php artisan supabase-logger:flush

Configuration Options

The package provides extensive configuration options in config/supabase-logger.php:

return [
    // Supabase connection
    'supabase_url' => env('SUPABASE_URL'),
    'supabase_key' => env('SUPABASE_SERVICE_ROLE_KEY'),
    'table_name' => 'laravel_logs',

    // Performance settings
    'batch_size' => 50,
    'flush_interval' => 60, // seconds
    'timeout' => 30,
    'retry_attempts' => 3,
    'retry_delay' => 1000, // milliseconds

    // Auto-tagging
    'auto_tag_routes' => true,
    'auto_tag_users' => true,
    'auto_tag_ips' => true,
    'auto_tag_exceptions' => true,

    // Security
    'sanitize_sensitive_data' => true,
    'sensitive_keys' => ['password', 'token', 'secret', 'key'],

    // Fallback logging
    'fallback_to_file' => true,
    'fallback_path' => storage_path('logs/supabase-fallback.log'),
];

Features in Detail

Log Deduplication

The package automatically deduplicates identical log messages using MD5 hashing. When a duplicate log is detected:

The occurrences count is incremented
The last_occurred_at timestamp is updated
No new database row is created

Smart Auto-Tagging

Logs are automatically tagged based on:

Route: route:user.profile
User: user:123 (when authenticated)
Exception: exception:ValidationException
IP Address: ip:192.168.1.1
Custom Tags: Via context tags array

Batch Processing

Logs are collected in memory and sent in configurable batches to reduce API calls and improve performance.

Error Handling & Fallback

If Supabase is unavailable, the package will:

Attempt to retry the request (configurable retry attempts)
Fall back to local file logging if enabled
Log errors to Laravel's default log channel
Continue operation without breaking your application

Model Usage

Interact with logs using the provided Eloquent model:

use Codexpedite\LaravelSupabaseLogger\Models\LaravelLog;

// Find logs by criteria
$criticalLogs = LaravelLog::level('error')
    ->forApp('my-app')
    ->forEnvironment('production')
    ->recent(24) // last 24 hours
    ->get();

// Update log status
$log = LaravelLog::find($id);
$log->acknowledge(); // Mark as acknowledged
$log->resolve();     // Mark as resolved
$log->reopen();      // Reopen (mark as new)

Testing

# Test connection and configuration
php artisan supabase-logger:test

# Run package tests
composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover a security vulnerability, please send an e-mail to info@codexpedite.com.

Credits

License

The MIT License (MIT). Please see License File for more information.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Support

Made with ❤️ by CodeXpedite

codexpedite / laravel-supabase-logger

Maintainers

Details