Skip to content

Commit 83d6f1f

Browse files
author
jiannei
committed
doc: update Readme
1 parent 979b75a commit 83d6f1f

File tree

1 file changed

+155
-9
lines changed

1 file changed

+155
-9
lines changed

‎README.md

Lines changed: 155 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,25 +3,171 @@
33
![Test](https://github.com/Jiannei/laravel-logger/workflows/Test/badge.svg)
44
[![StyleCI](https://github.styleci.io/repos/317144680/shield?branch=main)](https://github.styleci.io/repos/317144680?branch=main)
55

6-
## Installing
6+
## 介绍
7+
8+
`laravel-logger` 主要用来扩展项目中的日志记录，使调试更加方便。
9+
10+
## 概览
11+
12+
- 提供 `logger_async` 辅助函数，通过异步 Job 方式来记录日志；
13+
- 增加 RequestLog 中间件来记录 api 的请求和响应；对于单个请求关联 `UNIQUE_ID`，根据`UNIQUE_ID`可以跟踪请求执行过程
14+
- 适配 MongoDB 驱动，支持记录日志到 MongoDB；collection 支持按天、按月和按年拆分；
15+
- 日志的 message 适配 [laravel-enum](https://github.com/Jiannei/laravel-enum)，来让所有的日志来源可以追溯
16+
- 提供 `LOG_QUERY`、`LOG_REQUEST` 配置参数来开启关闭 sql 日志和 request 日志
17+
18+
## 安装
19+
20+
支持 Laravel 8/Lumen 8 以上版本，自定义日志描述分依赖于 [jiannei/laravel-enum](https://github.com/Jiannei/laravel-enum)，需要先进行安装。
21+
722

823
```shell
24+
$ composer require jiannei/laravel-enum -vvv
925
$ composer require jiannei/laravel-logger -vvv
1026
```
1127

12-
## Usage
1328

14-
TODO
29+
## 配置
30+
31+
复制配置项到 `config/logging.php`中，参考：https://github.com/Jiannei/lumen-api-starter/blob/master/config/logging.php
32+
33+
### Laravel
34+
35+
- 添加中间件 RequestLog 来记录 API 请求日志
36+
37+
在 `app/Http/Kernel.php` 的 $middlewareGroups 中添加
38+
39+
```php
40+
protected $middlewareGroups = [
41+
'api' => [
42+
\Jiannei\Logger\Laravel\Http\Middleware\RequestLog::class,// 加在这个地方
43+
],
44+
];
45+
```
46+
47+
-
48+
49+
### Lumen
50+
51+
- 加载配置
52+
53+
```php
54+
// bootstrap/app.php
55+
$app->configure('logging');
56+
```
57+
58+
- 添加中间件
59+
60+
```php
61+
$app->middleware([
62+
\Jiannei\Logger\Laravel\Http\Middleware\RequestLog::class,
63+
]);
64+
65+
```
66+
67+
- 注册服务容器
68+
69+
```php
70+
$app->register(\Jiannei\Logger\Laravel\Providers\ServiceProvider::class);
71+
```
72+
73+
### .env 中配置启用
74+
75+
```php
76+
LOG_CHANNEL=mongo
77+
LOG_SLACK_WEBHOOK_URL=
78+
LOG_QUERY=true
79+
LOG_REQUEST=true
80+
LOG_MONGODB_SEPARATE=daily
81+
LOG_MONGODB_LEVEL=debug
82+
83+
# 如果使用的是 mongo channel 需要配置
84+
MONGODB_HOST=mongo
85+
MONGODB_PORT=27017
86+
MONGODB_DATABASE=lumen-api
87+
MONGODB_USERNAME=
88+
MONGODB_PASSWORD=
89+
MONGODB_AUTHENTICATION_DATABASE=admin
90+
```
91+
92+
### 其他
93+
94+
如果需要记录日志到 MongoDB，需要先安装并配置[laravel-mongodb](https://github.com/jenssegers/laravel-mongodb)
95+
96+
## 如何使用
97+
98+
可以参考 [lumen-api-starter](https://github.com/Jiannei/lumen-api-starter) 中的实际使用示例。
99+
100+
### 使用
101+
102+
- `app/Repositories/Enums/LogEnum.php` 中定义记录日志时的 message
103+
- 通过 logger_async 方法记录日志
104+
105+
```php
106+
logger_async(LogEnum::SYSTEM_SQL, $arrayData);
107+
```
108+
109+
- 如果队列任务异步执行，则需要开启队列消费 `php artisan queue:work`
110+
111+
- 记录到文件中的日志内容
15112

16-
## Contributing
113+
```
114+
[2021-01-18 12:03:36] local.DEBUG: System sql {"database":"lumen-api","duration":"11.08ms","sql":"select `roles`.*, `model_has_roles`.`model_id` as `pivot_model_id`, `model_has_roles`.`role_id` as `pivot_role_id`, `model_has_roles`.`model_type` as `pivot_model_type` from `roles` inner join `model_has_roles` on `roles`.`id` = `model_has_roles`.`role_id` where `model_has_roles`.`model_id` = '11' and `model_has_roles`.`model_type` = 'App\\\\Repositories\\\\Models\\\\User'"} {"url":"/users","ip":"172.22.0.1","http_method":"get","server":"lumen-api.test","referrer":null,"unique_id":"43f54ea9-4ad4-47cf-b9da-1d3aa150ff61"}
115+
[2021-01-18 12:03:36] local.DEBUG: System request {"request":[],"response":{"status":"success","code":200,"message":"操作成功","data":{"data":[{"id":1,"nickname":"Evert Stracke DVM","email":"aufderhar.kaden@example.net"},{"id":2,"nickname":"Milton Toy","email":"keagan.eichmann@example.org"},{"id":3,"nickname":"Mrs. Alyce O'Hara","email":"cartwright.sidney@example.org"},{"id":4,"nickname":"Prof. Evalyn Windler I","email":"bertram.bartoletti@example.org"},{"id":5,"nickname":"Brant Skiles","email":"jane16@example.net"},{"id":6,"nickname":"Sage Rodriguez I","email":"ryder50@example.org"},{"id":7,"nickname":"Ms. Angelica Wiegand DVM","email":"kaelyn.mueller@example.net"},{"id":8,"nickname":"Newton Zieme","email":"sipes.kip@example.com"},{"id":9,"nickname":"Natalia Ruecker","email":"stroman.kiley@example.com"},{"id":10,"nickname":"Hallie Parisian","email":"rosina74@example.net"},{"id":11,"nickname":"Jiannei","email":"longjian.huang@foxmail.com"}],"meta":{"pagination":{"total":11,"count":11,"per_page":15,"current_page":1,"total_pages":1,"links":[]}}},"error":[]},"start":1610942614.450748,"end":1610942615.785696,"duration":"1.33s"} {"url":"/users","ip":"172.22.0.1","http_method":"GET","server":"lumen-api.test","referrer":null,"unique_id":"43f54ea9-4ad4-47cf-b9da-1d3aa150ff61"}
116+
```
117+
118+
- 记录日志到 Mongodb 的日志内容
17119

18-
You can contribute in one of three ways:
120+
```
121+
/* 1 */
122+
{
123+
"_id" : ObjectId("60050999ee7d025d4c62c8c2"),
124+
"message" : "System sql",
125+
"context" : {
126+
"database" : "lumen-api",
127+
"duration" : "54.19ms",
128+
"sql" : "select count(*) as aggregate from `users`"
129+
},
130+
"level" : 100,
131+
"level_name" : "DEBUG",
132+
"channel" : "mongo",
133+
"datetime" : ISODate("2021-01-18T12:07:53.410+08:00"),
134+
"extra" : {
135+
"url" : "/users",
136+
"ip" : "172.22.0.1",
137+
"http_method" : "get",
138+
"server" : "lumen-api.test",
139+
"referrer" : null,
140+
"unique_id" : "0cda1927-bf14-4acf-88e8-1d9ed67170b5"
141+
}
142+
}
143+
144+
/* 2 */
145+
{
146+
"_id" : ObjectId("60050999ee7d025d4c62c8c3"),
147+
"message" : "System sql",
148+
"context" : {
149+
"database" : "lumen-api",
150+
"duration" : "2.42ms",
151+
"sql" : "select * from `users` limit 15 offset 0"
152+
},
153+
"level" : 100,
154+
"level_name" : "DEBUG",
155+
"channel" : "mongo",
156+
"datetime" : ISODate("2021-01-18T12:07:53.500+08:00"),
157+
"extra" : {
158+
"url" : "/users",
159+
"ip" : "172.22.0.1",
160+
"http_method" : "get",
161+
"server" : "lumen-api.test",
162+
"referrer" : null,
163+
"unique_id" : "0cda1927-bf14-4acf-88e8-1d9ed67170b5"
164+
}
165+
}
166+
```
19167

20-
1. File bug reports using the [issue tracker](https://github.com/jiannei/laravel-logger/issues).
21-
2. Answer questions or fix bugs on the [issue tracker](https://github.com/jiannei/laravel-logger/issues).
22-
3. Contribute new features or update the wiki.
168+
## 特别说明
23169

24-
_The code contribution process is not very formal. You just need to make sure that you follow the PSR-0, PSR-1, and PSR-2 coding guidelines. Any new code contributions must be accompanied by unit tests where applicable._
170+
- SQL 日志记录参考：l[aravel-query-logger](https://github.com/overtrue/laravel-query-logger)
25171

26172
## License
27173

0 commit comments

Comments
 (0)