Package Data | |
---|---|
Maintainer Username: | understand |
Maintainer Contact: | aivis.silins@gmail.com (Aivis Silins) |
Package Create Date: | 2015-10-30 |
Package Last Update: | 2018-03-07 |
Language: | PHP |
License: | MIT |
Last Refreshed: | 2024-12-19 03:16:28 |
Package Statistics | |
---|---|
Total Downloads: | 665 |
Monthly Downloads: | 0 |
Daily Downloads: | 0 |
Total Stars: | 6 |
Total Watchers: | 4 |
Total Forks: | 2 |
Total Open Issues: | 0 |
You may also be interested in our Laravel 4, Laravel 5 service provider or Monolog Understand.io handler
This packages provides a full abstraction for Understand.io and provides extra features to improve Lumen's default logging capabilities. It is essentially a wrapper around our Understand Monolog handler to take full advantage of Understand.io's data aggregation and analysis capabilities.
Add this package to your project via composer:
composer require understand/understand-lumen
In bootstrap/app.php
enable Dotenv
(around line 5) AND $app->withFacades();
(around line 22):
Dotenv::load(__DIR__.'/../'); // around line 5
...
$app->withFacades(); // around line 22
In bootstrap/app.php
register the UnderstandLumenServiceProvider:
$app->register(Understand\UnderstandLumen\UnderstandLumenServiceProvider::class);
Create a new file as config/understand_lumen.php
(note that you may need to create the config
directory) with the following contents:
<?php
return [
/**
* Specify which handler to use - sync or async.
*
* Note that the async handler will only work in systems where
* the CURL command line tool is installed
*/
'handler' => env('UNDERSTAND_HANDLER', 'sync'),
/**
* Your input token from Understand.io
*/
'token' => env('UNDERSTAND_INPUT_KEY'),
/**
* Specifies whether logger should throw an exception of issues detected
*/
'silent' => env('UNDERSTAND_SILENT', true),
/**
* Specify additional field providers for each log
* E.g. sha1 version session_id will be appended to each "Log::info('event')"
*/
'meta' => [
'user_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUserId',
'session_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getSessionId',
'request_id' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getProcessIdentifier',
'url'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUrl',
'client_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientIp',
//'server_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getServerIp',
//'user_agent' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientUserAgent',
//'environment' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getEnvironment',
//'request_method'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getRequestMethod',
],
];
Set your input key (from Understand.io) in your .env
file as UNDERSTAND_INPUT_KEY
UNDERSTAND_INPUT_KEY=your-input-key-from-understand
Open app/Exceptions/Handler.php
and adjust the report
method:
public function report(Exception $e)
{
$encoder = new \UnderstandMonolog\Encoder\ExceptionEncoder();
app('Psr\Log\LoggerInterface')->error($e->getMessage(), $encoder->exceptionToArray($e));
}
Send your first event
$app->get('/', function () use ($app) {
Log::info('test log 123');
return $app->welcome();
});
You may wish to capture additional meta data with each event. For example, it can be very useful to capture the request url with exceptions, or perhaps you want to capture the current user's ID. To do this, you can specify custom field providers via the config.
/**
* Specify additional field providers for each log
* E.g. sha1 version session_id will be appended to each "Log::info('event')"
*/
'meta' => [
'user_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUserId',
'session_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getSessionId',
'request_id' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getProcessIdentifier',
'url'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUrl',
'client_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientIp',
//'server_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getServerIp',
//'user_agent' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientUserAgent',
//'environment' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getEnvironment',
//'request_method'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getRequestMethod',
],
The Understand.io service provider contains a powerful field provider class which provides default providers, and you can create or extend new providers.
dd(Understand\UnderstandLumen\UnderstandFieldProviderFacade::getSessionId());
// output: c624e355b143fc050ac427a0de9b64eaffedd606
The following field providers are included in this package:
getSessionId
- return sha1 version of session idgetUrl
- return current url (e.g. /my/path?with=querystring
).getRequestMethod
- return request method (e.g. POST
).getServerIp
- return server IP.getClientIp
- return client IP.getClientUserAgent
- return client's user agent.getEnvironment
- return Lumen environment (e.g. production
).getProcessIdentifier
- return unique token which is unique for every request. This allows you to easily group all events which happen in a single request.getUserId
- return current user id. This is only available if you make sure of the default Laravel Lumen auth or the cartalyst/sentry package. Alternatively, if you make use of a different auth package, then you can extend the getUserId
field provider and implement your own logic.Understand\UnderstandLumen\UnderstandFieldProviderFacade::extend('getMyCustomValue', function()
{
return 'my custom value';
});
dd(Understand\UnderstandLumen\UnderstandFieldProviderFacade::getMyCustomValue());
Lets assume that you have defined a custom field provider called getMyCustomValue
(as above). You should then add this to your config file as follows:
'meta' => [
...
'custom_value' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getMyCustomValue',
...
]
This additional meta data will then be automatically appended to all of your Lumen log events (Log::info('my_custom_event')
), and will appear as follows:
{
"message": "my_custom_event",
"custom_value":"my custom value"
}
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 a async handler. To do this, change the config parameter handler
to async
.
/**
* Specify which handler to use - sync or async.
*
* Note that the async handler will only work in systems where
* the CURL command line tool is installed
*/
'handler' => 'async',
The async handler is supported in most of the systems - the only requirement is that 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 Lumen 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.
return [
/**
* Specify which handler to use - sync or async.
*
* Note that the async handler will only work in systems where
* the CURL command line tool is installed
*/
'handler' => env('UNDERSTAND_HANDLER', 'sync'),
/**
* Your input token from Understand.io
*/
'token' => env('UNDERSTAND_INPUT_KEY'),
/**
* Specifies whether logger should throw an exception of issues detected
*/
'silent' => env('UNDERSTAND_SILENT', true),
/**
* Specify additional field providers for each log
* E.g. sha1 version session_id will be appended to each "Log::info('event')"
*/
'meta' => [
'user_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUserId',
'session_id'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getSessionId',
'request_id' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getProcessIdentifier',
'url'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getUrl',
'client_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientIp',
//'server_ip'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getServerIp',
//'user_agent' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getClientUserAgent',
//'environment' => 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getEnvironment',
//'request_method'=> 'Understand\UnderstandLumen\UnderstandFieldProviderFacade::getRequestMethod',
],
];
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 Lumen Understand.io service provider is open-sourced software licensed under the MIT license