configure-nightwatch
Configures Laravel Nightwatch data collection, sampling rates, filtering rules, and redaction policies. Use when setting up Nightwatch, managing data volume, protecting sensitive data (PII), or optimizing event collection for production workloads.
laravel · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add laravel/agent-skills --skill configure-nightwatch技能说明
name: configure-nightwatch description: Configures Laravel Nightwatch data collection, sampling rates, filtering rules, and redaction policies. Use when setting up Nightwatch, managing data volume, protecting sensitive data (PII), or optimizing event collection for production workloads. license: MIT metadata: author: laravel
Nightwatch Configuration Guide
This skill helps configure Laravel Nightwatch data collection to balance observability, performance, and privacy. Covers sampling strategies, filtering rules, and redaction methods across all event types.
Documentation Reference
The Nightwatch Documentation is the definitive and up-to-date source of information for all Nightwatch configuration options. This skill provides practical guidance and common patterns, but always consult the official documentation as the primary source of truth for specific details, environment variables, and API behavior. The documentation includes comprehensive coverage of:
- Filtering and Configuration - Core concepts for sampling, filtering, and redaction
- Individual event type pages with specific configuration options:
- Requests - Request sampling, header handling, payload capture
- Commands - Command sampling and redaction
- Queries - Query filtering and redaction
- Cache - Cache event filtering by key or pattern
- Jobs - Job filtering and sampling decoupling
- Mail - Mail event filtering
- Notifications - Notification filtering by channel
- Exceptions - Exception sampling and throttling
- Outgoing Requests - HTTP request filtering
- reference.md - Quick lookup table by event type, production presets, and verification checklist
Data Collection Flow
Nightwatch processes events through three stages:
- Sampling - Controls which entry points are captured (requests, commands, scheduled tasks)
- Filtering - Excludes specific events after sampling (queries, cache, mail, etc.)
- Redaction - Modifies captured data to remove/obfuscate sensitive information
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
Sampling Configuration
Sampling determines which entry points (requests, commands, scheduled tasks) trigger full trace collection. When an entry point is sampled, all related events are captured.
Global Sample Rates
Configure via environment variables:
# 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
Recommendation: Start with 0.1 (10%) for requests in production, adjust based on volume and needs.
Route-Based Sampling
Apply different rates to specific routes using the Sample middleware:
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());
Unmatched Route Sampling
Handle 404/bot traffic with reduced sampling:
Route::fallback(fn () => abort(404))
->middleware(Sample::rate(0.01)); // 1% sampling for unmatched routes
Dynamic Sampling
Sample based on runtime conditions (user role, request attributes):
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);
}
}
Command Sampling
Exclude specific commands from sampling:
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();
}
});
}
Vendor Commands
Nightwatch automatically ignores framework/internal commands. Opt-in to capture them:
Nightwatch::captureDefaultVendorCommands();
Filtering Configuration
Filtering excludes specific events from collection after sampling. Use filtering to reduce noise and quota usage.
Database Queries
Filter all queries (disable query collection):
NIGHTWATCH_IGNORE_QUERIES=true
Filter specific queries by SQL pattern:
use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\Query;
阅读完整来源 ↗