---
title: "Session Replay for Laravel: запис сесій користувачів на власному сервері"
url: https://laravelukraine.com/blog/session-replay-for-laravel-zapis-sesii-koristuvaciv-na-vlasnomu-serveri
date: 2026-11-18
---

# Session Replay for Laravel: запис сесій користувачів на власному сервері

Відтворення сесій - коли можна подивитися, що саме людина робила на сторінці перед тим, як «нічого не спрацювало», - зазвичай означає LogRocket, Hotjar або Sentry Replay: платний сервіс, на чиї сервери йде вся сторінка разом із даними користувачів. [Session Replay for Laravel](https://github.com/packstub/session-replay) від Packstub (автор - Ion Căliman) робить те саме всередині вашого застосунку: записує DOM через [rrweb](https://github.com/rrweb-io/rrweb), зберігає записи на вашому диску й у вашій базі даних, а плеєр віддає за вашим власним gate. Пакет [описав Laravel News](https://laravel-news.com/laravel-session-replay), актуальна версія - [v1.1.0](https://github.com/packstub/session-replay/releases/tag/v1.1.0) від 4 листопада, ліцензія MIT.

### Як це працює

Запис вмикає одна Blade-директива перед закривальним `</body>` у потрібних макетах. Нічого збирати чи публікувати на фронтенді не треба:

```blade
  @sessionReplay
</body>
```

Директива виводить невеликий об'єкт конфігурації та скрипт із `defer`. Скрипт записує сторінку через rrweb: один запис на вкладку браузера, який триває між переходами сторінками, доки вкладка не простоює. Що кілька секунд він надсилає на сервер стиснутий gzip пакет подій.

Цікаве рішення - на ендпоїнті прийому. Коли сторінка рендериться, сервер підписує ключем застосунку токен із поточним користувачем, тенантом і вашими власними властивостями. Браузер надсилає цей токен з кожним пакетом, тож ендпоїнту не потрібні ні сесія, ні cookie, ні CSRF-токен. Токен підписаний, але не зашифрований - його вміст видно у вихідному коді сторінки, тому секретів у властивості не кладіть.

Сервер не розбирає події, а лише зберігає файл і оновлює індекс. Чанки лягають у `sessions/{id}/{seq}.json.gz` на будь-якому диску Laravel, індекс - у таблиці `replay_sessions`, `replay_chunks`, `replay_markers` і `replay_assets`. Переглядач за адресою `/session-replay` показує список записів із фільтрами за помилками.

### Маркери на таймлайні

Головна цінність для розбору багів - маркери, за якими можна одразу перескочити до потрібного моменту:

- неперехоплені JS-помилки та виклики `console.error()`;
- невдалі Livewire-запити, а також same-origin `fetch` і XHR з відповіддю 500 і вище;
- винятки, які Laravel зафіксував під час записаного HTTP-запиту, - з класом винятку, методом, шляхом і ID звіту;
- завантаження сторінок, переходи `wire:navigate`, зміни сторінок в Inertia чи Vue Router;
- web vitals: LCP, INP і CLS;
- rage clicks - три й більше кліки в одне місце протягом 700 мс.

Свої маркери можна ставити з браузера, а кнопку «повідомити про проблему» - прив'язати до надсилання запису:

```js
SessionReplay.mark('Checkout started', { cart: 3 });
SessionReplay.send('Wrong total on the invoice');
```

### Запис лише тоді, коли щось зламалося

Писати кожну сесію не обов'язково. У режимі `on_error` рекордер тримає останню хвилину подій у пам'яті браузера і нічого не вивантажує, доки не спрацює тригер:

```php
// config/session-replay.php
'mode' => 'on_error',
'on_error' => [
  'buffer_seconds' => 60,
  'triggers' => ['error', 'request'],
  'ask' => false,
],
```

Після JS-помилки чи невдалого запиту на сервер іде буфер, і запис триває до кінця сесії вкладки - тобто ви бачите і хвилину до збою, і те, що людина робила після нього. З `'ask' => true` пакет спершу спитає дозволу. Для частки записаних сесій є `sample_rate` (від 0 до 1), а для вибіркового запису - `SessionReplay::recordWhen()`.

### Посилання на запис у логах

Поки триває запис, глобальний `middleware` додає ID запису та URL переглядача в [Context](https://laravelukraine.com/docs/13.x/context). Laravel додає Context до кожного запису в лог у межах цього HTTP-запиту, тож рядок про помилку вже містить посилання на відео:

```text
[2026-09-18 10:57:12] production.ERROR: Undefined array key "total"
{"exception":"…"} {"session_replay":"0b1c6a0e-…","session_replay_url":"https://app.test/session-replay/0b1c6a0e-…"}
```

Ті самі ключі отримують трекери помилок, що читають Context: Flare, Sentry, Nightwatch. Ключ `session_replay_moment` відкриває запис за три секунди до невдалого запиту. У зворотний бік `SessionReplay::logUrlUsing()` додає біля серверної помилки в плеєрі кнопку «Open in logs» - наприклад, на Log Viewer.

### Встановлення і доступ

Пакету потрібні PHP 8.3+, розширення `zlib` і Laravel 12 або 13:

```bash
composer require packstub/session-replay
php artisan session-replay:install
```

Далі - визначити, хто може дивитися записи, у `app/Providers/SessionReplayServiceProvider.php`, який опублікує інсталятор. Поза середовищем `local` записів не побачить ніхто, доки цього gate немає:

```php
use Illuminate\Support\Facades\Gate;
use Packstub\SessionReplay\Models\ReplaySession;

Gate::define('viewSessionReplay', function ($user, ?ReplaySession $session = null): bool {
  return $user->is_admin;
});
```

Gate перевіряється на кожному запиті: і для списку, і для плеєра, і для кожного файлу за ним. Очищення старих записів ставимо в розклад у `routes/console.php`:

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('session-replay:prune')->daily();
```

Для [Filament v5](https://laravelukraine.com/blog/filament-v5-pidtrimka-livewire-v4-ta-novii-instrument-blueprint) є окремий пакет [packstub/filament-session-replay](https://github.com/packstub/filament-session-replay): ресурс із фільтрами, плеєр і relation manager із записами кожного користувача. Він вимагає `filament/filament` ^5.0 і основний пакет ^1.1. Щоб помацати все без встановлення у свій проєкт, автор зробив [демо-застосунок](https://github.com/packstub/session-replay-demo) - маленький магазин із готовими записами.

### Приватність і навантаження: що перевірити перед продом

Запис сесії показує все, що людина бачила на екрані. Це головне, про що варто пам'ятати, і жодні налаштування за замовчуванням цього не скасовують. Самі налаштування, втім, обережні:

- усі `input`, `textarea` і `select` замасковано зірочками (`privacy.mask_all_inputs`), паролі й приховані поля - навіть якщо цю опцію вимкнути;
- текст у `contenteditable` (Tiptap, Trix) маскується так само;
- гостей не записують (`guests`), IP-адресу не зберігають узагалі - це не налаштовується;
- стан Livewire-компонентів (`wire:snapshot`) до запису не потрапляє;
- сторінки скидання пароля й підтвердження email виключено, значення `token`, `signature`, `email` та інших параметрів у URL вирізаються;
- cookie, localStorage, тіла запитів і відповідей не записуються;
- записи видаляються через 30 днів (`retention.days`).

Чого пакет не знає - це ваших даних. IBAN, номер телефону чи адреса, виведені звичайним текстом на сторінці, у записі будуть. Їх треба позначити `data-replay-mask` (текст стане зірочками) або `data-replay-block` (блок запишеться порожнім прямокутником), а для жорсткого режиму є `privacy.mask_all_text`. Також варто подивитися, що ваш код пише в `console`: консольний вивід теж іде в запис. За замовчуванням `consent` має значення `always`, тобто запис стартує разом зі сторінкою - для публічного сайту під GDPR логічніше `opt-in` і виклик `SessionReplay.consent(true)` з банера згоди. Документація пакета має [окремий розділ про приватність](https://github.com/packstub/session-replay/blob/main/docs/privacy.md) з текстом для політики приватності.

Щодо місця: автор наводить заміри зі своєї лабораторії на панелі Filament 5. Знімок сторінки з таблицею на 50 рядків - 34 КБ, стилі Filament зберігаються один раз для всіх записів (65 КБ), відкрита сторінка без дій - 0,2 КБ на хвилину. Його оцінка для людини, що відкриває чотири-шість сторінок на хвилину, - близько 5 МБ на диску й 0,4 МБ у БД на годину безперервної роботи, тобто при 30 днях зберігання 100 активних годин на місяць дають приблизно 0,5 ГБ на диску й 40 МБ у базі. Це екстраполяція, а не виміри на реальних користувачах, тож на своєму трафіку варто перевірити самостійно. Рекордер важить 32 КБ JavaScript (gzip), а стискає пакети браузер поза головним потоком.

Ще одна практична деталь: [v1.1.0](https://github.com/packstub/session-replay/releases/tag/v1.1.0) - безпековий випуск. Він закрив можливість у мультитенантних застосунках читати стилі чи знімки сторінок іншого тенанта за хешем, а також дописувати в чужий запис за його ID. Якщо ви ставили бету, оновіться і виконайте `php artisan migrate`.

### Кому це варто спробувати

Пакет має сенс, якщо баг-репорти у вас звучать як «я натиснув зберегти, і нічого не сталося», а відтворити проблему за логами не вдається. Особливо - у Livewire- і Filament-застосунках, на які він явно розрахований: невдалі Livewire-запити, `wire:navigate` і маскування `wire:snapshot` працюють з коробки. Тим, хто вже платить за Sentry чи PostHog і задоволений ними, міняти щось не обов'язково - автор і сам пише, що пакет про відтворення всередині власного застосунку, а не про заміну платформ.

Пакет молодий: перша стабільна версія вийшла 22 жовтня. Найобережніший старт - режим `on_error` на невеликому `sample_rate`, з одразу налаштованим gate, переглянутими сторінками з персональними даними і запланованим `session-replay:prune`.
