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).
7 The following requirements are required to run this example:
9 - install **VPP 18.10+**
10 - enable stats in VPP:
18 > The [default socket](https://wiki.fd.io/view/VPP/Command-line_Arguments#.22statseg.22_parameters) is located at `/run/vpp/stats.sock`.
19 - run the VPP (ideally with some traffic)
23 First build the example: `go build git.fd.io/govpp.git/examples/stats-api`.
25 ### Higher-level access to stats
27 Use commands following commands to retrieve stats that are aggregated and
28 processed into logical structures from [api package](../../api).
30 - `system` to retrieve system statistics
31 - `nodes` to retrieve per node statistics
32 - `interfaces` to retrieve per interface statistics
33 - `errors` to retrieve error statistics (you can use patterns to filter the errors)
37 Following command will retrieve system stats.
40 System stats: &{VectorRate:0 InputRate:0 LastUpdate:32560 LastStatsClear:0 Heartbeat:3255}
45 Following command will retrieve per node stats.
50 - {NodeIndex:554 Clocks:0 Vectors:0 Calls:0 Suspends:0}
51 - {NodeIndex:555 Clocks:189609 Vectors:15 Calls:15 Suspends:0}
52 - {NodeIndex:556 Clocks:2281847 Vectors:0 Calls:0 Suspends:21}
53 - {NodeIndex:557 Clocks:0 Vectors:0 Calls:0 Suspends:0}
54 - {NodeIndex:558 Clocks:0 Vectors:0 Calls:0 Suspends:0}
55 - {NodeIndex:559 Clocks:7094 Vectors:0 Calls:1 Suspends:1}
56 - {NodeIndex:560 Clocks:88159323916601 Vectors:0 Calls:14066116 Suspends:0}
57 - {NodeIndex:561 Clocks:0 Vectors:0 Calls:0 Suspends:0}
58 - {NodeIndex:562 Clocks:0 Vectors:0 Calls:0 Suspends:0}
59 - {NodeIndex:563 Clocks:0 Vectors:0 Calls:0 Suspends:0}
60 - {NodeIndex:564 Clocks:447894125 Vectors:0 Calls:0 Suspends:32395}
61 - {NodeIndex:565 Clocks:1099655497824612 Vectors:0 Calls:40 Suspends:117}
62 - {NodeIndex:566 Clocks:0 Vectors:0 Calls:0 Suspends:0}
63 - {NodeIndex:567 Clocks:0 Vectors:0 Calls:0 Suspends:0}
64 - {NodeIndex:568 Clocks:0 Vectors:0 Calls:0 Suspends:0}
65 - {NodeIndex:569 Clocks:0 Vectors:0 Calls:0 Suspends:0}
66 - {NodeIndex:570 Clocks:0 Vectors:0 Calls:0 Suspends:0}
67 - {NodeIndex:571 Clocks:0 Vectors:0 Calls:0 Suspends:0}
68 - {NodeIndex:572 Clocks:0 Vectors:0 Calls:0 Suspends:0}
69 Listed 573 node counters
74 Following command will retrieve per interface stats.
76 $ ./stats-api interfaces
77 Listing interface stats..
78 - {InterfaceIndex:0 RxPackets:0 RxBytes:0 RxErrors:0 TxPackets:0 TxBytes:0 TxErrors:0 RxUnicast:[0 0] RxMulticast:[0 0] RxBroadcast:[0 0] TxUnicastMiss:[0 0] TxMulticast:[0 0] TxBroadcast:[0 0] Drops:0 Punts:0 IP4:0 IP6:0 RxNoBuf:0 RxMiss:0}
79 - {InterfaceIndex:1 RxPackets:0 RxBytes:0 RxErrors:0 TxPackets:0 TxBytes:0 TxErrors:0 RxUnicast:[0 0] RxMulticast:[0 0] RxBroadcast:[0 0] TxUnicastMiss:[0 0] TxMulticast:[0 0] TxBroadcast:[0 0] Drops:5 Punts:0 IP4:0 IP6:0 RxNoBuf:0 RxMiss:0}
80 - {InterfaceIndex:2 RxPackets:0 RxBytes:0 RxErrors:0 TxPackets:0 TxBytes:0 TxErrors:0 RxUnicast:[0 0] RxMulticast:[0 0] RxBroadcast:[0 0] TxUnicastMiss:[0 0] TxMulticast:[0 0] TxBroadcast:[0 0] Drops:0 Punts:0 IP4:0 IP6:0 RxNoBuf:0 RxMiss:0}
81 - {InterfaceIndex:3 RxPackets:0 RxBytes:0 RxErrors:0 TxPackets:0 TxBytes:0 TxErrors:0 RxUnicast:[0 0] RxMulticast:[0 0] RxBroadcast:[0 0] TxUnicastMiss:[0 0] TxMulticast:[0 0] TxBroadcast:[0 0] Drops:0 Punts:0 IP4:0 IP6:0 RxNoBuf:0 RxMiss:0}
82 Listed 4 interface counters
87 Following command will retrieve error stats.
88 Use flag `-all` to include stats with zero values.
90 $ ./stats-api errors ip
91 Listing error stats.. ip
92 - {ip4-input/ip4 spoofed local-address packet drops 15}
93 Listed 1 (825) error counters
96 ### Low-level access to stats
98 Use commands `ls` and `dump` to list and dump statistics in their raw format
99 from [adapter package](../../adapter).
100 Optionally, patterns can be used to filter the results.
104 Following command will list stats matching patterns `/sys/` and `/if/`.
106 $ ./stats-api ls /sys/ /if/
107 Listing stats.. /sys/ /if/
111 - /sys/last_stats_clear
130 - /if/tx-unicast-miss
138 Following command will dump stats with their types and actual values.
139 Use flag `-all` to include stats with zero values.
143 - /sys/last_update ScalarIndex 10408
144 - /sys/heartbeat ScalarIndex 1041
145 - /err/ip4-icmp-error/unknown type ErrorIndex 5
146 - /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}]]
147 - /if/drops SimpleCounterVector [[0 5 5]]
148 Dumped 5 (2798) stats