avto-dev/events-log-laravel

Events logging for laravel applications

v3.4.1 2023-05-15 04:44 UTC

This package is auto-updated.

Last update: 2024-03-15 06:27:14 UTC


README

Laravel

Events logging for Laravel

Version PHP Version Build Status Coverage Downloads count License

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\...:

Класс логгера Назначение
DefaultLogstashLogger Пишет лог-записи в формате logstash в файл, не видоизменяя тело записи (поле context не изменяется)
EventsLogstashLogger Пишет лог-записи в формате logstash в файл, но данные связанные с событиями помещаются в секцию event
DefaultUdpLogstashLogger Отправляет лог-записи в формате logstash по UDP протоколу, не видоизменяя тело записи (поле context не изменяется)
EventsUdpLogstashLogger Пишет лог-записи в формате logstash по UDP протоколу, но данные связанные с событиями помещаются в секцию event

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

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

Release date Commits since latest release

Changes log can be found here.

Support

Issues Issues

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.