> ## 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.

# Attribute transfers to containers

> Use cgroup and namespace filters to attribute file transfers to the right container or Kubernetes pod, and learn what the metrics and records can and cannot show.

**The question:** which container sent this file, when many containers share one host?

Filetrace runs on the host and sees the host's processes. Two filters map those processes back to a container: `--cgroup` and `--namespace`. Both are first-class filters on `files`, `transfers`, `processes`, `connections`, `flows` and `watch`.

## Run the agent on the host, not in a container

The agent loads eBPF programs and needs the host's PID namespace to see every container's processes. Run `filetrace-agent` as the packaged service on the node. An agent inside a container, even privileged, sees only its own namespace.

## Find a container's cgroup

Every process has a cgroup, and its directory in the cgroup tree identifies it:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
cat /proc/1245/cgroup
# 0::/kubepods/burstable/pod7c2a.../b6f3...
```

Pass the directory, and Filetrace uses its inode number, or pass the numeric ID directly:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Everything this container sent, by its cgroup directory
sudo filetrace files --cgroup /sys/fs/cgroup/kubepods/burstable/pod7c2a.../b6f3... --since 1h

# The same via the numeric cgroup ID
sudo filetrace files --cgroup 4294968 --since 1h
```

## Filter by namespace

`--namespace` takes the inode number of a network, PID or mount namespace:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
ls -Li /proc/1245/ns/net
# ... net:[4026532299]
sudo filetrace transfers --namespace 4026532299 --since 1h
```

This is the quickest way to answer "what did this pod's network namespace send", because the network namespace is per pod.

## Rank containers by egress

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Processes, with children folded in, ranked by outbound rate
sudo filetrace processes --cgroup /sys/fs/cgroup/kubepods --include-children --sort outbound

# Top destinations across the node, to see which services talk where
sudo filetrace top destinations --since 1h --limit 20
```

`--include-children` matters in containers: a shell, a runtime and a worker are separate processes, and folding descendants into the parent's totals shows the pod, not the pieces.

## What the metrics show

The `process_executable_name` label is the kernel's name for the process, at most 15 bytes. It does **not** carry the container or pod name. To get per-container metrics, join the Filetrace series with your container metadata on the host and the process:

```promql theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Egress per process on a node
sum by (process_executable_name) (
  rate(filetrace_network_io_bytes_total{network_io_direction="transmit"}[5m])
)
```

The reliable per-container key is in the log records and the API: `process.pid`, plus `filetrace.socket.id` to follow a transfer to its endpoints. Join `process.pid` against `container_process`-style metrics from cAdvisor or the kubelet, or against the cgroup ID, to attribute transfers to a pod.

## A worked example

A node runs an upload service and a database. Something is sending a large backup off the node.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Which cgroup is sending the most file bytes right now
sudo filetrace files --since 15m --sort bytes --limit 5
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FILE                     PROCESS  DESTINATION    BYTES   METHOD      CONFIDENCE  SCRIPT
/backups/shop-2026.sql   pg_dump  203.0.113.44   8.40 GB  read-write  INFERRED    module:pg_backup.py
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Confirm it is the database pod, not a sidecar
sudo filetrace inspect process 3311
```

The report names the cgroup and the namespace; compare them with the pod spec. The transfer is `INFERRED` because `pg_dump` reads the file and writes it to the socket, which is expected for a dump stream.

## Where the answer can mislead

* **Short-lived processes.** A process that exits before the agent reads its cgroup can show without one. `process_executable_name` still names it.
* **Host networking.** Pods that share the host network namespace cannot be told apart by `--namespace`; use `--cgroup` or the PID.
* **A sidecar proxy** sends on behalf of the application. The transfer is attributed to the proxy's process, so name the intended service by the socket's local port or by the script.
* **Namespaces are reused after a pod restarts**, so a namespace inode identifies a pod only for its lifetime. For long-term attribution, log the PID and cgroup with the transfer.

## Related pages

* [Filter options](https://filetrace.mintlify.site/cli/filters.md) — `--cgroup` and `--namespace` syntax.
* [`filetrace processes`](https://filetrace.mintlify.site/cli/processes) — `--include-children`, rates per process.
* [Data model](https://filetrace.mintlify.site/concepts/data-model.md) — how processes, sockets and transfers link.


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