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

# Reconstruct an incident

> Build a timeline of what left a host during a window: raw events in order, inspect from every side, and export to JSON for analysis or a case file.

**The question:** between two times, what did this host send, by which process, to where, and in what order?

The live commands answer "what now". Incident work needs the events in order and the details behind each one. Filetrace keeps both: a bounded in-memory event log and an `inspect` report for any single object.

> [!WARNING]
>
> The event log is kept in memory and starts when the agent starts. It holds only the most recent events and does not survive a restart or a reboot. For an incident you expect to review later, make sure the OTLP exporter was sending `file_transfer` and `event_loss` records to a collector, or export the events now.

## 1. Pull the window

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
sudo filetrace events --since '2026-11-11T20:00:00Z' --until '2026-11-11T22:00:00Z' \
  --type file_transfer,network_send,process_exec --format jsonl --output /tmp/incident.jsonl
```

* `--since` and `--until` select events made in the range.
* `--type` trims the log to what matters; the raw log also holds socket and process noise.
* `--jsonl` writes one JSON object per line, which `jq`, `grep` and most log tools read directly.
* `--output` writes to a file, so the terminal is not flooded.

If the agent lost events in the window, the command still prints what it has, warns on standard error and exits with 9. Note the reported loss window in the case file.

## 2. Find the first interesting event

`jq` over the JSON lines is enough to sketch a timeline:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
# Every transfer, oldest first, as path -> peer
jq -r 'select(.type=="file_transfer") | "\(.timestamp) \(.process.comm // .process.name) \(.file.path) -> \(.network.peer.address)"' \
  /tmp/incident.jsonl | sort
```

```text theme={"theme":{"light":"github-dark","dark":"github-dark"}}
2026-11-11T20:41:02Z python3 /data/exports/users.csv -> 203.0.113.25
2026-11-11T20:41:19Z python3 /data/exports/orders.csv -> 203.0.113.25
2026-11-11T20:42:07Z curl    /etc/ssl/private/site.key -> 198.51.100.7
```

## 3. Ask about each object from every side

Once a line stands out, `inspect` gathers everything known about the process, the file, the socket, the flow or the address, so the case file does not depend on one view:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
sudo filetrace inspect process 1245 --since '2026-11-11T20:00:00Z' --json
sudo filetrace inspect file /data/exports/users.csv --json
sudo filetrace inspect ip 203.0.113.25 --since '2026-11-11T20:00:00Z'
sudo filetrace inspect socket 928374
sudo filetrace inspect flow 553102
```

| Inspect | Answers |
| - | - |
| `process <pid>` | What this process is sending now, where to, and which files it sent |
| `file <path>` | Who sent this file, to whom, how much and by which method |
| `ip <address\|cidr>` | Which processes talk to this address, and which files went there |
| `socket <id>` | One socket: its ends, owner, traffic and the files sent on it |
| `flow <id>` | One process's traffic with one remote endpoint on a socket |

`socket` and `flow` IDs are the `SOCKET` and `FLOW` columns of `connections` and `flows`.

## 4. Check whether attribution was reliable

A transfer marked with `*`, or a non-zero loss count, means the timeline may be incomplete:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
filetrace events --type event_loss --since '2026-11-11T20:00:00Z'
filetrace stats events
```

The four loss kinds say where to look: `event_queue` (the kernel queue overflowed), `counter_table` (the in-kernel table was full), `socket_identity` (a socket could not be identified), `path_buffer` (a file was recorded without its path). See [loss kinds](https://filetrace.eorlov.org/integrations/telemetry-reference.md#loss-kinds).

## 5. Keep the case file

JSON output is the record. Alongside the exported events, keep the version and the diagnostics that interpretation depends on:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
filetrace version --json > /tmp/incident.version.json
sudo filetrace doctor --json > /tmp/incident.doctor.json
sudo filetrace stats --json > /tmp/incident.stats.json
```

The doctor report says which probes were attached and whether any feature was partial; the stats report says how many events were lost and when. Both are what a reviewer needs to judge the timeline.

## 6. Make the next incident easier

* **Export to a collector continuously.** Send `file_transfer` and `event_loss` log records over OTLP so the data survives the agent and the host. See [keep an audit trail](https://filetrace.eorlov.org/use-cases/compliance.md).
* **Alert on the loss itself.** The `FiletraceEventLoss` rule in the [recipes](https://filetrace.eorlov.org/integrations/observability-recipes.md) fires before an incident, not during it.
* **Raise the limits if loss is routine.** `[limits] kernel_counters` and `[agent] ring_buffer_size`; see [overhead and sizing](https://filetrace.eorlov.org/guides/performance.md).

## Where the answer can mislead

* **The log is bounded.** Old events are discarded even while the agent runs. Export early.
* **Events are aggregated.** A `network_send` or `file_transfer` event carries the bytes of one collection interval, several a second, not of one system call. Order within an interval is not preserved.
* **A missing event is not proof of absence.** Without loss, an event that is not there did not happen; with loss, it may have been dropped.
* **`INFERRED` transfers are associations**, so two simultaneous uploads in one process can be attributed by timing. Corroborate with the script and the destination.

## Related pages

* [`filetrace events`](https://filetrace.eorlov.org/cli/events) — types, `--follow`, `--raw`, machine formats.
* [`filetrace inspect`](https://filetrace.eorlov.org/cli/inspect) — every report.
* [Loss kinds](https://filetrace.eorlov.org/integrations/telemetry-reference.md#loss-kinds)
* [Observability recipes](https://filetrace.eorlov.org/integrations/observability-recipes.md)


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