> ## Documentation Index
> Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Filetrace: see which files leave your machine

> Filetrace is a Linux eBPF tool that shows which files a machine sends over the network, which process sends them, where they go, and how sure each answer is.

Filetrace shows which files a machine sends over the network, which process sends them, and where they go. It observes the Linux kernel through eBPF, so no application has to be changed or restarted, and every answer carries a confidence level that says how it was established.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ sudo filetrace files
FILE                    PROCESS  DESTINATION   BYTES    METHOD      CONFIDENCE
/var/www/video.mp4      nginx    198.51.100.4  1.20 GB  sendfile    EXACT
/data/export/users.csv  python   192.0.2.10    85.2 MB  read-write  INFERRED
```

## Questions it answers

Filetrace links files, processes and network endpoints in both directions, so you can start an investigation from whichever side you know.

| You know | You want | Command |
| - | - | - |
| A file | Who sends it, and to whom | `filetrace inspect file /data/report.pdf` |
| An address | The files sent to it | `filetrace files --remote 203.0.113.25` |
| A process | What it is sending now | `filetrace inspect process 1245` |
| The network | The processes behind the traffic | `filetrace processes` |

## How it works

Filetrace is two programs. `filetrace-agent` loads BPF programs into the kernel, keeps what they report in bounded memory, and answers queries on a local socket. `filetrace` is the command-line interface: it asks the agent and prints the answer as a table, JSON, JSON Lines or CSV.

The agent attributes a send to a file in two ways. When the kernel moves a file to a socket itself, as `sendfile(2)` does, the attribution is **EXACT**. When a thread reads a regular file and then sends on a socket, the attribution is **INFERRED**, because the payload cannot be proven to come only from that file. Bytes that no file accounts for are still counted, as **UNKNOWN**.

The same state is available to other tools: a Prometheus metrics page, OpenTelemetry events and metrics over OTLP, and a gRPC API that lists and streams transfers.

## Requirements

Collection needs Linux 6.1 or later with BTF. Filetrace is tested on Linux 6.1, 6.12 and 7.0 on arm64, and continuous integration builds and tests x86-64 and arm64. On macOS the command-line interface reports diagnostics, but nothing is collected; collection needs Linux.

## Next steps

> [card] [Quickstart](https://filetrace.mintlify.site/quickstart.md)
>
> Install Filetrace, start the agent and find your first file transfer.

> [card] [Installation](https://filetrace.mintlify.site/installation.md)
>
> Package repositories, Homebrew, release archives, versions and channels.

> [card] [File attribution](https://filetrace.mintlify.site/concepts/attribution.md)
>
> How a send is tied to a file, and what EXACT and INFERRED mean.

> [card] [CLI reference](https://filetrace.mintlify.site/cli/overview.md)
>
> Every command, option, filter and output format.

> [card] [Integrations](https://filetrace.mintlify.site/integrations/overview.md)
>
> Prometheus metrics, OpenTelemetry export and the gRPC API.

> [card] [Configuration](https://filetrace.mintlify.site/reference/configuration.md)
>
> Every setting of the agent's configuration file.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.