Downloads
Stars
Version
This packages provides a full abstraction for Understand.io and provides extra features to improve Laravel's default logging capabilities. It is essentially a wrapper around Laravel's event handler to take full advantage of Understand.io's data aggregation and analysis capabilities.
composer require understand/understand-laravel
providers
array in config/app.php
Understand\UnderstandLaravel5\UnderstandLaravel5ServiceProvider::class,
.env
fileUNDERSTAND_ENABLED=true
UNDERSTAND_TOKEN=your-input-token-from-understand-io
// anywhere inside your Laravel app
\Log::error('Understand.io test error');
>= 5.0, < 5.1
) version, please read about - How to report Laravel 5.0 exceptions.By default, Laravel automatically stores its logs in storage/logs
. By using this package, your log data will also be sent to your Understand.io channel. This includes error and exception logs, as well as any log events that you have defined (for example, Log::info('my custom log')
).
\Log::info('my message', ['my_custom_field' => 'my data']);
By default, all errors and exceptions with code fragments and stack traces will be sent to Understand.io.
The following extra information will be collected:
Type | Default | Config Key | Config Options |
---|---|---|---|
SQL queries | Enabled | UNDERSTAND_SQL= |
true or false |
SQL query values/bindings | Disabled | UNDERSTAND_SQL_BINDINGS= |
true or false |
HTTP request query string data | Enabled | UNDERSTAND_QUERY_STRING= |
true or false |
HTTP request form or JSON data | Enabled | UNDERSTAND_POST_DATA= |
true or false |
Additionally, you can specify which HTTP request field values should not be sent to Understand.io. By default, the following field values will be hidden:
UNDERSTAND_HIDDEN_REQUEST_FIELDS=password,password_confirmation,access_token,secret_key,token,access_key
If you wish you can publish the configuration file and make desired adjustments. See Advanced configuration
By default each log event will be sent to Understand.io's api server directly after the event happens. If you generate a large number of logs, this could slow your app down and, in these scenarios, we recommend that you make use of an async handler. To do this, set the config parameter UNDERSTAND_HANDLER
to async
in your .env
file.
# Specify which handler to use - sync, queue or async.
#
# Note that the async handler will only work in systems where
# the CURL command line tool is installed
UNDERSTAND_HANDLER=async
The async handler is supported in most systems - the only requirement is that the CURL command line tool is installed and functioning correctly. To check whether CURL is available on your system, execute following command in your console:
curl -h
If you see instructions on how to use CURL then your system has the CURL binary installed and you can use the async
handler.
Keep in mind that Laravel allows you to specify different configuration values in different environments. You could, for example, use the async handler in production and the sync handler in development.
>= 5.0, < 5.1
) exceptionsLaravel's (>= 5.0, < 5.1
) exception logger doesn't use event dispatcher (https://github.com/laravel/framework/pull/10922) and that's why you need to add the following line to your Handler.php
file (otherwise Laravel's exceptions will not be sent Understand.io).
Open app/Exceptions/Handler.php
and put this line \UnderstandExceptionLogger::log($e)
inside report
method.
public function report(Exception $e)
{
\UnderstandExceptionLogger::log($e);
return parent::report($e);
}
php artisan vendor:publish --provider="Understand\UnderstandLaravel5\UnderstandLaravel5ServiceProvider"
To filter out specific log types a custom log filter can be provided.
Example filter class
// app/Logging/UnderstandLogFilter.php
<?php
declare(strict_types=1);
namespace App\Logging;
use Illuminate\Support\Str;
class UnderstandLogFilter
{
public function __invoke($level, $message, $context): bool
{
if ($level === 'warning' && Str::contains(strtolower($message), 'deprecated')) {
return true;
}
return false;
}
}
and then it can be configured in understand-laravel.php
<?php
// ...
// config/understand-laravel.php
'log_filter' => \App\Logging\UnderstandLogFilter::class,
The log_filter
config value must be a callable type:
The suggested way would be to create an invokable class since it's hard to serialise anonymous functions (Laravel config cache):
The log filter interface must be as follows: $callable($level, $message, $context)
.
The result of the filter must be a boolean value:
TRUE
, the log should be ignored and NOT delivered to Understand.ioFALSE
, the log should be delivered to Understand.ioThe ignored_logs
config value has higher precedence than log_filter
.
This package uses the json_encode function, which only supports UTF-8 data, and you should therefore ensure that all of your data is correctly encoded. In the event that your log data contains non UTF-8 strings, then the json_encode function will not be able to serialize the data.
http://php.net/manual/en/function.json-encode.php
The Laravel Understand.io service provider is open-sourced software licensed under the MIT license