extras/vpp_stats_fs/README.rst

   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