README

Events logging for Laravel

This package provides logging for Laravel events (events must implements special interface).

Requirements

PHP >=8.0
Laravel >= 8.75

Install

Require this package with composer using the following command:

$ composer require feugene/events-log-laravel "^3.0"

Installed composer is required (how to install composer).

You need to fix the major version of package.

Setup

After an installation you should setup it. Minimal config is following changing in you ./config/logging.php file:

<?php

return [
    // ...

    'events_channel' => env('EVENTS_LOG_CHANNEL', 'stack'),

    // ...
];

Where stack - is a channel name, listed in the channels section of the same file. Without specifying this option, logging will be performed using the default channel.

You can override this option by adding to .env file the line: EVENTS_LOG_CHANNEL=%channel_name%.

For instance, if you need to log events in a different file in the Monolog format and additionally record to another file in the Logstash format, then the configuration may look like this:

<?php

return [

    'events_channel' => env('EVENTS_LOG_CHANNEL', 'events-stack'),

    // ...

    'channels' => [

        // ...

        'events-stack' => [
            'driver'   => 'stack',
            'channels' => ['events-monolog', 'events-logstash'],
        ],

        'events-monolog' => [
            'driver' => 'single',
            'path'   => storage_path('logs/laravel-events.log'),
            'level'  => 'debug',
        ],

        'events-logstash' => [
            'driver' => 'custom',
            'via'    => Feugene\EventsLogLaravel\Logging\EventsLogstashLogger::class,
            'path'   => storage_path('logs/logstash/laravel-events.log'),
            'level'  => 'debug',
        ],
    ],
];

To send logs in the Logstash format over UPD:

<?php

return [

    'default' => env('LOG_CHANNEL', 'app-logstash-udp'),

    'events_channel' => env('EVENTS_LOG_CHANNEL', 'events-logstash-udp'),

    // ...

    'channels' => [

        // ...

        'app-logstash-udp' => [
            'driver' => 'custom',
            'via'    => Feugene\EventsLogLaravel\Logging\DefaultUdpLogstashLogger::class,
            'host'   => env('LOGSTASH_UDP_HOST', 'logstash'),
            'port'   => (int) env('LOGSTASH_UDP_PORT', 4560),
            'level'  => 'debug',
        ],

        'events-logstash-udp' => [
            'driver' => 'custom',
            'via'    => Feugene\EventsLogLaravel\Logging\EventsUdpLogstashLogger::class,
            'host'   => env('LOGSTASH_UDP_HOST', 'logstash'),
            'port'   => (int) env('LOGSTASH_UDP_PORT', 4560),
            'level'  => 'debug',
        ],
    ],
];

You can read more about Laravel Logging at source.

Using

This package works as follows:

The ServiceProvider of this package registers its listener for the all events that occur in the application;
When an event is received, it checks the implementation of the event class for compliance with the ShouldBeLoggedContract interface;
If your event class implemented the ShouldBeLoggedContract interface, then using the specified in the file logging.php the logging channel, is being performed writing data;

Example of a logged event class:

<?php

class SomeApplicationEvent implements \Feugene\EventsLogLaravel\Contracts\ShouldBeLoggedContract
{
    /**
     * {@inheritdoc}
     */
    public function logLevel(): string
    {
        return 'info';
    }

    /**
     * {@inheritdoc}
     */
    public function logMessage(): string
    {
        return 'My log message';
    }

    /**
     * {@inheritdoc}
     */
    public function logEventExtraData(): array
    {
        return ['key' => 'any value'];
    }

    /**
     * {@inheritdoc}
     */
    public function eventType(): string
    {
        return 'default_event';
    }

    /**
     * {@inheritdoc}
     */
    public function eventSource(): string
    {
        return 'service_name';
    }
    
    public function eventTags(): array
    {
        return [];
    }
}

Now it is enough to call at any place in your application:

event(new SomeApplicationEvent());

And be sure that this event will be recorded in a log file.

Logging conditions

In some cases, it is necessary to add logging conditions to event. To do this, you can use the skipLogging method in the event class:

<?php

class YourEvent implements \Feugene\EventsLogLaravel\Contracts\ShouldBeLoggedContract
{
    /**
     * @var int
     */
    protected $value = 101;

    /**
     * {@inheritDoc}
     */
    public function logMessage(): string
    {
        return 'foo bar';
    }

    /**
     * {@inheritDoc}
     */
    public function skipLogging(): bool
    {
        return $this->value > 100;
    }

    // ...
}

Additional loggers

Together with this package, the following pre-configured loggers are available to you Feugene\EventsLogLaravel\Logging\...:

Logger's class	Appointment
`DefaultLogstashLogger`	Writes logs in the `logstash` format to a file, without modifying the body of the record (field `context`)
`EventsLogstashLogger`	Writes logs in the `logstash` format to a file, but the event-related data is placed in the `event` section
`DefaultUdpLogstashLogger`	Sends logs in the `logstash` format over UPD protocol, without modifying record's body (field `context`)
`EventsUdpLogstashLogger`	Writes logs in the `logstash` format to a file over UDP protocol, but the event-related data is placed in the `event` section

Testing

For package testing we use phpunit framework and docker-ce + docker-compose as develop environment. So, just write into your terminal after repository cloning:

$ make build
$ make latest # or 'make lowest'
$ make test

Changes log

Changes log can be found here.

Support

If you will find any package errors, please, make an issue in current repository.

License

This is open-sourced software licensed under the MIT License.

feugene / events-log-laravel

Maintainers

Details