> ## 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-agent: the collector and its options

> Reference for filetrace-agent, which loads the probes and serves queries: options with defaults and ranges, modes, socket access, logging, exit codes.

`filetrace-agent` is the program that collects. It loads the probes into the kernel, keeps what they report in bounded memory and answers queries from the `filetrace` command over a local socket. It is also what exports: the metrics page, the OTLP exporter and the gRPC API run inside it when the configuration turns them on. It runs in the foreground until it is stopped; the packages install it as the `filetrace-agent` service.

## Usage

```bash theme={null}
filetrace-agent [options]
```

```bash theme={null}
sudo filetrace-agent
```

[`filetrace agent run`](https://filetrace.mintlify.site/cli/agent) runs the same code from the command-line interface. Service managers should start `filetrace-agent` directly; [run the agent as a service](https://filetrace.mintlify.site/guides/run-as-a-service.md) covers systemd, OpenRC and SysV init.

## Settings and options

Settings come from the configuration file; an option given on the command line overrides the file. The agent reads the file before it looks at its other options, so an option overrides the file wherever it stands on the command line. `filetrace config show` prints every setting of the file, and [the configuration file reference](https://filetrace.mintlify.site/reference/configuration.md) describes them.

## Options

**--config** `string` (default: /etc/filetrace/config.toml)

Configuration file. The default file is read if it exists; `$FILETRACE_CONFIG` names another default.

**--socket** `string` (default: /run/filetrace/agent.sock)

Listening socket. The agent creates its directory if needed.

**--mode** `string` (default: standard)

`minimal` or `standard`. See [Modes](#modes).

**--probes** `string` (default: auto)

`auto`, `trampoline` or `kprobe`. Auto traces kernel functions through BPF trampolines where the kernel has them and through kprobes otherwise. [Kernel instrumentation](https://filetrace.mintlify.site/concepts/kernel-probes.md) compares the two sets.

**--flush-interval** `string` (default: 250ms)

How often counters are collected from the kernel, from `10ms` to `60s`.

**--queue-size** `string` (default: 4MB)

Kernel event queue size, from `64KB` to `1GB`. The default is 1MB in minimal mode.

**--event-log-size** `string` (default: 1MB)

Memory for the log of recent events that [`filetrace events`](https://filetrace.mintlify.site/cli/events) reads, from `64KB` to `256MB`; `0` keeps none. The default is 256KB in minimal mode.

**--correlation-window** `string` (default: 2s)

Longest read-to-send gap that still associates a file with a send. See [file attribution and confidence](https://filetrace.mintlify.site/concepts/attribution.md).

**--log-level** `string` (default: info)

`error`, `warn`, `info` or `debug`.

**--version** `boolean`

Print the version and exit.

**-h, --help** `boolean`

Print the help and exit.

Times take a unit (`ms`, `s`, `m`, `h`, `d`) and sizes an optional one (`KB`, `MB`, `GB`), as described in [filters](https://filetrace.mintlify.site/cli/filters.md#value-syntax). A value outside its range, or an unknown option, is reported with the help, and the agent exits with 2.

## Modes

| Mode | Collects |
| - | - |
| `minimal` | Processes, sockets and network byte counts |
| `standard` | Adds file identity and file-to-network attribution |

In minimal mode, [`capabilities`](https://filetrace.mintlify.site/cli/capabilities) reports file read tracking, sendfile attribution and read+send correlation as DISABLED.

## Socket access

The agent creates its socket so that only its owner can open it, and it accepts connections only from root and from the user it runs as; it logs a warning for any other client and closes the connection. When the agent runs as root, the commands that query it need `sudo`. If another agent already serves the socket, the agent reports it and exits with 1. When the agent stops, it removes the socket.

## Running and stopping

The agent stops on `SIGINT` (Ctrl-C) or `SIGTERM`, and when [`filetrace agent stop`](https://filetrace.mintlify.site/cli/agent) asks it to. If the configuration sets `[agent] enabled = false`, the agent logs a warning and exits with 0 without collecting.

The agent logs to standard error, one line per message, prefixed with `filetrace:` and the level, such as `filetrace: warn:`. At the default level, it logs where its settings came from, the backend and mode it collects with, and the exporters it serves.

## Examples

```bash theme={null}
sudo filetrace-agent
sudo filetrace-agent --mode minimal
sudo filetrace-agent --probes kprobe --log-level debug
sudo filetrace-agent --config /etc/filetrace/config.toml --event-log-size 16MB
filetrace-agent --version
```

## Exit codes

| Code | Meaning |
| - | - |
| 0 | Stopped normally |
| 1 | Other errors, such as another agent already serving the socket |
| 2 | Invalid arguments |
| 3 | Permission denied: not allowed to load BPF programs or to create the socket |
| 5 | Unsupported platform or kernel |
| 6 | Invalid configuration |
| 8 | The metrics page cannot listen on its configured address |

The systemd service does not restart an agent that exited with 2, 3, 5 or 6, because those causes do not go away on a retry.


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