configure-nightwatch

Nightwatch 設定ガイド

このスキルは、可観測性、パフォーマンス、プライバシーのバランスを取りながら、Laravel Nightwatch のデータ収集を設定するのに役立ちます。すべてのイベントタイプにわたるサンプリング戦略、フィルタリングルール、秘匿化の方法を扱います。

ドキュメントの参照先

Nightwatch ドキュメントは、Nightwatch のすべての設定オプションについて、決定版となる最新の情報源です。このスキルでは実践的なガイダンスと一般的なパターンを紹介しますが、具体的な詳細、環境変数、API の動作については、必ず公式ドキュメントを主な情報源として参照してください。ドキュメントでは、以下の内容を網羅しています。

• フィルタリングと設定 - サンプリング、フィルタリング、秘匿化の基本概念
• 個別のイベントタイプのページと、各タイプ固有の設定オプション：
  • リクエスト - リクエストのサンプリング、ヘッダーの処理、ペイロードの取得
  • コマンド - コマンドのサンプリングと秘匿化
  • クエリ - クエリのフィルタリングと秘匿化
  • キャッシュ - キーまたはパターンによるキャッシュイベントのフィルタリング
  • ジョブ - ジョブのフィルタリングとサンプリングの分離
  • メール - メールイベントのフィルタリング
  • 通知 - チャネルによる通知のフィルタリング
  • 例外 - 例外のサンプリングとスロットリング
  • 送信リクエスト - HTTP リクエストのフィルタリング
• reference.md - イベントタイプ別のクイック参照表、本番環境向けプリセット、検証チェックリスト

データ収集の流れ

Nightwatch は、次の 3 段階でイベントを処理します。

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);
});