Skip to main content
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

  • --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:

​
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:
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:
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:
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.