Use Filetrace output in scripts and pipelines

Every Filetrace listing prints as a table for people and as JSON, JSON Lines or CSV for programs. Machine-readable formats carry exact byte counts instead of rounded sizes, RFC 3339 timestamps, and one schema for a transfer whether it comes from files or from events. This guide shows the common patterns: query, filter with jq, follow the stream, and react to exit codes.

Choose a format

Format	Option	Shape
`table`	default	Aligned columns with rounded sizes, for reading
`json`	`--format json` or `--json`	One JSON document: an array of records, or an object for `inspect` and `stats`
`jsonl`	`--format jsonl` or `--jsonl`	One JSON record per line
`csv`	`--format csv`	A header row, then one row per record
`quiet`	`--format quiet`	One identifier per row: a file path, transfer, process, socket or flow ID

--output <file> writes to a file instead of standard output. [output] format in the configuration file sets the default for every listing command. Output formats describes each format per command, and JSON output schema lists every field.

Read a transfer record

A record from filetrace files --jsonl, wrapped for reading:

{
  "event": "file_transfer",
  "transfer_id": "tr_4",
  "timestamp": "2026-11-11T12:00:04.561Z",
  "host": "web-01",
  "platform": "linux",
  "process": {"pid": 1245, "ppid": 1, "name": "nginx", "executable": "/usr/sbin/nginx"},
  "file": {"path": "/var/www/video.mp4", "inode": 366815, "device": 64768,
           "size": 50000000, "owner": "www-data", "filesystem": "ext4", "deleted": false},
  "network": {"protocol": "tcp", "socket_id": 421,
              "local_ip": "192.0.2.7", "local_port": 443,
              "remote_ip": "198.51.100.10", "remote_port": 48175},
  "transfer": {"method": "sendfile", "bytes_sent": 50000000, "bytes_per_second": 0,
               "operations": 1, "started": "2026-11-11T12:00:04.561Z", "duration_ms": 0,
               "state": "active", "confidence": "exact",
               "evidence": ["direct_file_to_socket_transfer", "file_identity",
                            "socket_identity", "remote_endpoint"],
               "incomplete": false}
}

transfer.bytes_sent is what the socket accepted from the file, file.size the size of the file when it was first seen, and, for read-write transfers, transfer.bytes_read what the thread read from it. incomplete is true when events were lost during the transfer.

Filter and aggregate with jq

Narrow the result with Filetrace’s own options, then shape it with jq.

# Bytes sent per remote address in the last hour, largest first
sudo filetrace files --since 1h --jsonl |
    jq -s 'group_by(.network.remote_ip)
           | map({remote: .[0].network.remote_ip, bytes: (map(.transfer.bytes_sent) | add)})
           | sort_by(-.bytes)'

# Paths of files sent by a given process, one per line
sudo filetrace files --process python --format quiet

# Exact transfers over 100 MB, as tab-separated values
sudo filetrace files --confidence exact --min-bytes 100MB --jsonl |
    jq -r '[.file.path, .process.name, .network.remote_ip, .transfer.bytes_sent] | @tsv'

Follow the event stream

filetrace events --follow --jsonl prints one JSON record per event as it happens, which suits a log shipper or a small daemon:

sudo filetrace events --follow --jsonl --type file_transfer |
    jq -c 'select(.network.remote_ip | startswith("203.0.113.")) | {file: .file.path, bytes: .transfer.bytes_sent}'

Each event carries the bytes of one collection interval, so a long transfer produces several events whose bytes_sent add up to the transfer. Event records have a sequence number that increases with every record. For a stream to another system, the OTLP exporter or the gRPC API are sturdier than a pipe.

Handle exit codes

Filetrace distinguishes an empty answer from an incomplete one:

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Permission denied
`4`	Agent unavailable
`5`	Unsupported platform or capability
`9`	Partial results: events were lost in the queried time range

Code 9 still comes with output. Treat it as a warning, not a failure:

sudo filetrace files --since 1h --jsonl >transfers.jsonl
status=$?
case $status in
0) ;;
9) echo "warning: events were lost; the list may be incomplete" >&2 ;;
*) echo "filetrace failed with exit code $status" >&2; exit "$status" ;;
esac

Exit codes lists the codes of every command, including doctor, config validate and agent status.

Run periodic reports

Because history lives in the agent’s memory and is bounded, a periodic job that writes each period’s results to disk keeps a longer record than the agent does:

# /etc/cron.hourly/filetrace-report
#!/bin/sh
out=/var/log/filetrace/files-$(date +%Y%m%d%H).csv
mkdir -p /var/log/filetrace
filetrace files --since 1h --format csv --output "$out"
status=$?
[ "$status" -eq 0 ] || [ "$status" -eq 9 ]

Run the job as root, or as the user the agent runs as, so it can reach the agent’s socket.

Get started

Concepts

Guides

Use Filetrace output in scripts and pipelines

Choose a format

Read a transfer record

Filter and aggregate with jq

Follow the event stream

Handle exit codes

Run periodic reports

​Choose a format

​Read a transfer record

​Filter and aggregate with jq

​Follow the event stream

​Handle exit codes

​Run periodic reports

Choose a format

Read a transfer record

Filter and aggregate with jq

Follow the event stream

Handle exit codes

Run periodic reports