Sync preview and snapshots
Before a connector pulls anything, Log Lens shows you exactly what it plans to do. Preview discovers the remote files, compares them against what has already been mirrored locally, and reports a per-file action plan. Snapshots then guarantee that the sync you confirm is the sync that actually runs. This lets you review changes before any bytes move, and keeps large log fetches predictable.
Previewing a sync
Preview runs against a single enabled connector, or across every enabled connector at once. A disabled connector is rejected. For each discovered file, preview classifies the work:
| Action | Meaning |
|---|---|
new | File never seen before; fetch from byte 0 |
append | Remote grew; fetch only the new tail |
unchanged | Local mirror already matches |
index_local | Bytes already mirrored but not yet indexed |
rotation | Identity changed or file shrank; start a new generation |
rename | Same file appeared at a new path |
reconcile | Matches a manually imported source, sizes differ |
already_ingested | Matches a manual source exactly |
The preview summary totals files, files_to_sync, already_current, and bytes_to_fetch, plus an actions breakdown of every action count - so you can see the byte cost before committing.
Snapshot verification
Every preview includes a snapshot: a SHA-256 hash over each file's path, identity, size, and modification time and the calculated action, byte range, and will_sync decision. When you run the sync, pass that snapshot back. Log Lens re-discovers the files, rebuilds the plan, and compares. If either the remote set or calculated plan shifted, the run aborts with The synchronization plan changed after preview. Review the synchronization files again. instead of fetching work that was not confirmed.
Sync-all works the same way, keyed by connector id - a connector missing from the confirmed set is rejected rather than silently synced. Passing no snapshot skips the check and syncs whatever is currently there.
Append-only fetch
Sync never re-downloads data it already holds. It fetches only remote size − local mirror size, in chunks (default 8 MiB, sync.chunk_size), appending each range to the canonical mirror. A short read aborts the run. If the remote is smaller than the mirror, that is treated as rotation and a fresh generation begins. Only one sync per connector can run at a time; a second attempt reports the connector is already synchronizing.
Dashboard confirmations create durable queued run rows and return immediately. A detached CLI worker performs only the confirmed actionable files; unchanged files are not fetched, imported, hashed, or counted as progress. Byte totals advance after each chunk; completed files, indexed events, and the current path advance after each actionable file. One-time metadata-only reconciliation can occur invisibly without inflating transfer progress. Reloading the dashboard resumes the progress display without affecting the worker.
Worker launch is cross-platform: PHP CLI discovery checks configured overrides, the web SAPI's sibling install, PHP_BINDIR, and PATH; Linux/macOS use a POSIX shell and Windows uses cmd.exe. If launch is unavailable, the row remains queued and the normal scheduled CLI or Artisan sync drains it. The HTTP request never falls back to transferring large logs synchronously.