# Filetrace

> 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: see which files leave your machine](https://filetrace.mintlify.app/index.md): 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.
- [Get started with Filetrace](https://filetrace.mintlify.app/quickstart.md): Install Filetrace on Linux, check that the kernel can be monitored, start the agent and find which process sends which file, in five steps.
- [Install Filetrace on Linux and macOS](https://filetrace.mintlify.app/installation.md): Install Filetrace with the installer script, from the apt, dnf, yum, zypper or apk repositories, with Homebrew, or from release archives, and upgrade or remove it.
- [Build Filetrace from source](https://filetrace.mintlify.app/build-from-source.md): Build the filetrace command and the filetrace-agent daemon with CMake and Clang, enable static linking or sanitizers, and run the unit and kernel tests.
- [How the agent and the command work together](https://filetrace.mintlify.app/concepts/architecture.md): Filetrace splits into filetrace-agent, which loads the probes and keeps bounded state, and the filetrace command, which queries it over a local socket.
- [File attribution and confidence levels](https://filetrace.mintlify.app/concepts/attribution.md): How Filetrace ties bytes sent on a socket to a file, through sendfile or a read followed by a send, and what the EXACT, INFERRED and UNKNOWN levels guarantee.
- [Records, identifiers and history](https://filetrace.mintlify.app/concepts/data-model.md): The processes, sockets, flows, files, transfers and events that Filetrace records, the IDs that link them, what each byte count measures, and how long history lasts.
- [Kernel instrumentation: trampolines and kprobes](https://filetrace.mintlify.app/concepts/kernel-probes.md): Which tracepoints and kernel functions Filetrace's BPF programs attach to, how the trampoline and kprobe probe sets differ, and how to choose one.
- [Find which process sends a file and where](https://filetrace.mintlify.app/guides/trace-a-file.md): Start from a file path and find every process that sent it, the addresses it went to, how many bytes left, and how certain each attribution is.
- [Investigate a remote address or network](https://filetrace.mintlify.app/guides/investigate-a-destination.md): Start from an IP address or CIDR network and find the processes that talk to it, the files sent to it, and the sockets and flows that carried them.
- [Watch file transfers live in the terminal](https://filetrace.mintlify.app/guides/live-monitoring.md): Use filetrace watch to see file transfers, processes and connections as they happen, filter the view, and record snapshots to a log file.
- [Use Filetrace output in scripts and pipelines](https://filetrace.mintlify.app/guides/automation.md): Read Filetrace results as JSON, JSON Lines or CSV, process them with jq, follow the event stream, and handle the exit codes that signal incomplete answers.
- [Run the Filetrace agent as a system service](https://filetrace.mintlify.app/guides/run-as-a-service.md): Manage filetrace-agent under systemd, OpenRC or SysV init: start and stop it, pass options, read its logs, control who may query it, and apply configuration changes.
- [Troubleshoot Filetrace](https://filetrace.mintlify.app/guides/troubleshooting.md): Fix common Filetrace problems: an agent that is not running, missing kernel support, lost events, files that do not appear, and unexpected attributions.
- [Filetrace overhead, memory use and sizing](https://filetrace.mintlify.app/guides/performance.md): Measured system call overhead and memory use of the Filetrace agent, and how to size its tables, event queue and event log for a busy machine.
- [Filetrace command-line interface](https://filetrace.mintlify.app/cli/overview.md): Synopsis, global options, environment variables, the command list, the privileges each command needs and how to get help for the filetrace command.
- [Filter options of the listing commands](https://filetrace.mintlify.app/cli/filters.md): The filter options that the listing commands share: value syntax for times, sizes, addresses, wildcards and regular expressions, and which command takes which.
- [Output formats: table, JSON, JSON Lines, CSV and quiet](https://filetrace.mintlify.app/cli/output-formats.md): How the commands print tables, JSON, JSON Lines, CSV and bare IDs, what --output does, and how exact values differ between human and machine formats.
- [filetrace watch: live view of file transfers](https://filetrace.mintlify.app/cli/watch.md): Reference for filetrace watch: the live dashboard with its views and keys, the --no-ui snapshot mode, foreground collection, options and exit codes.
- [filetrace files: list files sent over the network](https://filetrace.mintlify.app/cli/files.md): Reference for filetrace files: the columns it prints, how to read BYTES and CONFIDENCE, every option with its values, examples with real output, and exit codes.
- [filetrace transfers: transfer records and unattributed bytes](https://filetrace.mintlify.app/cli/transfers.md): Reference for filetrace transfers: transfer records with their IDs, including sent bytes that no file accounts for, every option, examples and exit codes.
- [filetrace processes: network activity per process](https://filetrace.mintlify.app/cli/processes.md): Reference for filetrace processes: outbound rate, files sent, open connections and byte totals per process, with every option, examples and exit codes.
- [filetrace connections: open and recently closed sockets](https://filetrace.mintlify.app/cli/connections.md): Reference for filetrace connections: sockets by their local and remote ends, owning process, state and byte counts, with every option, examples and exit codes.
- [filetrace flows: bytes per process and remote endpoint](https://filetrace.mintlify.app/cli/flows.md): Reference for filetrace flows: bytes per process, socket and remote endpoint, grouping by process, remote, port or protocol, options and exit codes.
- [filetrace top: rank processes, files and destinations](https://filetrace.mintlify.app/cli/top.md): Reference for filetrace top: rank processes, files, remote addresses or connections by bytes sent, with the columns of each subject and the options.
- [filetrace events: the agent's records, past and live](https://filetrace.mintlify.app/cli/events.md): Reference for filetrace events: event types, the text, raw and JSON formats, following events live, the bounded event log, options and exit codes.
- [filetrace inspect: a file, process, socket, flow or address](https://filetrace.mintlify.app/cli/inspect.md): Reference for filetrace inspect: reports on a file, process, socket, flow or IP address, with a real sample of each, the options, JSON output and exit codes.
- [filetrace agent: run, check and stop the agent](https://filetrace.mintlify.app/cli/agent.md): Reference for filetrace agent: run the collector in the foreground, report whether an agent serves the socket and how healthy it is, or stop it.
- [filetrace-agent: the collector and its options](https://filetrace.mintlify.app/cli/filetrace-agent.md): Reference for filetrace-agent, which loads the probes and serves queries: options with defaults and ranges, modes, socket access, logging, exit codes.
- [filetrace stats: the agent's own statistics](https://filetrace.mintlify.app/cli/stats.md): Reference for filetrace stats: events received and lost, CPU and memory use, how full the bounded tables are, network totals and health, with options.
- [filetrace doctor: check whether a machine can be monitored](https://filetrace.mintlify.app/cli/doctor.md): Reference for filetrace doctor: kernel and BPF checks, every probe attached for the check, the features they add up to, the pipeline and the status.
- [filetrace capabilities: supported features and their limits](https://filetrace.mintlify.app/cli/capabilities.md): Reference for filetrace capabilities: each feature as FULL, PARTIAL, UNAVAILABLE or DISABLED with the reason, from the agent or a direct check.
- [filetrace config: show, validate and locate the config file](https://filetrace.mintlify.app/cli/config.md): Reference for filetrace config: print every setting in effect, validate a configuration file before the agent reads it, and print which file is read.
- [filetrace version: version, build and platform information](https://filetrace.mintlify.app/cli/version.md): Reference for filetrace version: the version, platform, kernel, backend, compiler, build type and commit of the command, and whether the agent is running.
- [Telemetry interfaces of the Filetrace agent](https://filetrace.mintlify.app/integrations/overview.md): The three ways other tools get the agent's data: a Prometheus page, OTLP over gRPC and a gRPC API; what each carries, how to enable it, naming and security.
- [Scrape Filetrace metrics with Prometheus](https://filetrace.mintlify.app/integrations/prometheus.md): Enable the agent's metrics page and scrape it with Prometheus: listen address, scrape job, every metric and label, PromQL examples and how series stay bounded.
- [Export events and metrics over OTLP](https://filetrace.mintlify.app/integrations/opentelemetry.md): Send Filetrace events as log records, and its metrics, to an OpenTelemetry Collector over OTLP/gRPC: settings, collector setup, records, batching, retries.
- [List and stream transfers with the gRPC API](https://filetrace.mintlify.app/integrations/grpc-api.md): Enable the agent's gRPC API, control who may connect, and call GetStatus, ListTransfers and WatchTransfers with grpcurl or buf curl; filters, streams, errors.
- [FiletraceService gRPC API reference](https://filetrace.mintlify.app/integrations/grpc-reference.md): Every RPC, message, field and enum value of filetrace.v1.FiletraceService, the gRPC API of the Filetrace agent, with what each field holds and when it is empty.
- [Filetrace metrics and telemetry attributes reference](https://filetrace.mintlify.app/integrations/telemetry-reference.md): Every exported metric with its OpenTelemetry and Prometheus names, type, unit and attributes, plus resource attributes, log record attributes and loss kinds.
- [Configuration file reference](https://filetrace.mintlify.app/reference/configuration.md): Every section and key of /etc/filetrace/config.toml with its type, default and accepted range, plus file precedence, value syntax and validation.
- [JSON output schema](https://filetrace.mintlify.app/reference/json-output.md): Field-by-field reference of the JSON and JSON Lines records of files, transfers, processes, connections, flows, top, inspect, stats, capabilities and doctor.
- [Event types of filetrace events](https://filetrace.mintlify.app/reference/event-types.md): The twelve event types the agent records, when each one is recorded, the fields it carries in text, JSON and raw output, the bounded event log, and OTLP export.
- [Exit codes of filetrace and filetrace-agent](https://filetrace.mintlify.app/reference/exit-codes.md): Exit codes of the filetrace commands, doctor, agent status, stats and filetrace-agent, the codes systemd does not restart on, and how to script code 9.
- [Known limitations of Filetrace](https://filetrace.mintlify.app/reference/limitations.md): What Filetrace does not observe or cannot attribute: platform support, the kprobe set, read-write attribution, file identity, exporters and history.
- [Versions and release channels](https://filetrace.mintlify.app/reference/versioning.md): How Filetrace versions are numbered, what the stable and lts channels carry, how candidates and untagged builds are marked, and how installs follow them.
- [Security of Filetrace](https://filetrace.mintlify.app/reference/security.md): Verify downloads and signing keys, see the agent's privileges and systemd hardening, control access to its sockets and exporters, report vulnerabilities.


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