Filtering and Context

The NightOwl agent receives whatever Nightwatch sends. That means all of Nightwatch’s filtering and redaction primitives work out of the box — and the agent itself buffers the payload as-received.

Sampling

Sampling lives in laravel/nightwatch and runs inside the customer’s PHP process. The trace decision is set at the start of the request and applied at the end — sensors record into the trace either way, but at flush time only sampled-in traces are shipped to the agent. That means the agent only sees and stores what Nightwatch already decided to keep, with no second-pass drop on the agent side. Configure it in .env:

NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1           # Keep ~10% of HTTP requests
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0           # Keep all artisan commands
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0         # Keep all exceptions
NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE=1.0    # Keep all scheduled tasks

When an entry point is sampled in, the entire trace — queries, cache events, logs, outgoing requests — is captured. Sampling happens at the trace boundary, not per-record, so you never end up with half a request. Set NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0 to keep every exception regardless of the parent request’s sample decision. See the throughput guide for how to pick a rate.

In-code filtering

Use Nightwatch’s filtering API to exclude specific events inline:

use Laravel\Nightwatch\Facades\Nightwatch;

Nightwatch::ignore(function () {
    // queries, jobs, cache events inside this callback
    // will not be recorded
    User::chunk(1000, fn ($chunk) => $chunk->each(...));
});

For finer control, pause and resume around a block:

Nightwatch::pause();

// ... unmonitored code ...

Nightwatch::resume();

Useful for health-check endpoints, internal admin batch operations, or hot paths you don’t want to sample but also don’t want to pay for.

Context metadata

Attach custom key-value data to traces using Laravel’s Context facade (Laravel 11+):

use Illuminate\Support\Facades\Context;

Context::add('user_role', $user->role);
Context::add('feature_flags', ['new-checkout' => true]);
Context::add('tenant', ['id' => $tenant->id, 'plan' => 'pro']);

Context data is captured by Nightwatch, stored by the agent alongside the request row, and shown in the request detail page as a collapsible JSON tree. The agent’s per-connection payload ceiling is 10 MB (MAX_PAYLOAD_BYTES) — oversized payloads are rejected with 5:ERROR, not silently truncated — so keep context entries small and structured rather than pushing large blobs through the tracer. Good things to stash in context:

Tenant / workspace / organization ID.
Feature flag decisions that affected this request.
User role or permission set.
Deploy-specific debugging flags you set temporarily during an incident.

Don’t stash secrets in Context — those entries are passed through verbatim.

Redaction

PII redaction lives in laravel/nightwatch and runs inside the customer’s PHP process before the payload is shipped to the agent. Configure it in .env:

NIGHTWATCH_REDACT_HEADERS=Authorization,Cookie,Proxy-Authorization,X-XSRF-TOKEN
NIGHTWATCH_REDACT_PAYLOAD_FIELDS=_token,password,password_confirmation

NIGHTWATCH_REDACT_HEADERS strips named headers from every request record. NIGHTWATCH_REDACT_PAYLOAD_FIELDS recursively replaces matching keys in the request payload with a [N bytes redacted] marker. Both are applied at record-assembly time, so neither the agent’s TCP buffer, SQLite WAL, nor PostgreSQL drain ever see the un-redacted values. Note: Nightwatch only writes the request payload for HTTP 500 responses, and only for application/json and form-encoded bodies. Response bodies are never written.

Combining the layers

A common production config looks like:

# Collect everything important, drop most read traffic
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0
NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE=1.0

# Strip secrets at the source (Nightwatch)
NIGHTWATCH_REDACT_HEADERS=Authorization,Cookie,Proxy-Authorization,X-XSRF-TOKEN
NIGHTWATCH_REDACT_PAYLOAD_FIELDS=_token,password,password_confirmation,api_key,access_token,refresh_token

Combined with Nightwatch::ignore() around health-check endpoints and Context::add() for tenant IDs, you get a dataset that’s lean, safe to store, and actually queryable.

Getting Started

Agent

NightOwl Features

Performance

Filtering and Context

Sampling

In-code filtering

Context metadata

Redaction

Combining the layers

​Sampling

​In-code filtering

​Context metadata

​Redaction

​Combining the layers

Sampling

In-code filtering

Context metadata

Redaction

Combining the layers