From installation to event investigation

Connect installation, capture scope, detection strategies and event investigation through the local CLI and TUI.

Complete first-time setup

Initialization supports :back; choose edit at review to revisit identity, capture or outputs. Enter pick to browse applications, or pid:123 / unit:app.service. The generated executable/UID/cgroup scope survives process restarts, without reading arguments or environment. Interfaces show flags, MTU and addresses. Saving still requires confirmation.

sudo netflowscout setup --lang en --config /etc/netflowscout/netflowscout.json \
  --endpoint-config /etc/netflowscout/endpoints/app.json

Interactive init at the installed path also offers this continuation after saving. Setup validates, displays preflight, confirms starting matching systemd units, then checks coverage, real requests and independent sink acknowledgments. Optional bounded observation metadata requires confirmation, backup and a coordinated restart. Setup does not enable boot startup or generate business requests. Skipped stages remain not_verified; HTTP acceptance does not prove searchable backend data.

Create a detection strategy

netflowscout strategy create --lang en --config CONFIG --out ./url.nfs
netflowscout strategy create --config CONFIG --out ./url.nfs --id checkout_url \
  --service checkout --path /checkout --match prefix --method POST \
  --status 500 --event checkout.failure --severity warning --input sample.ndjson

Templates cover HTTP paths, database errors and DNS errors, with service and minimum duration conditions. HTTP supports exact/prefix/RE2 regex paths, method and three-digit status strings; incomplete and truncated records are excluded. Generated DSL is type-checked; optional ndjson/pcap/stream replay produces redacted previews without delivery. CLI only creates a new 0600 file: add it to rules, set service-readable permissions and reload. TUI page 3 Create strategy appends to the selected file, validates the full rule set, previews changes, backs up, activates and checks runtime versions. Cancel returns to the form. Use the rule language for complex windows.

Manage applications and policies

TUI page 2 browses and selects running applications. Page 8 adds, duplicates, removes and previews capture policies. Converting a single match preserves it as the default policy. Copies receive unique IDs but still need adjusted scope or priority; current equal-priority target conflicts prevent activation. The final scope cannot be removed; stop its discovery unit to disable collection. Preview examines current processes without attaching probes. Maximum: 64 policies.

Explain missing events

sudo netflowscout explain --lang en --config CONFIG --endpoint-config TARGET \
  --service checkout --rule checkout_url --input sample.ndjson

The report gives evidence and next actions for coverage, loss, recent observations, rules, queue and outputs. Live tracing retains only 256 recent metadata records, without per-request operand values. Unknown evidence remains not_verified. Replay provides filter, window, cooldown and lateness traces for the full rule set. Aggregate losses cannot identify an individual dropped request. TUI x opens investigation; f in its result opens the recommended page. Overview f opens targets.

Investigate analysis events

netflowscout events --config CONFIG --service checkout --rule checkout_url \
  --since 2026-10-18T00:00:00Z --limit 100
netflowscout events --config CONFIG --id EVENT_ID

Filter service, rule, name, severity, protocol, ID, connection and inclusive RFC3339 times. TUI / accepts service=checkout rule=checkout_url since=...; use CLI flags for values containing spaces. Current and rotated files are read with an 8 MiB tail per file, 64 MiB total and 1,000 matching results. Filtering precedes the cap; ordering is newest append first. Read budgets and boundaries are reported. This is a bounded snapshot, with best-effort concurrent rotation, rather than a full history index.

Only metadata such as process, connection, rule version and time is shown; message/fields are omitted. Delivery inspection reads the running service's WAL receipts; unknown/expired receipts are unconfirmed, with capacity 8,192. Observation tracing need not be enabled. Rule investigation compares the current version and cannot reconstruct historical source. Raw evidence uses existing recording operations.

Interface language and permissions

Use tui --lang zh|en, or L to switch. Defaults follow LC_ALL, LC_MESSAGES and LANG. Pages, actions, form guidance and help are localized. Field/operation IDs, audit, JSON, underlying diagnostics and user content retain their original spelling. Existing --control, OS permissions, confirmation and backup/recovery constraints apply. See TUI and support boundaries.

Continuous task: from application to event

See the corresponding TUI screenshots.

TUI n starts or continues application → strategy → events; C clears session context. Search applications with /, select with arrows and Enter, and choose a manager first when several are selected. Attribution comes from the same manager and process generation when known, otherwise from editable configuration defaults. No PID copying is needed. Capture changes still require control permissions, preview and confirmation.

Strategy templates initially show only 2–3 fields, with service prefilled, generated IDs and event names defaulting to the rule ID. Ctrl+O expands advanced conditions and replay, Ctrl+T switches templates, and arrows choose enum values. Database/DNS templates hide HTTP inputs and do not inherit hidden HTTP conditions. Blank service means all services and is highlighted at review.

After activation, n shows events for the service and rule, including service names containing spaces. Previous snapshots and global incidents cannot leak into this scope. Enter explains what happened, the rule/version and independent sink receipts. Use d for technical details, x for diagnosis, c for the rule, o for raw evidence and r to refresh receipts. Diagnosis inherits service and rule. Different rule versions or missing historical operands remain unknown; condition string literals and request content are not added to explanations.

Read-only queries run immediately. Changes, synthetic verification and diagnostic exports still require confirmation. Context lasts only for the current TUI session.