aboutsummaryrefslogtreecommitdiffstats
path: root/extras/vpp_stats_fs/README.rst
diff options
context:
space:
mode:
authorNathan Skrzypczak <nathan.skrzypczak@gmail.com>2021-10-08 14:05:58 +0200
committerDave Wallace <dwallacelf@gmail.com>2021-10-13 15:32:22 +0000
commita2c9509a4ab22380937a2b613fcc518da22f5166 (patch)
tree93e0629de82c99ca4b1f9802083cf9362f1dc325 /extras/vpp_stats_fs/README.rst
parent8acc5ee9079d0b03229a72e72a5308e7de0a359a (diff)
docs: convert extras doc md->rst
Type: improvement Change-Id: Ie3b25a86b99098d2b3a21a11fc73234c8ed589d6 Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Diffstat (limited to 'extras/vpp_stats_fs/README.rst')
-rw-r--r--extras/vpp_stats_fs/README.rst148
1 files changed, 148 insertions, 0 deletions
diff --git a/extras/vpp_stats_fs/README.rst b/extras/vpp_stats_fs/README.rst
new file mode 100644
index 00000000000..d6635d146c0
--- /dev/null
+++ b/extras/vpp_stats_fs/README.rst
@@ -0,0 +1,148 @@
+.. _stats_fs_doc:
+
+VPP stats segment FUSE filesystem
+=================================
+
+The statfs binary allows to create a FUSE filesystem to expose and to
+browse the stats segment. It relies on the Go-FUSE library and requires
+Go-VPP stats bindings to work.
+
+The binary mounts a filesystem on the local machine with the data from
+the stats segments. The counters can be opened and read as files
+(e.g. in a Unix shell). Note that the value of a counter is determined
+when the corresponding file is opened (as for /proc/interrupts).
+
+Directories update their contents on epoch changes so that new counters
+get added to the filesystem.
+
+The script ``install.sh`` is responsible for building and installing
+the filesystem.
+
+Usage
+-----
+
+The local Makefile contains targets for all the possible interactions
+with the stats_f binary.
+
+Help
+~~~~
+
+A basic help menu
+
+.. code:: bash
+
+ make help
+
+Install
+~~~~~~~
+
+Building the binary
+
+.. code:: bash
+
+ make install
+
+Start
+~~~~~
+
+Starts the filesystem. Requires a running VPP instance using the default
+socket /run/vpp/stats.sock.
+
+May require a privileged user (sudo)
+
+.. code:: bash
+
+ make start
+
+Stop
+~~~~
+
+Stops and unmounts the filesystem if it is not busy.
+
+May require a privileged user (sudo)
+
+.. code:: bash
+
+ make stop
+
+Force unmount
+~~~~~~~~~~~~~
+
+Forces the unmount of the filesystem even if it is busy.
+
+May require a privileged user (sudo)
+
+.. code:: bash
+
+ make force-unmount
+
+Cleanup
+~~~~~~~
+
+Cleaning stats_fs binary.
+
+May require a privileged user (sudo).
+
+.. code:: bash
+
+ make clean
+
+Browsing the filesystem
+-----------------------
+
+The default mountpoint is /run/vpp/stats_fs_dir. You can browse the
+filesystem as a regular user. Example:
+
+.. code:: bash
+
+ cd /run/vpp/stats_fs_dir
+ cd sys/node
+ ls -al
+ cat names
+
+Building and mounting the filesystem manually
+---------------------------------------------
+
+For more modularity, you can build and mount the filesystem manually.
+
+Building
+~~~~~~~~
+
+Inside the local directory, you can build the go binary:
+
+.. code:: bash
+
+ go build
+
+Mounting
+~~~~~~~~
+
+Then, you can mount the filesystem with the local binary.
+
+May require a privileged user (sudo).
+
+The basic usage is:
+
+.. code:: bash
+
+ ./stats_fs <MOUNT_POINT>
+
+**Options:** - debug <true|false> (default is false) - socket
+<statSocket> (default is /run/vpp/stats.sock) : VPP socket for stats
+
+Unmounting the file system
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can unmount the filesystem with the fusermount command.
+
+May require a privileged user (sudo)
+
+.. code:: bash
+
+ fusermount -u /path/to/mountpoint
+
+To force the unmount even if the resource is busy, add the -z option:
+
+.. code:: bash
+
+ fusermount -uz /path/to/mountpoint