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

---

サンプリング設定

サンプリングは、完全なトレース収集をトリガーするエントリーポイント(リクエスト、コマンド、スケジュール済みタスク)を決定します。エントリーポイントがサンプリングされると、関連するすべてのイベントがキャプチャされます。

グローバルサンプリングレート

環境変数で設定:

# デフォルト: 100% サンプリング(すべてのリクエスト/コマンドをキャプチャ)
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1      # 推奨: リクエストの 10%
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0      # すべてのコマンドをキャプチャ
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0    # 常に例外をキャプチャ

推奨: 本番環境ではリクエストに対して 0.1(10%)で開始し、ボリュームとニーズに基づいて調整してください。

ルートベースのサンプリング

Sample ミドルウェアを使用して、特定のルートに異なるレートを適用:

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

// 管理者ルートを 100% サンプリング
Route::middleware(Sample::rate(1.0))->prefix('admin')->group(function () {
    // すべての管理者ルートが完全にサンプリング
});

// API ルートを 5% サンプリング
Route::middleware(Sample::rate(0.05))->prefix('api')->group(function () {
    // API ルートは控えめにサンプリング
});

// 重要なエンドポイントは常にサンプリング
Route::post('/checkout', [CheckoutController::class, 'process'])
    ->middleware(Sample::always());

// ヘルスチェックはサンプリングしない
Route::get('/health', [HealthController::class, 'check'])
    ->middleware(Sample::never());

マッチしないルートのサンプリング

削減されたサンプリングで 404/ボット トラフィックを処理:

Route::fallback(fn () => abort(404))
    ->middleware(Sample::rate(0.01));  // マッチしないルートに対して 1% サンプリング

動的サンプリング

ランタイム条件(ユーザーロール、リクエスト属性)に基づいてサンプリング:

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();  // 管理者リクエストは常にサンプリング
        }
        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
{
    // ジョブテーブルクエリをフィルター(PostgreSQL)
    Nightwatch::rejectQueries(function (Query $query) {
        return str_contains($query->sql, 'into "jobs"');
    });

    // キャッシュテーブルクエリをフィルター(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',                    // 完全一致
    '/^my-app:posts:/',                // 正規表現: my-app:posts: で開始
    '/^[a-zA-Z0-9]{40}$/',             // 正規表現: セッション ID
]);

コールバックでフィルター:

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):

# 削減されたヘッダーをカスタマイズ
NIGHTWATCH_REDACT_HEADERS=Authorization,Cookie,Proxy-Authorization,X-API-Key

リクエストペイロードを削減(デフォルトで無効):

# ペイロードキャプチャを有効化
NIGHTWATCH_CAPTURE_REQUEST_PAYLOAD=true

# 削減されたフィールドをカスタマイズ
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);
});