Laravel Nightwatch 入门 - Knowledge of Laravel

什么是 Laravel Nightwatch

Laravel Nightwatch 是一个用来持续监控 Laravel 生产环境的托管型 SaaS 平台。它会实时采集并可视化 HTTP 请求、SQL 查询、异常、队列作业、日志、定时任务等应用整体的遥测数据。

Nightwatch 是付费服务(按月计费)。免费额度也能使用,但可采集的事件数量有上限。要在免费额度下实用起来,后面提到的采样与过滤配置几乎是必备的。

与 Telescope、Pulse 的差异

Nightwatch 与 Laravel 生态里已有的监控/调试工具目标不同,下面梳理各自用途。

工具	用途	托管形式	目标环境
Telescope	开发时的调试与查询排查	自托管(在 Laravel 应用内)	本地开发
Pulse	性能指标聚合与展示	自托管(在 Laravel 应用内)	生产 / 预发布
Nightwatch	生产应用的实时监控	Laravel 托管的 SaaS	生产环境

它采集的信息和 Telescope 差不多,但 Nightwatch 会常驻一个 agent 进程,把数据发到云端。因此即使服务器宕机也能查历史数据,还能一站式管理多服务器、多应用。

架构

Nightwatch 采用在 Laravel 应用和 Nightwatch 云之间夹一个 agent 进程的架构。 Agent 在本地(127.0.0.1:2407)等待,接收来自 Laravel 应用的事件后转发到云端。因此 agent 进程需要一直保持运行。

安装与初始设置

1. 创建账号与应用

在 nightwatch.laravel.com 创建账号,并注册组织和应用。注册应用后会得到一份环境 token。

2. 安装包

composer require laravel/nightwatch

和 Telescope 不同,不需要 --dev 标志。Nightwatch 就是面向生产环境使用的。

3. 配置 token

在 .env 中加上 token。

NIGHTWATCH_TOKEN=your-api-key

4. 启动 agent

php artisan nightwatch:agent

Agent 需要在后台常驻。Laravel Cloud、Laravel Forge、Laravel Vapor 都提供专门的指南。用 Forge 时,官方集成会帮你自动配置。查看 agent 状态:

php artisan nightwatch:status

5. 在测试环境中禁用

建议在测试执行时禁用 Nightwatch。

# .env
NIGHTWATCH_ENABLED=false

也可以在 phpunit.xml 里配置。

<php>
    <env name="APP_ENV" value="testing"/>
    <env name="NIGHTWATCH_ENABLED" value="false"/>
</php>

在免费额度下也能实用起来的配置

**免费额度对每月事件数有上限。**在默认配置(采样率 100%、采集所有数据)下,流量稍大的应用很快就会用完额度。请务必应用下面的配置。

降低采样率

NIGHTWATCH_REQUEST_SAMPLE_RATE 默认是 1.0(采集所有请求)。免费额度下建议压到 0.1(10%)左右。

# .env
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1

异常和命令继续全量采集的配置示例:

NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1    # 请求只采集 10%
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0  # 异常全量(默认)
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0    # 命令全量(默认)

关闭 query 采集

数据库查询占用的事件量往往非常大。免费额度下关掉查询采集,能为异常、请求、作业等重要事件腾出空间。

# .env
NIGHTWATCH_IGNORE_QUERIES=true

其他过滤配置

需要时也可以关闭缓存事件、邮件的采集。

NIGHTWATCH_IGNORE_CACHE_EVENTS=true
NIGHTWATCH_IGNORE_MAIL=true
NIGHTWATCH_IGNORE_NOTIFICATIONS=true
NIGHTWATCH_IGNORE_OUTGOING_REQUESTS=true

免费额度推荐配置汇总

# .env(免费额度推荐配置)
NIGHTWATCH_TOKEN=your-api-key
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_IGNORE_QUERIES=true

只需这 3 行,免费额度下也能实现实用的应用监控。

主要功能

请求监控

按 HTTP 请求采集响应时间、状态码、路由信息等。可以定位异常慢的端点,发现性能瓶颈。

异常追踪

实时捕获生产环境中的未处理异常。自动记录堆栈跟踪与源代码片段,方便排查原因。

# 异常源代码采集(默认启用)
NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=true

日志采集

与 Laravel 的日志系统(Log::error() 等)集成,把结构化日志发送到 Nightwatch。

# 采集日志的最低级别(默认:debug)
NIGHTWATCH_LOG_LEVEL=error

作业与定时任务监控

追踪队列作业、定时任务的执行历史、成功/失败状态、执行时间。可以快速定位批处理问题。

部署追踪

把每次发布的变更与问题关联起来。可以直观地进行“这次部署之后异常增加了”一类的排查。

告警与通知

通过 Slack 集成或 Webhook,可以在异常激增或性能下降时立即通知。

Telescope 和 Nightwatch 的取舍

本地开发 → Telescope
想要生产的聚合面板 → Pulse
想要生产的详细追踪与告警 → Nightwatch

三者不是互斥的,Pulse 和 Nightwatch 也可以一起用。

总结

Laravel Nightwatch 是一款能大幅提升生产 Laravel 应用可观测性的 SaaS 工具。引入时请记住以下几点:

agent 进程需要一直运行
在免费额度下,NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1 和 NIGHTWATCH_IGNORE_QUERIES=true 基本是必备
Telescope(开发)、Pulse(聚合)、Nightwatch(监控)角色不同,可以配合使用

详细配置请参考官方文档和环境变量参考。

Laravel Telescope 实战技巧

本地开发调试请使用 Telescope。

​什么是 Laravel Nightwatch

​与 Telescope、Pulse 的差异

​架构

​安装与初始设置

​1. 创建账号与应用

​2. 安装包

​3. 配置 token

​4. 启动 agent

​5. 在测试环境中禁用

​在免费额度下也能实用起来的配置

​降低采样率

​关闭 query 采集

​其他过滤配置

​免费额度推荐配置汇总

​主要功能

​请求监控

​异常追踪

​日志采集

​作业与定时任务监控

​部署追踪

​告警与通知

​Telescope 和 Nightwatch 的取舍

​总结

Laravel Telescope 实战技巧

什么是 Laravel Nightwatch

与 Telescope、Pulse 的差异

架构

安装与初始设置

1. 创建账号与应用

2. 安装包

3. 配置 token

4. 启动 agent

5. 在测试环境中禁用

在免费额度下也能实用起来的配置

降低采样率

关闭 query 采集

其他过滤配置

免费额度推荐配置汇总

主要功能

请求监控

异常追踪

日志采集

作业与定时任务监控

部署追踪

告警与通知

Telescope 和 Nightwatch 的取舍

总结