README

Events logging for Laravel

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

Install

Require this package with composer using the following command:

$ composer require avto-dev/events-log-laravel "^3.0"

Installed composer is required (how to install composer).

You need to fix the major version of package.

Setup

После установки пакета вам необходимо произвести его настройку. Минимальной конфигурацией является добавление в ваш файл ./config/logging.php значения:

<?php

return [
    // ...

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

    // ...
];

Где stack - это имя одного из каналов, перечисленного в секции channels этого же файла. Без указания данной опции логгирование будет производиться с использованием канала по умолчанию.

Переопределить данную опцию вы сможете добавив в .env файл вашего приложения строку EVENTS_LOG_CHANNEL=%channel_name%.

Например, если вам необходимо производить логгирование событий в отдельный файл в формате Monolog и дополнительно вести запись в другой файл в формате Logstash, то конфигурация может иметь следующий вид:

<?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'    => AvtoDev\EventsLogLaravel\Logging\EventsLogstashLogger::class,
            'path'   => storage_path('logs/logstash/laravel-events.log'),
            'level'  => 'debug',
        ],
    ],
];

Для отправки логов в формате Logstash по UDP протоколу:

<?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'    => AvtoDev\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'    => AvtoDev\EventsLogLaravel\Logging\EventsUdpLogstashLogger::class,
            'host'   => env('LOGSTASH_UDP_HOST', 'logstash'),
            'port'   => (int) env('LOGSTASH_UDP_PORT', 4560),
            'level'  => 'debug',
        ],
    ],
];

Более подробно о настройке логгирования вы можете прочитать по этой ссылке.

Использование

Данный пакет работает следующий образом:

• Сервис-провайдер данного пакета регистрирует свой "слушатель" на все события, что происходят в приложении;
• При получении события он проверяет реализацию класса события интерфейса ShouldBeLoggedContract;
• Если предыдущее условие выполняется - то используя указанный в файле logging.php канал логгирования производится запись данных которые возвращают методы, описанные в интерфейсе ShouldBeLoggedContract.

Пример класса логгируемого события:

<?php

class SomeApplicationEvent implements \AvtoDev\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';
    }

    /**
     * {@inheritdoc}
     */
    public function skipLogging() : bool
    {
        return false;
    }
}

Теперь достаточно в произвольном месте вашего приложения вызвать:

event(new SomeApplicationEvent);

И быть уверенным в том, что данное событие будет записано в лог-файл. О том, как работают события (events) в Laravel вы можете прочитать по этой ссылке.

Условия логирования

В некоторых случаях необходимо добавить условия логгирования события. Для этого вы можете использовать в классе события метод skipLogging:

<?php

class YourEvent extends AvtoDev\EventsLogLaravel\Events\AbstractLoggableEvent
{
    /**
     * @var int
     */
    protected $value = 101;

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

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

    // ...
}

Дополнительные логгеры

Вместе с данным пакетом вам доступны следующие пред-настроенные логгеры AvtoDev\EventsLogLaravel\Logging\...:

Более подробно о них смотрите исходный код

Testing

For package testing we use phpunit framework and docker with compose plugin 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.