---
title: top_file
sidebar_position: 0
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# top_file

The top_file gadget reports periodically the read/write activity by file.

## Requirements

- Minimum Kernel Version : 5.6

## Getting started

Running the gadget:

<Tabs groupId="env">
    <TabItem value="kubectl-gadget" label="kubectl gadget">
        ```bash
        $ kubectl gadget run ghcr.io/inspektor-gadget/gadget/top_file:%IG_TAG% [flags]
        ```
    </TabItem>

    <TabItem value="ig" label="ig">
        ```bash
        $ sudo ig run ghcr.io/inspektor-gadget/gadget/top_file:%IG_TAG% [flags]
        ```
    </TabItem>
</Tabs>

## Flags

### `--all-files`

Trace all files types. By default, only regular files are traced

Default value: "false"

### `--pid`

Show only events generated by process with this PID

Default value: "0"

## Guide

This example shows how to use this gadget. To do so, we will run an application
that performs some disk I/O activity.

Before starting our application, let's start our `top_file` gadget to be sure it
captures all the events from the beginning:

<Tabs groupId="env">
    <TabItem value="kubectl-gadget" label="kubectl gadget">
        ```bash
        $ kubectl gadget run top_file:%IG_TAG% --pod mypod
        K8S.NODE     K8S.NAMESPACE          K8S.PODNAME            K8S.CONTAINERNAME               PID  READS RBYT… WRIT… WBYT… FILE                  COMM             T
        ```
    </TabItem>

    <TabItem value="ig" label="ig">
        ```bash
        $ sudo ig run top_file:%IG_TAG% --containername test-top-file
        RUNTIME.CONTAINERNAME                                 PID      READS     RBYTES    WRITES    WBYTES FILE                                COMM             T
        ```
    </TabItem>
</Tabs>

The `T` column indicates the type of the file: `R` for regular files, `S` for
sockets, and `O` for other (including pipes). By default only regular files are
shown; use the `--all-files` option to show all file types.

In another terminal, let's create our application. It'll install `git` and then
clone the linux source code:

<Tabs groupId="env">
    <TabItem value="kubectl-gadget" label="kubectl gadget">
        ```bash
        kubectl run -it mypod --rm --image ubuntu -- /bin/sh -c "apt-get update && apt-get install -y git && git clone https://github.com/torvalds/linux"
        ```
    </TabItem>

    <TabItem value="ig" label="ig">
        ```bash
        docker run --rm --name test-top-file ubuntu /bin/sh -c "apt-get update && apt-get install -y git && git clone https://github.com/torvalds/linux"
        ```
    </TabItem>
</Tabs>

We can see how the `top_file` terminal shows the files that are read and written
by the application. The `File` field shows the absolute path of the file being
accessed. For instance, `http`, `apt-get` and `apt-config` are reading a lot
of files when updating the packages list and installing packages:

<Tabs groupId="env">
    <TabItem value="kubectl-gadget" label="kubectl gadget">
        ```bash
		K8S.NAMESPACE               K8S.PODNAME                 K8S.CONTAINERNAME                       PID    READS  RBYTES  WRITES  WBYTES FILE                       COMM            K8S.NODE
        default                     mypod                       mypod                               1786428       64  262144       0       0 /var/lib/apt/lists/archiv… apt-get         minikube
        default                     mypod                       mypod                               1786428       10  589883       0       0 /var/lib/apt/lists/securi… apt-get         minikube
        default                     mypod                       mypod                               1786428        2  110977       0       0 /var/lib/apt/lists/securi… apt-get         minikube
        default                     mypod                       mypod                               1786428        6   24576       0       0 /etc/group                 apt-get         minikube
        default                     mypod                       mypod                               1786730        3    2400       0       0 /usr/lib/x86_64-linux-gnu… dpkg            minikube
        default                     mypod                       mypod                               1786428     1494 977912…       0       0 /var/lib/apt/lists/archiv… apt-get         minikube
        default                     mypod                       mypod                               1786608        3   21287       0       0 /var/lib/apt/lists/partia… store           minikube
        default                     mypod                       mypod                               1786730        1     832       0       0 /usr/lib/x86_64-linux-gnu… dpkg            minikube
        default                     mypod                       mypod                               1786730        2    8192       0       0 /etc/dpkg/dpkg.cfg         dpkg            minikube
        default                     mypod                       mypod                               1786608        0       0      28  722475 /var/lib/apt/lists/partia… store           minikube
        default                     mypod                       mypod                               1786608        0       0      28  589765 /var/lib/apt/lists/partia… store           minikube
        default                     mypod                       mypod                               1786608       74  602300       0       0 /var/lib/apt/lists/partia… store           minikube
        default                     mypod                       mypod                               1786608     2049 167783…       0       0 /var/lib/apt/lists/partia… store           minikube
        default                     mypod                       mypod                               1786608        0       0       2   17989 /var/lib/apt/lists/partia… store           minikube
        default                     mypod                       mypod                               1786608        0       0      40  973998 /var/lib/apt/lists/partia… store           minikube
        default                     mypod                       mypod                               1786608        4   32284       0       0 /var/lib/apt/lists/partia… store           minikube
        default                     mypod                       mypod                               1786729        3    2400       0       0 /usr/lib/x86_64-linux-gnu… rm              minikube
        default                     mypod                       mypod                               1786428       10  649015       0       0 /var/lib/apt/lists/archiv… apt-get         minikube
        default                     mypod                       mypod                               1786428        4  197340       0       0 /var/lib/apt/lists/archiv… apt-get         minikube
        default                     mypod                       mypod                               1786428      188 123166…       0       0 /var/lib/apt/lists/archiv… apt-get         minikube
        ...
        ```
    </TabItem>

    <TabItem value="ig" label="ig">
        ```bash
		RUNTIME.CONTAINERNAME                                                PID         READS       RBYTES       WRITES       WBYTES FILE                                          COMM             T
        test-top-file                                                      23607             1          832            0            0 /usr/lib/x86_64-linux-gnu/libxxhash.so.0.8.2  http             R
        test-top-file                                                      23609             1          832            0            0 /usr/lib/x86_64-linux-gnu/libbz2.so.1.0.4     http             R
        test-top-file                                                      23609             1          832            0            0 /usr/lib/x86_64-linux-gnu/libzstd.so.1.5.5    http             R
        test-top-file                                                      23608             1          832            0            0 /usr/lib/x86_64-linux-gnu/libffi.so.8.1.4     http             R
        test-top-file                                                      23605             3        11889            0            0 /etc/apt/apt.conf.d/01autoremove              apt-get          R
        test-top-file                                                      23605             3        12288            0            0 /etc/passwd                                   apt-get          R
        test-top-file                                                      23607             3         2400            0            0 /usr/lib/x86_64-linux-gnu/libc.so.6           http             R
        test-top-file                                                      23609             1          832            0            0 /usr/lib/x86_64-linux-gnu/libgnutls.so.30.37… http             R
        test-top-file                                                      23608             1          832            0            0 /usr/lib/x86_64-linux-gnu/libcap.so.2.66      http             R
        test-top-file                                                      23605             1          832            0            0 /usr/lib/x86_64-linux-gnu/libcap.so.2.66      apt-get          R
        test-top-file                                                      23607             1          832            0            0 /usr/lib/x86_64-linux-gnu/libzstd.so.1.5.5    http             R
        test-top-file                                                      23608             1         4096            0            0 /etc/passwd                                   http             R
        test-top-file                                                      23606             2         2048            0            0 /proc/filesystems                             dpkg             R
        ...
        test-top-file                                                      23680             3        12261            0            0 /etc/apt/apt.conf.d/docker-disable-periodic-… apt-config       R
        test-top-file                                                      23656             2        16382            0            0 /usr/share/dpkg/tupletable                    apt-config       R
        test-top-file                                                      23689             1          832            0            0 /usr/lib/x86_64-linux-gnu/libz.so.1.3         apt-config       R
        test-top-file                                                      23655             2         2048            0            0 /proc/filesystems                             dpkg             R
        test-top-file                                                      23609             1        65536           14        19964 /var/lib/apt/lists/partial/archive.ubuntu.co… http             R
        test-top-file                                                      23647             1          832            0            0 /usr/lib/x86_64-linux-gnu/libgcc_s.so.1       gpgv             R
        test-top-file                                                      23653             1          832            0            0 /usr/lib/x86_64-linux-gnu/libmd.so.0.1.0      dpkg             R
        test-top-file                                                      23685             1          832            0            0 /usr/lib/x86_64-linux-gnu/libpcre2-8.so.0.11… dpkg             R
        test-top-file                                                      23684             3        12106            0            0 /etc/apt/apt.conf.d/70debconf                 apt-config       R
        ...
        ```
    </TabItem>
</Tabs>

After the initial installation is done, we can see how git uses a temporary file
to store the repository being cloned.

<Tabs groupId="env">
    <TabItem value="kubectl-gadget" label="kubectl gadget">
        ```bash
        K8S.NAMESPACE               K8S.PODNAME                 K8S.CONTAINERNAME                       PID    READS  RBYTES  WRITES  WBYTES FILE                                      COMM            K8S.NODE
        default                     mypod                       mypod                               1799742      266   81944       0       0 /linux/.git/objects/pack/tmp_pack_dzzrva  git             minikube
	    ```
    </TabItem>

    <TabItem value="ig" label="ig">
        ```bash
        RUNTIME.CONTAINERNAME                                                PID         READS       RBYTES       WRITES       WBYTES FILE                                          COMM             T
        test-top-file                                                      27959             0            0          804      3293184 /linux/.git/objects/pack/tmp_pack_UPu2eM      git              R
         ```
    </TabItem>
</Tabs>

By default the `top_file` gadget prints a summary each second until users press
Ctrl + C. Both the number of summaries and the interval can be customized using
`--map-fetch-count` and `--map-fetch-interval` flags, respectively. For example,
with the following values, the gadget will run for 10 seconds in total, printing
5 summaries every 2 seconds:

<Tabs groupId="env">
    <TabItem value="kubectl-gadget" label="kubectl gadget">
        ```bash
        kubectl gadget run top_file:%IG_TAG% --map-fetch-count 5 --map-fetch-interval 2s
        ```
    </TabItem>

    <TabItem value="ig" label="ig">
        ```bash
        sudo ig run top_file:%IG_TAG% --map-fetch-count 5 --map-fetch-interval 2s
        ```
    </TabItem>
</Tabs>
