From 9147deccaa79a3f3a6b22891179d899f3dbe4d45 Mon Sep 17 00:00:00 2001 From: YueGuobin Date: Wed, 2 Sep 2026 22:33:23 +0800 Subject: [PATCH] docs: document that restarting capture nodes truncates marker pcaps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A marker pcap's lifetime equals its uBridge's lifetime: a fresh uBridge reinstalls every desired marker (paused ones too — install first, then turn the filter off) and pcap_dump_open truncates. Server restart + project reopen without starting nodes is safe until a uBridge comes up (verified live); Docker nodes restart effectively on server restart via stale-container cleanup. Recorded in the tag-gate table, a lifecycle note, and a pcap_dump_open_append follow-up. --- docs/features/marker-tag-replay.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/features/marker-tag-replay.md b/docs/features/marker-tag-replay.md index d8439fed0..4d148a5c8 100644 --- a/docs/features/marker-tag-replay.md +++ b/docs/features/marker-tag-replay.md @@ -103,11 +103,19 @@ markers at all → 404. | all `enabled: false` (paused) | retained, frozen | **allowed** | | deleted | file unlinked | no data | | `bpf`/`tag`/`direction` changed (rebuild) | pcap reopened (truncated) — new session | prior history gone | +| capture node (re)started | pcap reopened (truncated) — new session | prior history gone | - **Pause, not delete.** Deleting a marker (or its definition) deletes its pcap — replay before deleting or the data is gone. - **Pause → resume → pause is fine.** The pcap accumulates the full history; replay covers everything up to the current pause point. +- **The replay window ends when nodes restart.** A pcap's lifetime equals its uBridge's + lifetime: a fresh uBridge reinstalls every desired marker — paused ones too (install + first, then turn the filter off) — and uBridge opens the pcap with truncate semantics + (`pcap_dump_open`, not `_append`). Server restart + project reopen **without starting + nodes** is safe: nothing touches the files until a uBridge comes up (verified live). + Docker nodes effectively restart on server restart as well (stale-container cleanup), + so their window is shorter still. - uBridge flushes every matched packet to the pcap immediately (`pcap_dump_flush` per packet under a mutex — verified in the uBridge source), so a pause boundary never loses tail frames. @@ -244,4 +252,6 @@ the pcap. listener normalizes); replay keys on that int value. - **Follow-ups.** Remote-compute support via the existing capture-file proxy pattern; convenience APIs (`GET …/markers/tags` to list tags, `POST …/markers/tags/{tag}/pause` - to batch-pause — a one-call path to the replayable state). + to batch-pause — a one-call path to the replayable state); uBridge-side + `pcap_dump_open_append` (with a linktype-header check on the existing file) so capture + history survives node restarts instead of being truncated on every reinstall.