Reconstruct an incident

Build a timeline of what left a host during a window: raw events in order, inspect from every side, and export to JSON for analysis or a case file.

The question: between two times, what did this host send, by which process, to where, and in what order?

The live commands answer “what now”. Incident work needs the events in order and the details behind each one. Filetrace keeps both: a bounded in-memory event log and an inspect report for any single object.

The event log is kept in memory and starts when the agent starts. It holds only the most recent events and does not survive a restart or a reboot. For an incident you expect to review later, make sure the OTLP exporter was sending file_transfer and event_loss records to a collector, or export the events now.

​

1. Pull the window

sudo filetrace events --since '2026-11-11T20:00:00Z' --until '2026-11-11T22:00:00Z' \
  --type file_transfer,network_send,process_exec --format jsonl --output /tmp/incident.jsonl

• --since and --until select events made in the range.
• --type trims the log to what matters; the raw log also holds socket and process noise.
• --jsonl writes one JSON object per line, which jq, grep and most log tools read directly.
• --output writes to a file, so the terminal is not flooded.

If the agent lost events in the window, the command still prints what it has, warns on standard error and exits with 9. Note the reported loss window in the case file.

​

2. Find the first interesting event

jq over the JSON lines is enough to sketch a timeline:

# Every transfer, oldest first, as path -> peer
jq -r 'select(.type=="file_transfer") | "\(.timestamp) \(.process.comm // .process.name) \(.file.path) -> \(.network.peer.address)"' \
  /tmp/incident.jsonl | sort

2026-11-11T20:41:02Z python3 /data/exports/users.csv -> 203.0.113.25
2026-11-11T20:41:19Z python3 /data/exports/orders.csv -> 203.0.113.25
2026-11-11T20:42:07Z curl    /etc/ssl/private/site.key -> 198.51.100.7

​

3. Ask about each object from every side

Once a line stands out, inspect gathers everything known about the process, the file, the socket, the flow or the address, so the case file does not depend on one view:

sudo filetrace inspect process 1245 --since '2026-11-11T20:00:00Z' --json
sudo filetrace inspect file /data/exports/users.csv --json
sudo filetrace inspect ip 203.0.113.25 --since '2026-11-11T20:00:00Z'
sudo filetrace inspect socket 928374
sudo filetrace inspect flow 553102

Inspect	Answers
process <pid>	What this process is sending now, where to, and which files it sent
file <path>	Who sent this file, to whom, how much and by which method
ip <address|cidr>	Which processes talk to this address, and which files went there
socket <id>	One socket: its ends, owner, traffic and the files sent on it
flow <id>	One process’s traffic with one remote endpoint on a socket

socket and flow IDs are the SOCKET and FLOW columns of connections and flows.

​

4. Check whether attribution was reliable

A transfer marked with *, or a non-zero loss count, means the timeline may be incomplete:

filetrace events --type event_loss --since '2026-11-11T20:00:00Z'
filetrace stats events

The four loss kinds say where to look: event_queue (the kernel queue overflowed), counter_table (the in-kernel table was full), socket_identity (a socket could not be identified), path_buffer (a file was recorded without its path). See loss kinds.

​

5. Keep the case file

JSON output is the record. Alongside the exported events, keep the version and the diagnostics that interpretation depends on:

filetrace version --json > /tmp/incident.version.json
sudo filetrace doctor --json > /tmp/incident.doctor.json
sudo filetrace stats --json > /tmp/incident.stats.json

The doctor report says which probes were attached and whether any feature was partial; the stats report says how many events were lost and when. Both are what a reviewer needs to judge the timeline.

​

6. Make the next incident easier

• Export to a collector continuously. Send file_transfer and event_loss log records over OTLP so the data survives the agent and the host. See keep an audit trail.
• Alert on the loss itself. The FiletraceEventLoss rule in the recipes fires before an incident, not during it.
• Raise the limits if loss is routine. [limits] kernel_counters and [agent] ring_buffer_size; see overhead and sizing.

​

Where the answer can mislead

• The log is bounded. Old events are discarded even while the agent runs. Export early.
• Events are aggregated. A network_send or file_transfer event carries the bytes of one collection interval, several a second, not of one system call. Order within an interval is not preserved.
• A missing event is not proof of absence. Without loss, an event that is not there did not happen; with loss, it may have been dropped.
• INFERRED transfers are associations, so two simultaneous uploads in one process can be attributed by timing. Corroborate with the script and the destination.

​

Related pages

• filetrace events — types, --follow, --raw, machine formats.
• filetrace inspect — every report.
• Loss kinds
• Observability recipes