You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> You may also be interested in our [Laravel 4](https://github.com/understand/understand-laravel), [Laravel Lumen service provider](https://github.com/understand/understand-lumen) or [Monolog Understand.io handler](https://github.com/understand/understand-monolog)
11
8
9
+
-[Quick start](#quick-start)
10
+
-[Upgrading To Version 2](#upgrading-to-version-2-of-the-service-provider)
12
11
13
12
### Introduction
14
13
15
14
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.
16
15
17
16
### Quick start
18
17
19
-
1. Add package to your project.
20
-
21
-
```
22
-
composer require understand/understand-laravel5
23
-
```
24
-
25
-
2. Add the ServiceProvider to the providers array in ```config/app.php```
- We recommend that you make use of a async handler - [How to send data asynchronously](#how-to-send-data-asynchronously)
45
-
- If you are using Laravel 5.0 (`>= 5.0, < 5.1`) version, please read about - [How to report Laravel 5.0 exceptions](#how-to-report-laravel-50--50--51-exceptions).
46
-
- For advanced configuration please read about - [Advanced configuration](#advanced-configuration)
47
-
48
-
49
-
### How to send events/logs
50
-
51
-
#### Laravel logs
52
-
By default, Laravel automatically stores its logs in ```storage/logs```. By using this package, your logs can 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')```).
By default, All exceptions will be sent to Understand.io service.
62
-
63
-
#### Eloquent model logs
64
-
Eloquent model logs are generated whenever one of the `created`, `updated`, `deleted` or `restored` Eloquent events is fired. This allows you to automatically track all changes to your models and will contain a current model diff (`$model->getDirty()`), the type of event (created, updated, etc) and additonal meta data (user_id, session_id, etc). This means that all model events will be transformed into a log event which will be sent to Understand.io.
65
-
66
-
By default model logs are disabled. To enable model logs, you can set the config value to `true`:
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.
76
-
24
+
2. Add the ServiceProvider to the `providers` array in `config/app.php`
25
+
77
26
```php
78
-
/**
79
-
* Specify additional field providers for each log
80
-
* E.g. sha1 version session_id will be appended to each "Log::info('event')"
The Understand.io service provider contains a powerful field provider class which provides default providers, and you can create or extend new providers.
119
-
30
+
3. Set your Understand.io input token in your `.env` file
-`getProcessIdentifier` - return unique token which is unique for every request. This allows you to easily group all events which happen in a single request.
137
-
-`getUserId` - return current user id. This is only available if you make sure of the default Laravel 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.
138
-
139
-
#### How to extend create your own methods or extend the field providers
Lets assume that you have defined a custom field provider called `getCurrentTemperature` (as above). You should then add this to your config file as follows:
44
+
- We recommend that you make use of a async handler - [How to send data asynchronously](#how-to-send-data-asynchronously)
45
+
- If you are using Laravel 5.0 (`>= 5.0, < 5.1`) version, please read about - [How to report Laravel 5.0 exceptions](#how-to-report-laravel-50--50--51-exceptions).
46
+
- For advanced configuration please read about - [Advanced configuration](#advanced-configuration)
This additional meta data will then be automatically appended to all of your Laravel log events (`Log::info('my_custom_event')`), and will appear as follows:
49
+
### How to send events/logs
168
50
169
-
```json
51
+
#### Laravel logs
52
+
By default, Laravel automatically stores its [logs](http://laravel.com/docs/errors#logging) 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')`).
By default, all errors and exceptions with code fragments and stack traces will be sent to Understand.io.
176
59
60
+
In addition, all SQL queries that were executed before each exception or error will also be sent to Understand.io. Note that for security and privacy reasons, we do NOT substitute query parameters. The SQL logging feature can be disabled if you wish - please see [Advanced configuration](#advanced-configuration).
177
61
178
62
### How to send data asynchronously
179
63
180
64
##### Async handler
181
-
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, set the config parameter `UNDERSTAND_HANDLER` to `async` in your `.env` file.
65
+
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.
182
66
183
67
```php
184
68
# Specify which handler to use - sync, queue or async.
@@ -188,7 +72,7 @@ By default each log event will be sent to Understand.io's api server directly af
188
72
UNDERSTAND_HANDLER=async
189
73
```
190
74
191
-
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:
75
+
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:
192
76
193
77
```
194
78
curl -h
@@ -198,14 +82,11 @@ If you see instructions on how to use CURL then your system has the CURL binary
198
82
199
83
> 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.
200
84
201
-
##### Laravel queue handler
202
-
Although we generally recommend using the async handler, making use of queues is another another option. Bear in mind that by the default Laravel queue is `sync`, so you will still need to configure your queues properly using something like iron.io or Amazon SQS. See http://laravel.com/docs/queues for more information.
203
-
204
85
### How to report Laravel 5.0 (`>= 5.0, < 5.1`) exceptions
205
86
206
87
Laravel'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).
207
88
208
-
- Open ```app/Exceptions/Handler.php``` and put this line ```\UnderstandExceptionLogger::log($e)``` inside ```report``` method.
89
+
- Open `app/Exceptions/Handler.php` and put this line `\UnderstandExceptionLogger::log($e)` inside `report` method.
### Upgrading To Version 2 of the Service Provider
110
+
111
+
1. Update your `package.json` file, change the version of `understand/understand-laravel5` package and run `composer update understand/understand-laravel5`.
112
+
```json
113
+
"understand/understand-laravel5": "^2.0",
114
+
```
115
+
116
+
2. Add the following configuration variable to your `.env` file.
232
117
```php
233
-
return [
234
-
/**
235
-
* Input key
236
-
*/
237
-
'token' => env('UNDERSTAND_TOKEN'),
238
-
239
-
/**
240
-
* Specifies whether logger should throw an exception of issues detected
241
-
*/
242
-
'silent' => true,
243
-
244
-
/**
245
-
* Specify which handler to use - sync, queue or async.
246
-
*
247
-
* Note that the async handler will only work in systems where
3. If you previously created a `understand-laravel.php` config file in your `config` directory, please delete it and follow [Advanced configuration](#advanced-configuration) steps to publish a new version if necessary.
122
+
294
123
### Requirements
295
124
##### UTF-8
296
125
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.
0 commit comments