extras/vpp_stats_fs/README.md

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