avto-dev/events-log-laravel

Events logging for laravel applications

, _(*1)

Events logging for Laravel

![PHP Version][badge_php_version] ![Coverage][badge_coverage] ![License][badge_license], _(*2)

This package provides logging for Laravel events (events must implements special interface)., _(*3)

Install

Require this package with composer using the following command:, _(*4)

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

Installed composer is required (how to install composer)., _(*5)

You need to fix the major version of package., _(*6)

Setup

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

<?php

return [
    // ...

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

    // ...
];

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

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

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

<?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 протоколу:, _(*11)

<?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',
        ],
    ],
];

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

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

Данный пакет работает следующий образом:, _(*13)

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

Пример класса логгируемого события:, _(*14)

<?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;
    }
}

Теперь достаточно в произвольном месте вашего приложения вызвать:, _(*15)

event(new SomeApplicationEvent);

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

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

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

<?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\...:, _(*18)

Более подробно о них смотрите исходный код, _(*19)

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:, _(*20)

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

Changes log

![Commits since latest release][badge_commits_since_release], _(*21)

Changes log can be found here., _(*22)

Support

![Issues][badge_pulls], _(*23)

If you will find any package errors, please, make an issue in current repository., _(*24)

License

This is open-sourced software licensed under the MIT License., _(*25)