examples/cmd/stats-api/README.md

   1 # Stats API Example
   2
   3 This example demonstrates how to retrieve statistics from VPP using [the new Stats API](https://github.com/FDio/vpp/blob/master/src/vpp/stats/stats.md).
   4
   5 ## Requirements
   6
   7 The following requirements are required to run this example:
   8
   9 - install **VPP 18.10+**
  10 - enable stats in VPP:
  11
  12   ```sh
  13   statseg {
  14         default
  15   }
  16   ```
  17   > The [default socket](https://wiki.fd.io/view/VPP/Command-line_Arguments#.22statseg.22_parameters) is located at `/run/vpp/stats.sock`.
  18 - run the VPP, ideally with some traffic
  19
  20 ## Running example
  21
  22 First build the example: `go build git.fd.io/govpp.git/examples/cmd/stats-api`.
  23
  24 Use commands `ls` and `dump` to list and dump statistics. Optionally, patterns can be used to filter the results.
  25
  26 ### List stats matching patterns `/sys/` and `/if/`
  27 ```
  28 $ ./stats-api ls /sys/ /if/
  29 Listing stats.. /sys/ /if/
  30  - /sys/vector_rate
  31  - /sys/input_rate
  32  - /sys/last_update
  33  - /sys/last_stats_clear
  34  - /sys/heartbeat
  35  - /sys/node/clocks
  36  - /sys/node/vectors
  37  - /sys/node/calls
  38  - /sys/node/suspends
  39  - /if/drops
  40  - /if/punt
  41  - /if/ip4
  42  - /if/ip6
  43  - /if/rx-no-buf
  44  - /if/rx-miss
  45  - /if/rx-error
  46  - /if/tx-error
  47  - /if/rx
  48  - /if/rx-unicast
  49  - /if/rx-multicast
  50  - /if/rx-broadcast
  51  - /if/tx
  52  - /if/tx-unicast-miss
  53  - /if/tx-multicast
  54  - /if/tx-broadcast
  55 Listed 25 stats
  56 ```
  57
  58 ### Dump all stats with their types and values
  59 ```
  60 $ ./stats-api dump
  61 Dumping stats..
  62  - /sys/last_update                       ScalarIndex 10408
  63  - /sys/heartbeat                         ScalarIndex 1041
  64  - /err/ip4-icmp-error/unknown type        ErrorIndex 5
  65  - /net/route/to                CombinedCounterVector [[{Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:0 Bytes:0} {Packets:5 Bytes:420}]]
  66  - /if/drops                      SimpleCounterVector [[0 5 5]]
  67 Dumped 5 (2798) stats
  68 ```