Skip to main content
When you need to know whether a file left the machine, start from its path. Filetrace answers with the processes that sent it, the remote addresses, the bytes each socket accepted and the method, so you can tell a web server serving a download from a script copying an export. This guide walks through the commands from a quick check to a full report.
The agent must be running, and it only knows what happened since it started. Run the commands with sudo when the agent runs as root.

​
Check a single file

filetrace inspect file reports everything known about one file: its identity, every transfer, totals and the provenance of the attribution.
Read it from the bottom up: the last lines say how far back the answer reaches. If the file is not in the history, it was not read or sent since the agent started, or the history has since forgotten it (see Records and history). A path may contain * wildcards as long as they match a single file.

​
Check a directory or pattern

filetrace files lists every file associated with a transfer. Narrow it with --path, which accepts * wildcards, or --path-regex, which takes a POSIX extended regular expression:
Each row is one transfer of one file to one destination, with the bytes the socket accepted:
Add --deleted to list only files that no longer have a directory entry.

​
Decide how sure the answer is

The CONFIDENCE column says what the association rests on:
  • EXACT with method sendfile: the kernel moved the file’s data to the socket itself. The file was sent.
  • INFERRED with method read-write: the same thread read the file and then sent on the socket within two seconds, with no receive in between. The payload cannot be proven to come only from the file.
To list only certain associations, filter on the level:
A * after the level marks a transfer during which events were lost; its byte counts may be incomplete. File attribution and confidence explains both methods and their limits.

​
Follow the process

Once you know the PID, look at the process from its side: its connections, rates, top destinations and every file it sent.

​
Catch the next transfer

History answers questions about the past. To see a file the moment it is sent, follow the event stream with a path filter:
Each event carries the bytes of one collection interval, so a long transfer appears as several events. To be notified outside the terminal, export file_transfer events over OpenTelemetry or stream them from the gRPC API.

​
Keep a record

Write the answer in a machine-readable form for a ticket or a later comparison:
See Use Filetrace output in scripts for JSON processing and exit codes.