summaryrefslogtreecommitdiffstats
path: root/extras/vpp_stats_fs/README.md
diff options
context:
space:
mode:
authorArthur de Kerhor <arthurdekerhor@gmail.com>2021-03-24 07:32:07 -0700
committerBeno�t Ganne <bganne@cisco.com>2021-06-03 07:25:04 +0000
commit9cfbd3b7869db3ca5131c6fd0c0f77b787fa4312 (patch)
tree2c43941190db870ccb73a54df420756197bd330c /extras/vpp_stats_fs/README.md
parent2f64790c596036877d1fc70a1cae0f96b655af19 (diff)
misc: bug fixes and improvements for stats Fuse fs
Added syslogs Added support for symlinks Relocated make commands in a local Makefile Dumping stats on index instead of paths Updated README Added go.mod and go.sum with relevant dependencies for the module Type: fix Change-Id: I2c91317939b2f4d765771ab7038372ae27d3109d Signed-off-by: Arthur de Kerhor <arthurdekerhor@gmail.com>
Diffstat (limited to 'extras/vpp_stats_fs/README.md')
-rwxr-xr-xextras/vpp_stats_fs/README.md98
1 files changed, 75 insertions, 23 deletions
diff --git a/extras/vpp_stats_fs/README.md b/extras/vpp_stats_fs/README.md
index c5ec8127d8a..52610feba94 100755
--- a/extras/vpp_stats_fs/README.md
+++ b/extras/vpp_stats_fs/README.md
@@ -1,61 +1,113 @@
# VPP stats segment FUSE filesystem {#stats_fs_doc}
The statfs binary allows to create a FUSE filesystem to expose and to browse the stats segment.
-Is is leaned on the Go-FUSE library and requires Go-VPP stats bindings to work.
+It relies on the Go-FUSE library and requires Go-VPP stats bindings to work.
The binary mounts a filesystem on the local machine whith 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 regularly update their contents so that new counters get added to the filesystem.
+Directories update their contents on epoch changes so that new counters get added to the filesystem.
-## Prerequisites (for building)
+The script `install.sh` is responsible for buildiing and installing the filesystem.
-**GoVPP** library (master branch)
-**Go-FUSE** library
-vpp, vppapi
+## Usage
-## Building
+The local Makefile contains targets for all the possible intercations with the stats_f binary.
-Here, we add the Go librairies before building the binary
+### Help
+A basic help menu
```bash
-go mod init stats_fs
-go get git.fd.io/govpp.git@master
-go get git.fd.io/govpp.git/adapter/statsclient@master
-go get github.com/hanwen/go-fuse/v2
-go build
+make help
```
-## Usage
+### Install
+Building the binary
+```bash
+make install
+```
-The basic usage is:
+### Start
+Starts the filesystem. Requires a running VPP instance using the default socket /run/vpp/stats.sock.
+
+May require a privileged user (sudo)
```bash
-sudo ./statfs <MOUNT_POINT> &
+make start
+```
+
+### Stop
+Stops and unmounts the filesystem if it is not busy.
+
+May require a privileged user (sudo)
+```bash
+make stop
+```
+
+### Force unmount
+Forces the unmount of the filesystem even if it is busy.
+
+May require a privileged user (sudo)
+```bash
+make force-unmount
+```
+
+### Cleanup
+Cleaning stats_fs binary.
+
+May require a privileged user (sudo).
+```bash
+make clean
```
-**Options:**
- - debug \<true|false\> (default is false)
- - socket \<statSocket\> (default is /run/vpp/stats.sock)
## Browsing the filesystem
+The default mountpoint is /run/vpp/stats_fs_dir.
You can browse the filesystem as a regular user.
Example:
```bash
-cd /path/to/mountpoint
+cd /run/vpp/stats_fs_dir
cd sys/node
ls -al
cat names
```
-## Unmounting the file system
+## 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:
+```bash
+go build
+```
+
+### Mounting
+Then, ou can mount the filesystem with the local binary.
+
+May require a privileged user (sudo).
+
+The basic usage is:
+```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)
+
```bash
-sudo fusermount -u /path/to/mountpoint
+fusermount -u /path/to/mountpoint
```
To force the unmount even if the resource is busy, add the -z option:
```bash
-sudo fusermount -uz /path/to/mountpoint
+fusermount -uz /path/to/mountpoint
```