| Nathan Skrzypczak | a2c9509 | 2021-10-08 14:05:58 +0200 | [diff] [blame] | 1 | .. _stats_fs_doc: |
| 2 | |
| 3 | VPP stats segment FUSE filesystem |
| 4 | ================================= |
| 5 | |
| 6 | The statfs binary allows to create a FUSE filesystem to expose and to |
| 7 | browse the stats segment. It relies on the Go-FUSE library and requires |
| 8 | Go-VPP stats bindings to work. |
| 9 | |
| 10 | The binary mounts a filesystem on the local machine with the data from |
| 11 | the stats segments. The counters can be opened and read as files |
| 12 | (e.g. in a Unix shell). Note that the value of a counter is determined |
| 13 | when the corresponding file is opened (as for /proc/interrupts). |
| 14 | |
| 15 | Directories update their contents on epoch changes so that new counters |
| 16 | get added to the filesystem. |
| 17 | |
| 18 | The script ``install.sh`` is responsible for building and installing |
| 19 | the filesystem. |
| 20 | |
| 21 | Usage |
| 22 | ----- |
| 23 | |
| 24 | The local Makefile contains targets for all the possible interactions |
| 25 | with the stats_f binary. |
| 26 | |
| 27 | Help |
| 28 | ~~~~ |
| 29 | |
| 30 | A basic help menu |
| 31 | |
| 32 | .. code:: bash |
| 33 | |
| 34 | make help |
| 35 | |
| 36 | Install |
| 37 | ~~~~~~~ |
| 38 | |
| 39 | Building the binary |
| 40 | |
| 41 | .. code:: bash |
| 42 | |
| 43 | make install |
| 44 | |
| 45 | Start |
| 46 | ~~~~~ |
| 47 | |
| 48 | Starts the filesystem. Requires a running VPP instance using the default |
| 49 | socket /run/vpp/stats.sock. |
| 50 | |
| 51 | May require a privileged user (sudo) |
| 52 | |
| 53 | .. code:: bash |
| 54 | |
| 55 | make start |
| 56 | |
| 57 | Stop |
| 58 | ~~~~ |
| 59 | |
| 60 | Stops and unmounts the filesystem if it is not busy. |
| 61 | |
| 62 | May require a privileged user (sudo) |
| 63 | |
| 64 | .. code:: bash |
| 65 | |
| 66 | make stop |
| 67 | |
| 68 | Force unmount |
| 69 | ~~~~~~~~~~~~~ |
| 70 | |
| 71 | Forces the unmount of the filesystem even if it is busy. |
| 72 | |
| 73 | May require a privileged user (sudo) |
| 74 | |
| 75 | .. code:: bash |
| 76 | |
| 77 | make force-unmount |
| 78 | |
| 79 | Cleanup |
| 80 | ~~~~~~~ |
| 81 | |
| 82 | Cleaning stats_fs binary. |
| 83 | |
| 84 | May require a privileged user (sudo). |
| 85 | |
| 86 | .. code:: bash |
| 87 | |
| 88 | make clean |
| 89 | |
| 90 | Browsing the filesystem |
| 91 | ----------------------- |
| 92 | |
| 93 | The default mountpoint is /run/vpp/stats_fs_dir. You can browse the |
| 94 | filesystem as a regular user. Example: |
| 95 | |
| 96 | .. code:: bash |
| 97 | |
| 98 | cd /run/vpp/stats_fs_dir |
| 99 | cd sys/node |
| 100 | ls -al |
| 101 | cat names |
| 102 | |
| 103 | Building and mounting the filesystem manually |
| 104 | --------------------------------------------- |
| 105 | |
| 106 | For more modularity, you can build and mount the filesystem manually. |
| 107 | |
| 108 | Building |
| 109 | ~~~~~~~~ |
| 110 | |
| 111 | Inside the local directory, you can build the go binary: |
| 112 | |
| 113 | .. code:: bash |
| 114 | |
| 115 | go build |
| 116 | |
| 117 | Mounting |
| 118 | ~~~~~~~~ |
| 119 | |
| 120 | Then, you can mount the filesystem with the local binary. |
| 121 | |
| 122 | May require a privileged user (sudo). |
| 123 | |
| 124 | The basic usage is: |
| 125 | |
| 126 | .. code:: bash |
| 127 | |
| 128 | ./stats_fs <MOUNT_POINT> |
| 129 | |
| 130 | **Options:** - debug <true|false> (default is false) - socket |
| 131 | <statSocket> (default is /run/vpp/stats.sock) : VPP socket for stats |
| 132 | |
| 133 | Unmounting the file system |
| 134 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 135 | |
| 136 | You can unmount the filesystem with the fusermount command. |
| 137 | |
| 138 | May require a privileged user (sudo) |
| 139 | |
| 140 | .. code:: bash |
| 141 | |
| 142 | fusermount -u /path/to/mountpoint |
| 143 | |
| 144 | To force the unmount even if the resource is busy, add the -z option: |
| 145 | |
| 146 | .. code:: bash |
| 147 | |
| 148 | fusermount -uz /path/to/mountpoint |