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