README

Laravel Molog enables you to log messages and store metrics that are related to specific models. Akin to Spatie's Activity Log, but slightly more generic and with the possibility to associate metrics (Gauges) to messages or to any other Laravel model. The gauges factory class also provides builtin timer, incrementation and percentage methods.

In its simplest form:

$user = auth()->user();

$this->message('Mail sent!')->concerning($user)->save();

A slightly more advanced example — a message with metrics for a custom model:

$model = new Model();

$this->gauges()->startTimer();

$this->message()->notice('Import started...')->concerning($model)->save();

// processing...

$this->gauges()
    ->concerning($this->messages()->last())
    ->gauge('Files accepted', 16)
    ->gauge('Files refused', 2)
    ->stopTimer()
    ->save();

Good old exception logging:

$msg = $this->message(new Exception('Oops'))->setContext('example');

echo $msg;              // 2023-04-10 17:34:22.348 [debug] [example] Oops
echo $msg->subject;     // Oops
echo $msg->body;        // Stack trace ...

Features

Attach log messages and metrics (gauges) to models
Follows the PSR-3: Logger Interface
Exception logging
Start & stop timer metrics
Increment and decrement methods for gauges
Output messages and metrics to string
Generic HTTP controller

Requirements

Package	PHP	Laravel
`^2.0`	8.3, 8.4	12.x, 13.x
`^1.6`	7.4 – 8.2	7.x – 10.x

Version 2.0 raises the minimum requirements to PHP 8.3 and Laravel 12. Stay on ^1.6 if your application still runs on Laravel 11 or older.

Usage

Install with composer from packagist.org:

composer require dotburo/laravel-molog

The service provider is registered automatically through package auto-discovery, so there is nothing to add to bootstrap/providers.php.

The package's migration is loaded straight from the package, so php artisan migrate is enough to create the messages and gauges tables. Publish the files only if you want to own them:

# Both the config file and the migration
php artisan vendor:publish --provider="Dotburo\Molog\MologServiceProvider"

# Or selectively, by tag
php artisan vendor:publish --tag=laravel-molog-config
php artisan vendor:publish --tag=laravel-molog-migrate

php artisan migrate

Publish the config before migrating if you want the tables to use UUID primary keys (molog.primary_key_type).

Wherever you need logging, use the Logging trait. See the documentation for more usage examples.

class YourClass {

    use \Dotburo\Molog\Traits\Logging;
    
    protected function handle()
    {
        // This will store three messages
        $this->messages()
            ->message('Import process initiated', \Psr\Log\LogLevel::INFO)
            ->notice('Import process ongoing')
            ->warn('Import process aborted')
            ->save();
        
       // This will store one message with the subject 'aborted' and level critical
       $this->message()
            ->setContext('Import process')
            ->notice('ongoing')
            ->warn('aborted')
            ->setLevel(\Dotburo\Molog\MologConstants::CRITICAL)
            ->save();
        
        // Associate all subsequent metrics with the last message
        $this->gauges()->concerning($this->messages()->last());
        
        // Associate this metric of type INT with the first message
        $this->gauge('density', 5)->concerning($this->messages()->first())->save();
        
        // Add three metrics associated with the last message
        $this->gauges()
            ->gauge('density', 5.3567)  // updates the previous 'density' metric to the FLOAT value
            ->gauge('pressure', 2.35, 'bar', \Dotburo\Molog\MologConstants::GAUGE_INT_TYPE) // forcibly cast to FLOAT
            ->gauge('quality', 3)
            ->save();
    }
}

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

GNU General Public License (GPL). Please see the license file for more information.

dotburo / laravel-molog

Package info

Security

Fund package maintenance!

Statistics