Skip to content

Commit 748f64e

Browse files
aivisaivis
committed
Merge branch 'master' of github.com:understand/understand-laravel
2 parents 2fb9f49 + 2ed3855 commit 748f64e

File tree

1 file changed

+225
-0
lines changed

1 file changed

+225
-0
lines changed

‎README.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
## Laravel service provider for Understand.io
2+
3+
### Introduction
4+
5+
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.
6+
7+
### Quick start
8+
9+
1. Add this package to your composer.json and run `composer update`:
10+
11+
```php
12+
"understand/understand-laravel": "1.*"
13+
```
14+
15+
2. Add the ServiceProvider to the providers array in app/config/app.php
16+
17+
```php
18+
'Understand\UnderstandLaravel\UnderstandLaravelServiceProvider',
19+
```
20+
21+
3. Publish configuration file
22+
23+
```
24+
php artisan config:publish understand/understand-laravel
25+
```
26+
27+
4. Set your input key in config file
28+
29+
```php
30+
'token' => 'my-input-token'
31+
```
32+
33+
### How to send events/logs
34+
35+
#### Laravel logs
36+
By default, Laravel automatically stores its logs in ```app/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')```).
37+
38+
39+
#### Eloquent model logs
40+
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.
41+
42+
By default model logs are disabled. To enable model logs, you can set the config value to `true`:
43+
44+
```php
45+
'eloquent_logs' => true,
46+
```
47+
48+
### Additional meta data (field providers)
49+
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.
50+
51+
```php
52+
/**
53+
* Specify additional field providers for each log
54+
* E.g. sha1 version session_id will be appended to each "Log::info('event')"
55+
*/
56+
'additional' => [
57+
'model_log' => [
58+
'session_id' => 'UnderstandFieldProvider::getSessionId',
59+
'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
60+
'user_id' => 'UnderstandFieldProvider::getUserId',
61+
'env' => 'UnderstandFieldProvider::getEnvironment',
62+
'client_ip' => 'UnderstandFieldProvider::getClientIp',
63+
],
64+
'laravel_log' => [
65+
'session_id' => 'UnderstandFieldProvider::getSessionId',
66+
'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
67+
'user_id' => 'UnderstandFieldProvider::getUserId',
68+
'env' => 'UnderstandFieldProvider::getEnvironment',
69+
],
70+
'exception_log' => [
71+
'session_id' => 'UnderstandFieldProvider::getSessionId',
72+
'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
73+
'user_id' => 'UnderstandFieldProvider::getUserId',
74+
'env' => 'UnderstandFieldProvider::getEnvironment',
75+
'url' => 'UnderstandFieldProvider::getUrl',
76+
'method' => 'UnderstandFieldProvider::getRequestMethod',
77+
'client_id' => 'UnderstandFieldProvider::getClientIp',
78+
'user_agent' => 'UnderstandFieldProvider::getClientUserAgent'
79+
]
80+
]
81+
```
82+
83+
The Understand.io service provider contains a powerful field provider class which provides default providers, and you can create or extend new providers.
84+
85+
```php
86+
dd(UnderstandFieldProvider::getSessionId());
87+
// output: c624e355b143fc050ac427a0de9b64eaffedd606
88+
```
89+
90+
#### Default field providers
91+
The following field providers are included in this package:
92+
93+
- `getSessionId` - return sha1 version of session id
94+
- `getRouteName` - return current route name (e.g. `clients.index`).
95+
- `getUrl` - return current url (e.g. `/my/path?with=querystring`).
96+
- `getRequestMethod` - return request method (e.g. `POST`).
97+
- `getServerIp` - return server IP.
98+
- `getClientIp` - return client IP.
99+
- `getClientUserAgent` - return client's user agent.
100+
- `getEnvironment` - return Laravel environment (e.g. `production`).
101+
- `getProcessIdentifier` - return unique token which is unique for every request. This allows you to easily group all events which happen in a single request.
102+
- `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.
103+
104+
#### How to extend create your own methods or extend the field providers
105+
```php
106+
107+
UnderstandFieldProvider::extend('getMyCustomValue', function()
108+
{
109+
return 'my custom value';
110+
});
111+
112+
UnderstandFieldProvider::extend('getCurrentTemperature', function()
113+
{
114+
return \My\Temperature\Provider::getRoomTemperature();
115+
});
116+
117+
```
118+
119+
#### Example
120+
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:
121+
122+
```php
123+
'laravel_log' => [
124+
'meta' => [
125+
...
126+
'UnderstandFieldProvider::getCurrentTemperature',
127+
...
128+
]
129+
],
130+
```
131+
132+
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:
133+
134+
```json
135+
136+
{
137+
"message": "my_custom_event",
138+
"custom_temperature":"23"
139+
}
140+
```
141+
142+
143+
### How to send data asynchnoously
144+
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 queue handler. To do this, change the config parameter `handler` to `queue` and Laravel queues will be automatically used. 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.
145+
146+
```php
147+
/**
148+
* Specify which handler to use (sync|queue)
149+
*/
150+
'handler' => 'queue',
151+
```
152+
153+
### Configuration
154+
155+
```php
156+
157+
<?php
158+
159+
return [
160+
161+
/**
162+
* Input key
163+
*/
164+
'token' => 'd9048b69-15fe-4da1-a623-d83cdc87e887',
165+
166+
/**
167+
* Api server endpoint for http transport
168+
*/
169+
'url' => 'localhost:3000',
170+
171+
/**
172+
* Specifies whether logger should throw an exception of issues detected
173+
*/
174+
'silent' => false,
175+
176+
/**
177+
* Specify which handler to use (sync|queue)
178+
*/
179+
'handler' => 'sync',
180+
181+
/**
182+
* Send all laravel logs to understnad.io (e.g. "Log::info('my event')")
183+
*/
184+
'laravel_logs' => true,
185+
186+
/**
187+
* Send all Eloquent model events and changes to understand.io
188+
*/
189+
'eloquent_logs' => false,
190+
191+
/**
192+
* Specify additional field providers for each log
193+
* E.g. sha1 version session_id will be appended to each "Log::info('event')"
194+
*/
195+
'additional' => [
196+
'model_log' => [
197+
'session_id' => 'UnderstandFieldProvider::getSessionId',
198+
'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
199+
'user_id' => 'UnderstandFieldProvider::getUserId',
200+
'env' => 'UnderstandFieldProvider::getEnvironment',
201+
'client_ip' => 'UnderstandFieldProvider::getClientIp',
202+
],
203+
'laravel_log' => [
204+
'session_id' => 'UnderstandFieldProvider::getSessionId',
205+
'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
206+
'user_id' => 'UnderstandFieldProvider::getUserId',
207+
'env' => 'UnderstandFieldProvider::getEnvironment',
208+
],
209+
'exception_log' => [
210+
'session_id' => 'UnderstandFieldProvider::getSessionId',
211+
'request_id' => 'UnderstandFieldProvider::getProcessIdentifier',
212+
'user_id' => 'UnderstandFieldProvider::getUserId',
213+
'env' => 'UnderstandFieldProvider::getEnvironment',
214+
'url' => 'UnderstandFieldProvider::getUrl',
215+
'method' => 'UnderstandFieldProvider::getRequestMethod',
216+
'client_id' => 'UnderstandFieldProvider::getClientIp',
217+
'user_agent' => 'UnderstandFieldProvider::getClientUserAgent'
218+
]
219+
]
220+
];
221+
```
222+
223+
### License
224+
225+
The Laravel Understand.io service provider is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)

0 commit comments

Comments
 (0)