PHPackages                             charsen/moo-monitor-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. charsen/moo-monitor-laravel

ActiveLibrary[Logging & Monitoring](/categories/logging)

charsen/moo-monitor-laravel
===========================

Laravel runtime error & slow SQL monitoring SDK for moo-scaffold-cloud

v0.1.9(1w ago)01↓100%MITPHPPHP ^8.0CI passing

Since Jun 12Pushed 4d agoCompare

[ Source](https://github.com/charsen/moo-monitor-laravel)[ Packagist](https://packagist.org/packages/charsen/moo-monitor-laravel)[ Docs](https://gitee.com/charsen/moo-monitor-laravel)[ RSS](/packages/charsen-moo-monitor-laravel/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (7)Versions (11)Used By (0)

moo-monitor-laravel
===================

[](#moo-monitor-laravel)

Laravel 后端监控采集 SDK，用来把项目里的 **运行时异常** 和 **慢 SQL** 上报到 [moo-scaffold-cloud](https://gitee.com/charsen/moo-scaffold-cloud) 集中查看、告警和处理。

这个包是一个 **headless 采集端**：不提供本地页面、不注册业务路由，只负责采集数据、写入本地缓冲目录，再推送到云端。

适用场景
----

[](#适用场景)

- Laravel 项目需要统一收集后端异常。
- 想知道哪些 SQL 超时、在哪个文件和行号触发。
- 多个项目需要在同一个云端控制台查看问题、告警和处理状态。
- 从 `moo-scaffold  $e])` 这类只写日志的异常，避免队列 failed / 业务 catch 漏进云端。队列失败捕获监听 Laravel `JobFailed` 事件，把 connection、queue、job name、attempts 等失败上下文带进 runtime。慢 SQL 监控监听 Laravel `QueryExecuted` 事件，超过阈值的 SQL 会被记录，包含执行耗时、SQL 内容、触发位置和请求信息。相同问题聚合相同异常或相同慢 SQL 会按 hash 聚合，累计出现次数，避免同一个问题刷屏。敏感信息脱敏对 password、token、secret、authorization 等常见敏感字段做脱敏处理。本地缓冲数据先写入 `storage/moo-monitor/`，云端或网络异常不会影响业务请求。云端推送通过 `moo:cloud:push` 增量推送到 moo-scaffold-cloud，云端负责查看、告警和处置。AI / MCP 辅助处理可通过 `moo:cloud:mcp` 让 Claude Code / Codex 等工具读取云端 runtime 错误和待办，并回写处理状态。旧版迁移支持从 `moo-scaffold = 3.9`，通常不需要单独安装本包，scaffold 会自动依赖它。

快速接入
----

[](#快速接入)

在宿主项目 `.env` 中配置云端推送：

```
MOO_MONITOR_CLOUD_ENABLED=true
MOO_MONITOR_CLOUD_TOKEN=moo_xxxxxxxx

# 私有部署时再配置，默认是 https://c.mooeen.com
# MOO_MONITOR_CLOUD_URL=https://c.mooeen.com
```

Token 在 moo-scaffold-cloud 的「接入 Token」页面生成，建议开启 `runtimes` 和 `slow_queries` 能力。

运行时异常默认开启：

```
MOO_MONITOR_RUNTIME_ENABLED=true
```

慢 SQL 默认关闭，需要时开启：

```
MOO_MONITOR_SQL_SLOW_ENABLED=true
MOO_MONITOR_SQL_SLOW_THRESHOLD_MS=100
```

发布配置文件可查看更多选项：

```
php artisan vendor:publish --tag=moo-monitor-config
```

配置文件位置：

```
config/moo-monitor.php

```

验证是否接入成功
--------

[](#验证是否接入成功)

清理配置缓存：

```
php artisan config:clear
```

**推荐：一键自检。** 不用等真异常发生，直接推一条 runtime + 一条慢 SQL 到云端，逐步确认配置是否有效：

```
php artisan moo:cloud:test
```

输出会逐项反馈：配置检查 → 心跳（连通 + 鉴权 + SDK/宿主元信息）→ 推送自检 runtime → 推送自检慢 SQL。全绿即说明「采集 → 推送 → 云端」整条管道通畅。自检记录是可识别的（runtime 类名 `SelfTestException`、SQL 带 `self-test` 标记），默认保留为「未处理」，这样你能去云端 runtimes / slow\_queries 列表**亲眼确认数据已到达**；确认后在 UI 解决即可，或加 `--resolve` 让命令推送后自动标记已解决。重复运行只 upsert 同一条，不会堆积。

也可以用既有方式手动验证 —— 查看本地是否有待推送数据：

```
php artisan moo:cloud:push --dry-run
```

真实推送一次：

```
php artisan moo:cloud:push
```

如果云端没有数据，按顺序检查：

1. `.env` 中 `MOO_MONITOR_CLOUD_ENABLED` 是否为 `true`。
2. `MOO_MONITOR_CLOUD_TOKEN` 是否正确，且 token 有对应能力。
3. 项目是否真的触发过异常或慢 SQL。
4. 慢 SQL 是否已开启，阈值是否过高。
5. 服务器是否能访问 `MOO_MONITOR_CLOUD_URL`。
6. 内网自签证书导致 TLS 校验失败时，设 `MOO_MONITOR_CLOUD_VERIFY=false`。

### 推送一直失败

[](#推送一直失败)

为保证不丢数据，某一类（runtimes / slow\_sql）只要有一批推送失败，游标就不前进、下次重试同一批，该类的本地缓冲也不会被回收。因此**单条被云端持久拒收的记录会卡住整类推送并让本地缓冲持续增长**。

`moo:cloud:push` 失败时会打印卡住的记录 hash（自动调度的后台运行则写入日志），据此定位：

```
storage/moo-monitor///.yaml

```

确认该记录无需保留后，可手动移走或删除对应 yaml，再重新推送。

自动推送
----

[](#自动推送)

当以下配置同时满足时，包会自动注册每分钟推送任务：

```
MOO_MONITOR_CLOUD_ENABLED=true
MOO_MONITOR_CLOUD_SCHEDULE=true
```

宿主项目仍然需要正常运行 Laravel scheduler。服务器 crontab 示例：

```
* * * * * cd /path/to/project && php artisan schedule:run >> /dev/null 2>&1
```

没有接入 scheduler 时，也可以用自己的定时任务执行：

```
php artisan moo:cloud:push
```

常用命令
----

[](#常用命令)

命令说明`php artisan moo:cloud:test`自检：推一条 runtime + 一条慢 SQL 到云端，确认接入配置有效。`php artisan moo:cloud:push`推送 runtime 异常和慢 SQL 到云端。`php artisan moo:cloud:push --dry-run`只统计待推送数量，不发送请求。`php artisan moo:cloud:push --type=runtimes`只推送运行时异常。`php artisan moo:cloud:push --type=slow_sql`只推送慢 SQL。`php artisan moo:cloud:push --all`忽略游标，全量重推。云端按 hash 幂等处理。`php artisan moo:cloud:mcp`启动 MCP server，供 AI 工具读取云端错误和待办。`php artisan moo:monitor:migrate`从 `moo-scaffold