Skip to content

Commit cb184d3

Browse files
kitloongkitloong
committed
Updated README.md
1 parent 40a9587 commit cb184d3

File tree

1 file changed

+129
-113
lines changed

1 file changed

+129
-113
lines changed

‎README.md‎

Lines changed: 129 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44
[![Latest Stable Version](https://poser.pugx.org/kitloong/laravel-app-logger/v/stable.png)](https://packagist.org/packages/kitloong/laravel-app-logger)
55
[![License](https://poser.pugx.org/kitloong/laravel-app-logger/license.png)](https://packagist.org/packages/kitloong/laravel-app-logger)
66

7-
This package provides middleware that generate **http request** and **performance** logs for you application.
7+
This package provides middleware that generates **HTTP request** and **performance** logs from incoming requests.
88

9-
This package also provides Database **query log** to log all executed queries by your application.
9+
This package also provides a Database **query log** to log all executed queries in your application.
1010

1111
## Installation
1212

@@ -16,19 +16,17 @@ composer require kitloong/laravel-app-logger
1616

1717
## Usage
1818

19-
To start using **http request** and **performance** logger please add package's middleware in your `app/Http/Kernel.php` or routes.
19+
To start using **HTTP request** and **performance** logger please add the package's middleware in your `app/Http/Kernel.php` or routes.
2020

2121
```
2222
\KitLoong\AppLogger\Middlewares\AppLogger::class
2323
```
2424

25-
No code modification needed to use **DB query log**, you only need to enable it through `.env`.
25+
No code modification needed to use the Database **query log**, you only need to enable it through `.env`.
2626

27-
## Configuration
28-
29-
By default, **Http request** and **performance** are enabled while **query log** is disabled.
27+
By default, **HTTP request** and **performance** are enabled while the **query log** is disabled.
3028

31-
However, you could change each setting respectively by difference environment.
29+
However, you could change each setting respectively to a different environment.
3230

3331
```dotenv
3432
# By default
@@ -38,130 +36,148 @@ RUN_PERFORMANCE_LOG=true
3836
RUN_QUERY_LOG=false
3937
```
4038

41-
You could also publish config file to change more configuration or even use your own implementation
39+
## Log format
40+
41+
### Http request log
42+
43+
```log
44+
[2021-01-10 23:35:27] local.INFO: 2725ffb10adeae3f POST /path - Body: {"test":true} - Headers: {"cookie":["Phpstorm-12345"],"accept-language":["en-GB"]} - Files: uploaded.txt
45+
```
46+
47+
### Performance log
48+
49+
```log
50+
[2021-01-10 23:35:27] local.INFO: 2725ffb10adeae3f POST /path - Time: 55.82 ms - Memory: 22.12 MiB
51+
```
52+
53+
### Query log
54+
55+
```log
56+
[2021-01-10 23:35:27] local.INFO: Took: 2.45 ms mysql Sql: select * from `users` where `id` = 1
57+
```
58+
59+
## What's more
60+
61+
This package uses https://github.com/spatie/laravel-http-logger as the base for the **HTTP request** log, as well as the code design pattern.
62+
63+
It is common to receive tons of incoming requests in a real-life production application.
64+
65+
To ease for analysis, a unique string is embedded into **HTTP request** and **performance** log to indicate both log entries are related.
66+
67+
```log
68+
# HTTP request, unique: 2725ffb10adeae3f
69+
[2021-01-10 23:35:25] local.INFO: 2725ffb10adeae3f GET /path - Body ...
70+
71+
# Performance, unique: 2725ffb10adeae3f
72+
[2021-01-10 23:35:27] local.INFO: 2725ffb10adeae3f GET /path - Time: 55.82 ms - Memory: 5.12 MiB
73+
```
74+
75+
If you found any high memory usage or slow requests you could easily grep request log by the unique string for more information.
76+
77+
## Configuration
78+
79+
You could also publish the config file to change more configuration or even use your own implementation:
4280

4381
```bash
4482
php artisan vendor:publish --provider="KitLoong\AppLogger\AppLoggerServiceProvider" --tag=config
4583
```
4684

47-
This is content of config file
85+
You could check the content of the config file [here](config/app-logger.php).
4886

49-
```
50-
[
51-
'http' => [
52-
'enabled' => env('RUN_HTTP_LOG', true),
53-
54-
/*
55-
* The log profile which determines whether a request should be logged.
56-
* It should implement `HttpLogProfile`.
57-
*/
58-
'log_profile' => \KitLoong\AppLogger\HttpLog\LogProfile::class,
59-
60-
/*
61-
* The log writer used to write the request to a log.
62-
* It should implement `HttpLogWriter`.
63-
*/
64-
'log_writer' => \KitLoong\AppLogger\HttpLog\LogWriter::class,
65-
66-
/*
67-
* If you are using default `HttpLogProfile` provided by the package,
68-
* you could define which HTTP methods should be logged.
69-
*/
70-
'should_log' => [
71-
\Illuminate\Http\Request::METHOD_POST,
72-
\Illuminate\Http\Request::METHOD_PUT,
73-
\Illuminate\Http\Request::METHOD_PATCH,
74-
\Illuminate\Http\Request::METHOD_DELETE,
75-
],
76-
77-
/*
78-
* Filter out body fields which will never be logged.
79-
*/
80-
'except' => [
81-
'password',
82-
'password_confirmation',
83-
],
84-
85-
/*
86-
* Log channel name define in config/logging.php
87-
* null value to use default channel.
88-
*/
89-
'channel' => null,
90-
],
87+
### Config: Logging channel
88+
89+
By default, Laravel App Logger writes logs into your default logging channel.
90+
91+
However, you may implement a new logging channel in Laravel `config/logging.php`, and overwrite the `channel` in the published config file.
92+
93+
An example is written for a better explanation.
94+
95+
In Laravel `config/logging.php`:
9196

97+
```bash
98+
99+
'channels' => [
100+
'request' => [
101+
'driver' => 'daily',
102+
'path' => storage_path('logs/request.log'),
103+
'level' => 'debug',
104+
'days' => 14,
105+
],
106+
92107
'performance' => [
93-
'enabled' => env('RUN_PERFORMANCE_LOG', true),
94-
95-
/*
96-
* The log profile which determines whether a request should be logged.
97-
* It should implement `PerformanceLogProfile`.
98-
*/
99-
'log_profile' => \KitLoong\AppLogger\PerformanceLog\LogProfile::class,
100-
101-
/*
102-
* The log writer used to write the request to a log.
103-
* It should implement `PerformanceLogWriter`.
104-
*/
105-
'log_writer' => \KitLoong\AppLogger\PerformanceLog\LogWriter::class,
106-
107-
/*
108-
* If you are using default `PerformanceLogProfile` provided by the package,
109-
* you could define which HTTP methods should be logged.
110-
*/
111-
'should_log' => [
112-
\Illuminate\Http\Request::METHOD_GET,
113-
\Illuminate\Http\Request::METHOD_POST,
114-
\Illuminate\Http\Request::METHOD_PUT,
115-
\Illuminate\Http\Request::METHOD_PATCH,
116-
\Illuminate\Http\Request::METHOD_DELETE,
117-
],
118-
119-
/*
120-
* Log channel name define in config/logging.php
121-
* null value to use default channel.
122-
*/
123-
'channel' => null,
108+
'driver' => 'daily',
109+
'path' => storage_path('logs/performance.log'),
110+
'level' => 'debug',
111+
'days' => 14,
124112
],
125-
113+
126114
'query' => [
127-
'enabled' => env('RUN_QUERY_LOG', false),
128-
129-
/*
130-
* The log profile which determines whether query should be logged.
131-
* It should implement `QueryLogProfile`.
132-
*/
133-
'log_profile' => \KitLoong\AppLogger\QueryLog\LogProfile::class,
134-
135-
/*
136-
* The log writer used to write the query to a log.
137-
* It should implement `QueryLogWriter`.
138-
*/
139-
'log_writer' => \KitLoong\AppLogger\QueryLog\LogWriter::class,
140-
141-
/*
142-
* Log channel name define in config/logging.php
143-
* null value to use default channel.
144-
*/
145-
'channel' => null,
115+
'driver' => 'daily',
116+
'path' => storage_path('logs/query.log'),
117+
'level' => 'debug',
118+
'days' => 14,
146119
],
147-
];
120+
]
148121
```
149122

150-
This package used https://github.com/spatie/laravel-http-logger as base for **http request** log, as well as the code design pattern.
123+
In `config/app-logger.php`:
151124

152-
We could receive tons of access in a real life production application.
125+
```bash
126+
'http' => [
127+
...
128+
'channel' => 'request'
129+
],
130+
'performance' => [
131+
...
132+
'channel' => 'performance'
133+
],
134+
'query' => [
135+
...
136+
'channel' => 'query'
137+
]
138+
```
153139

154-
In order to ease for analyze, a unique string is embedded into **http request** and **performance** log to indicate both log entries are related.
140+
### Config: Implement own logger
155141

156-
```bash
157-
# Http request, unique: 2725ffb10adeae3f
158-
[2021-01-10 23:35:25] local.INFO: 2725ffb10adeae3f GET /path - Body ...
142+
You could even write your own logger implementation and overwrite it in the config file.
159143

160-
# Performance, unique: 2725ffb10adeae3f
161-
[2021-01-10 23:35:27] local.INFO: 2725ffb10adeae3f GET /path - Time: 55 - Memory: 5
144+
Here is the code snippet of **HTTP request**:
145+
146+
```bash
147+
/*
148+
* The log profile which determines whether a request should be logged.
149+
* It should implement `HttpLogProfile`.
150+
*/
151+
'log_profile' => \KitLoong\AppLogger\HttpLog\LogProfile::class,
152+
153+
/*
154+
* The log writer used to write the request to a log.
155+
* It should implement `HttpLogWriter`.
156+
*/
157+
'log_writer' => \KitLoong\AppLogger\HttpLog\LogWriter::class,
162158
```
163159

164-
If you found any high memory usage or slow requests you could easily grep request log by the unique string for more information.
160+
You could find a similar configuration in the `performance` and `query` section.
161+
162+
When you write your own `log_profile`, you must implement each loggers' own `LogProfile` interface.
163+
164+
|Logger|Interface|
165+
|---|---|
166+
|http|\KitLoong\AppLogger\HttpLog\HttpLogProfile|
167+
|performance|\KitLoong\AppLogger\PerformanceLog\PerformanceLogProfile|
168+
|query|\KitLoong\AppLogger\QueryLog\QueryLogProfile|
169+
170+
The interface requires `shouldLog` implementation. This is where you place your log condition.
171+
172+
When you write your own `log_writer`, you must implement each loggers' own `LogWriter` interface.
173+
174+
|Logger|Interface|
175+
|---|---|
176+
|http|\KitLoong\AppLogger\HttpLog\HttpLogWriter|
177+
|performance|\KitLoong\AppLogger\PerformanceLog\PerformanceLogWriter|
178+
|query|\KitLoong\AppLogger\QueryLog\QueryLogWriter|
179+
180+
The interface requires `log` implementation. This is where you define your log body message.
165181

166182
# License
167183

0 commit comments

Comments
 (0)