configure-nightwatch

Nightwatch 配置指南

此技能可帮助配置 Laravel Nightwatch 数据收集，在可观测性、性能和隐私之间取得平衡。涵盖各种事件类型的采样策略、筛选规则和脱敏方法。

文档参考

Nightwatch 文档 是所有 Nightwatch 配置选项的权威且最新的信息来源。此技能提供实用指导和常见模式，但对于具体细节、环境变量和 API 行为，请始终以官方文档为准。文档全面介绍了以下内容：

• 筛选与配置 - 采样、筛选和脱敏的核心概念
• 各事件类型的单独页面，介绍具体配置选项：
  • 请求 - 请求采样、标头处理、载荷捕获
  • 命令 - 命令采样和脱敏
  • 查询 - 查询筛选和脱敏
  • 缓存 - 按键或模式筛选缓存事件
  • 作业 - 作业筛选和采样解耦
  • 邮件 - 邮件事件筛选
  • 通知 - 按渠道筛选通知
  • 异常 - 异常采样和限流
  • 外发请求 - HTTP 请求筛选
• reference.md - 按事件类型分类的快速查阅表、生产环境预设和验证清单

数据收集流程

Nightwatch 分三个阶段处理事件：

1. 采样 - 控制捕获哪些入口（请求、命令、计划任务）
2. 筛选 - 采样后排除特定事件（查询、缓存、邮件等）
3. 脱敏 - 修改捕获的数据，以移除或模糊敏感信息

Request/Command/Scheduled Task
       |
       v
   [Sampling?] ----NO----> Drop entire trace
       | YES
       v
   Events generated
       |
       v
   [Filtering?] ----YES---> Drop specific event
       | NO
       v
   [Redaction] ----------> Store modified data

---

采样配置

采样决定哪些入口（请求、命令、计划任务）会触发完整的跟踪收集。对某个入口进行采样后，所有相关事件都会被捕获。

全局采样率

通过环境变量配置：

# Default: 100% sampling (all requests/commands captured)
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1      # Recommended: 10% of requests
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0      # Capture all commands
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0    # Always capture exceptions

建议：在生产环境中，先将请求采样率设为 0.1（10%），再根据流量和需求进行调整。

基于路由的采样

使用 Sample 中间件为特定路由应用不同的采样率：

use Illuminate\Support\Facades\Route;
use Laravel\Nightwatch\Http\Middleware\Sample;

// Sample admin routes at 100%
Route::middleware(Sample::rate(1.0))->prefix('admin')->group(function () {
    // All admin routes sampled fully
});

// Sample API routes at 5%
Route::middleware(Sample::rate(0.05))->prefix('api')->group(function () {
    // API routes sampled sparingly
});

// Always sample critical endpoints
Route::post('/checkout', [CheckoutController::class, 'process'])
    ->middleware(Sample::always());

// Never sample health checks
Route::get('/health', [HealthController::class, 'check'])
    ->middleware(Sample::never());

未匹配路由采样

以较低的采样率处理 404/机器人流量：

Route::fallback(fn () => abort(404))
    ->middleware(Sample::rate(0.01));  // 1% sampling for unmatched routes

动态采样

根据运行时条件（用户角色、请求属性）进行采样：

use Closure;
use Illuminate\Http\Request;
use Laravel\Nightwatch\Facades\Nightwatch;

class SampleAdminRequests
{
    public function handle(Request $request, Closure $next)
    {
        if ($request->user()?->isAdmin()) {
            Nightwatch::sample();  // Always sample admin requests
        }
        return $next($request);
    }
}

命令采样

将特定命令排除在采样之外：

use Illuminate\Console\Events\CommandStarting;
use Illuminate\Support\Facades\Event;
use Laravel\Nightwatch\Facades\Nightwatch;

public function boot(): void
{
    Event::listen(function (CommandStarting $event) {
        if (in_array($event->command, ['schedule:finish', 'horizon:snapshot'])) {
            Nightwatch::dontSample();
        }
    });
}

供应商命令

Nightwatch 会自动忽略框架/内部命令。如需捕获这些命令，请选择启用：

Nightwatch::captureDefaultVendorCommands();

---

筛选配置

筛选会在采样后将特定事件排除在收集之外。使用筛选可减少噪声和配额用量。

数据库查询

筛选所有查询（禁用查询收集）：

NIGHTWATCH_IGNORE_QUERIES=true

按 SQL 模式筛选特定查询：

use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\Query;

public function boot(): void
{
    // Filter job table queries (PostgreSQL)
    Nightwatch::rejectQueries(function (Query $query) {
        return str_contains($query->sql, 'into "jobs"');
    });

    // Filter cache table queries (MySQL)
    Nightwatch::rejectQueries(function (Query $query) {
        return str_contains($query->sql, 'from `cache`')
            || str_contains($query->sql, 'into `cache`');
    });
}

缓存事件

筛选所有缓存事件：

NIGHTWATCH_IGNORE_CACHE_EVENTS=true

按缓存键模式筛选：

Nightwatch::rejectCacheKeys([
    'my-app:users',                    // Exact match
    '/^my-app:posts:/',                // Regex: starts with my-app:posts:
    '/^[a-zA-Z0-9]{40}$/',             // Regex: session IDs
]);

使用回调进行筛选：

use Laravel\Nightwatch\Records\CacheEvent;

Nightwatch::rejectCacheEvents(function (CacheEvent $cacheEvent) {
    return str_starts_with($cacheEvent->key, 'temp:');
});

邮件事件

筛选所有邮件：

NIGHTWATCH_IGNORE_MAIL=true

筛选特定邮件：

use Laravel\Nightwatch\Records\Mail;

Nightwatch::rejectMail(function (Mail $mail) {
    return str_contains($mail->subject, 'Newsletter');
});

通知事件

筛选所有通知：

NIGHTWATCH_IGNORE_NOTIFICATIONS=true

按渠道筛选：

use Laravel\Nightwatch\Records\Notification;

Nightwatch::rejectNotifications(function (Notification $notification) {
    return $notification->channel === 'database';
});

外发 HTTP 请求

筛选所有外发请求：

NIGHTWATCH_IGNORE_OUTGOING_REQUESTS=true

按 URL 筛选：

use Laravel\Nightwatch\Records\OutgoingRequest;

Nightwatch::rejectOutgoingRequests(function (OutgoingRequest $request) {
    return str_contains($request->url, 'analytics.example.com');
});

队列作业

筛选特定作业：

use Laravel\Nightwatch\Records\QueuedJob;

Nightwatch::rejectQueuedJobs(function (QueuedJob $job) {
    return $job->name === 'App\Jobs\LowPriorityJob';
});

解耦作业采样

对作业进行独立于父级上下文的采样：

use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    Queue::before(fn () => Nightwatch::sample(rate: 0.5));
}

---

脱敏配置

脱敏会修改捕获的数据，以移除或混淆敏感信息。与过滤不同，脱敏会保留事件，但会清理其内容。

请求脱敏

对敏感标头进行脱敏（自动脱敏：Authorization、Cookie、X-XSRF-TOKEN）：

# Customize redacted headers
NIGHTWATCH_REDACT_HEADERS=Authorization,Cookie,Proxy-Authorization,X-API-Key

对请求负载进行脱敏（默认禁用）：

# Enable payload capture
NIGHTWATCH_CAPTURE_REQUEST_PAYLOAD=true

# Customize redacted fields
NIGHTWATCH_REDACT_PAYLOAD_FIELDS=password,password_confirmation,ssn,credit_card

以编程方式进行脱敏：

use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\Request;

Nightwatch::redactRequests(function (Request $request) {
    $request->url = str_replace('secret', '***', $request->url);
    $request->ip = preg_replace('/\d+$/', '***', $request->ip);
});

查询脱敏

use Laravel\Nightwatch\Records\Query;

Nightwatch::redactQueries(function (Query $query) {
    $query->sql = str_replace('secret_token', '***', $query->sql);
});

缓存脱敏

use Laravel\Nightwatch\Records\CacheEvent;

Nightwatch::redactCacheEvents(function (CacheEvent $cacheEvent) {
    $cacheEvent->key = str_replace('user:', 'user:***:', $cacheEvent->key);
});

命令脱敏

use Laravel\Nightwatch\Records\Command;

Nightwatch::redactCommands(function (Command $command) {
    $command->command = preg_replace('/--password=\S+/', '--password=***', $command->command);
});

异常脱敏

use Laravel\Nightwatch\Records\Exception;

Nightwatch::redactExceptions(function (Exception $exception) {
    $exception->message = str_replace('secret', '***', $exception->message);
});

邮件脱敏

use Laravel\Nightwatch\Records\Mail;

Nightwatch::redactMail(function (Mail $mail) {
    $mail->subject = str_replace('Invoice #', 'Invoice ***', $mail->subject);
});

外发请求脱敏

use Laravel\Nightwatch\Records\OutgoingRequest;

Nightwatch::redactOutgoingRequests(function (OutgoingRequest $outgoingRequest) {
    $outgoingRequest->url = preg_replace('/api_key=\w+/', 'api_key=***', $outgoingRequest->url);
});