Network Observability with SuzieQ: Part Three
Unlock network insights effortlessly with SuzieQ's powerful data interaction tools.
In part 2 of this multipart series on network observability with SuzieQ, we looked at how to setup SuzieQ using docker compose. In this part, we will look at how to interact with the data collected by SuzieQ using the command line interface (CLI) and its REST API.
If you have not read Part One and Part Two yet, I recommend you read it first before proceeding with this part.
SuzieQ CLI
SuzieQ provides a command line interface to interact with the data it has collected. Like any Linux CLI, SuzieQ CLI providers command completion when options are available and also provides help for each command. All commands follow a common structure <table_name> <verb> <filters>. This will make more sense when we start looking at some examples.
Let us start by running the SuzieQ CLI. If you have been following along with the previous parts, you should have the SuzieQ docker container running and you can connect to the SuzieQ CLI by running the docker attach suzieq_cli command. Once you are connected, you will see a prompt like this suzieq>. This is the SuzieQ CLI prompt.
root@sudarshanv:/suzieq/suzieq# docker attach suzieq_cli
suzieq>Connecting to SuzieQ CLI
From here you can get help by running the help command. This will show you all the commands available in the SuzieQ CLI. You can also get help for a specific command by running help <command>. For example, to get help for the bgp command, you can run help bgp.
suzieq> help
+-----------+-----------------------------------------------------------------+
| Command | Description |
+-----------+-----------------------------------------------------------------+
| ? | help |
| address | Act on interface addresses |
| arpnd | Act on ARP/ND data |
| bgp | Act on BGP data |
| clear | clear certain contexts for subsequent commands. Cmd is additive |
| devconfig | Act on device data |
| device | Act on device data |
| evpnVni | Act on EVPN VNI data |
| fs | Act on File System data |
| help | help |
| interface | Act on Interface data |
| inventory | Act on inventory data |
| lldp | Act on LLDP data |
| mac | Act on MAC Table data |
| mlag | Act on mlag data |
| namespace | Summarize namespace-wide network data |
| network | Act on network-wide data |
| ospf | Act on OSPF data |
| path | build and act on path data |
| route | Act on Routes |
| set | set certain contexts for subsequent commands. Cmd is additive |
| sqPoller | Act on SqPoller data |
| table | get data about data captured for various tables |
| topcpu | Act on topcpu data |
| topmem | Act on topmem data |
| topology | build and act on topology data |
| version | print the suzieq version |
| vlan | Act on vlan data |
+-----------+-----------------------------------------------------------------+
Built-in Commands
+----------+------------------------------------------------------------------+
| Command | Description |
+----------+------------------------------------------------------------------+
| :verbose | Prints or changes verbosity level, accepts integer or True/False |
| connect | Start the interactive mode |
| exit | Exits the program |
| q | Exits the program |
| quit | Exits the program |
+----------+------------------------------------------------------------------+
Use help <name of command/service> [<verb>] to get more help
For example: help route or help route show
suzieq>
Output of help command
Tables
SuzieQ stores the data collected in tables. You can get a list of all the tables by running the table show command. This will show you all the tables available in SuzieQ.
suzieq> table show
table firstTime lastTime intervals allRows namespaceCnt deviceCnt
0 arpnd 2024-06-15 07:44:35.543000+10:00 2024-06-15 07:44:35.577000+10:00 2 10 1 3
1 bgp 2024-06-15 07:44:36.172000+10:00 2024-06-15 07:44:40.130000+10:00 3 54 1 3
2 devconfig 2024-06-15 07:44:35.892000+10:00 2024-06-15 07:44:37.266000+10:00 3 3 1 3
3 device 2024-06-15 07:44:39.723000+10:00 2024-06-15 07:44:41.746000+10:00 3 3 1 3
4 interfaces 2024-06-15 07:44:36.378000+10:00 2024-06-15 07:44:40.462000+10:00 3 311 1 3
5 inventory 2024-06-15 07:44:36.302000+10:00 2024-06-15 07:44:40.284000+10:00 3 72 1 3
6 lldp 2024-06-15 07:44:35.931000+10:00 2024-06-15 07:44:37.348000+10:00 3 8 1 3
7 macs 2024-06-15 07:44:37.313000+10:00 2024-06-15 11:21:50.331000+10:00 5 28 1 3
8 ospfIf 2024-06-15 07:44:39.921000+10:00 2024-06-15 07:44:39.921000+10:00 1 7 1 1
9 ospfNbr 2024-06-15 07:44:37.383000+10:00 2024-06-15 07:44:37.383000+10:00 1 1 1 1
10 routes 2024-06-15 07:44:39.802000+10:00 2024-06-15 07:44:41.800000+10:00 3 240 1 3
11 sqPoller 2024-06-15 07:44:35.562000+10:00 2024-06-15 11:30:40.229000+10:00 2226 2227 1 3
12 vlan 2024-06-15 07:44:36.044000+10:00 2024-06-15 07:44:39.809000+10:00 3 39 1 3
13 TOTAL 2024-06-15 07:44:35.543000+10:00 2024-06-15 11:30:40.229000+10:00 2226 3003 1 3
suzieq>List of all available table
You can get data from a specific table by running the <table_name> show command. For example, to get data from the bgp table, you can run bgp show.
suzieq> bgp show
namespace hostname vrf peer peerHostname state afi safi asn peerAsn pfxRx pfxTx numChanges estdTime
0 ilab lab-rt-600 default 172.16.127.134 lab-rce-600 Established ipv4 label-unicast 10148 64604 0 0 3 2024-02-14 07:44:36.173000+11:00
1 ilab lab-rt-600 default 172.16.127.134 lab-rce-600 Established ipv4 unicast 10148 64604 0 0 3 2024-02-14 07:44:36.199000+11:00
2 ilab lab-rce-600 VRF-EXTERNAL 172.16.69.19 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
3 ilab lab-rce-600 VRF-EXTERNAL 172.16.69.35 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
4 ilab lab-rce-600 VRF-EXTERNAL 172.16.127.140 NotEstd vpnv4 unicast 64604 10148 0 0 0 1970-01-01 10:00:00+10:00
5 ilab lab-rce-600 VRF-EXTERNAL 172.16.127.142 NotEstd vpnv4 unicast 64604 10148 0 0 0 1970-01-01 10:00:00+10:00
6 ilab lab-rce-600 VRF-EXTERNAL 172.16.127.144 NotEstd vpnv4 unicast 64604 10148 0 0 0 1970-01-01 10:00:00+10:00
7 ilab lab-rce-600 VRF-EXTERNAL 192.101.254.117 NotEstd vpnv4 unicast 64604 64604 0 0 0 1970-01-01 10:00:00+10:00
8 ilab lab-rce-600 VRF-PROTECTED 172.16.127.133 lab-rt-600 Established vpnv4 unicast 64604 10148 0 0 1 2024-02-14 07:44:40.131000+11:00
9 ilab lab-rce-600 VRF-PROTECTED 172.16.127.150 lab-rpe-600 Established vpnv4 unicast 64604 64603 0 0 1 2024-02-14 07:44:40.131000+11:00
10 ilab lab-rce-600 VRF-PROTECTED 172.16.127.152 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
11 ilab lab-rce-600 VRF-PROTECTED 172.16.127.170 lab-rpe-600 Established vpnv4 unicast 64604 64603 0 0 1 2024-02-14 07:44:40.131000+11:00Output of bgp show
Querying Data
Now that you have a basic understanding of the SuzieQ CLI, let's look at how to query the data collected by SuzieQ. SuzieQ provides a powerful query language that allows you to filter and aggregate data.Again the best way to understand the query language is to use it.
Let's start by running a simple query to get the data from the bgp table. Say for instance you want to get information about the BGP sessions that are in the NotEstd state. You can run the following query:
suzieq> bgp show state=NotEstd
namespace hostname vrf peer peerHostname state afi safi asn peerAsn pfxRx pfxTx numChanges estdTime
0 ilab lab-rce-600 VRF-EXTERNAL 172.16.69.19 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
1 ilab lab-rce-600 VRF-EXTERNAL 172.16.69.35 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
2 ilab lab-rce-600 VRF-EXTERNAL 172.16.127.140 NotEstd vpnv4 unicast 64604 10148 0 0 0 1970-01-01 10:00:00+10:00
3 ilab lab-rce-600 VRF-EXTERNAL 172.16.127.142 NotEstd vpnv4 unicast 64604 10148 0 0 0 1970-01-01 10:00:00+10:00
4 ilab lab-rce-600 VRF-EXTERNAL 172.16.127.144 NotEstd vpnv4 unicast 64604 10148 0 0 0 1970-01-01 10:00:00+10:00
5 ilab lab-rce-600 VRF-EXTERNAL 192.101.254.117 NotEstd vpnv4 unicast 64604 64604 0 0 0 1970-01-01 10:00:00+10:00
6 ilab lab-rce-600 VRF-PROTECTED 172.16.127.152 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
7 ilab lab-rce-600 VRF-PROTECTED 172.16.127.172 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
8 ilab lab-rce-600 VRF-PROTECTED 172.16.127.178 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
9 ilab lab-rce-600 VRF-PROTECTED 172.16.127.180 NotEstd vpnv4 unicast 64604 64603 0 0 0 1970-01-01 10:00:00+10:00
10 ilab lab-rce-600 VRF-PROTECTED 192.101.254.119 NotEstd vpnv4 unicast 64604 64604 0 0 0 1970-01-01 10:00:00+10:00You can also query data over a time range, and you can do that by using natural query spec which is a way to specify a time range in a human-readable format. For example, to get the BGP data from a particular host over the last day, you can run the following query:
suzieq> bgp show hostname=lab-rt-600 start-time="1 day ago" end-time="1 min ago"
active namespace hostname vrf peer peerHostname state afi safi asn peerAsn pfxRx pfxTx numChanges estdTime timestamp
0 + ilab lab-rt-600 default 172.16.127.134 lab-rce-600 Established ipv4 unicast 10148 64604 0 0 3 2024-02-14 07:44:36.199000+11:00 2024-06-15 07:44:36.172000+10:00
1 + ilab lab-rt-600 default 172.16.127.134 lab-rce-600 Established ipv4 label-unicast 10148 64604 0 0 3 2024-02-14 07:44:36.173000+11:00 2024-06-15 07:44:36.172000+10:00
2 + ilab lab-rt-600 default 172.16.127.134 adminDown ipv4 label-unicast 10148 64604 0 0 4 1970-01-01 10:00:00+10:00 2024-06-15 12:22:23.018000+10:00
3 + ilab lab-rt-600 default 172.16.127.134 adminDown ipv4 unicast 10148 64604 0 0 4 1970-01-01 10:00:00+10:00 2024-06-15 12:22:23.018000+10:00
4 + ilab lab-rt-600 default 172.16.127.134 lab-rce-600 Established ipv4 label-unicast 10148 64604 0 0 5 2024-06-15 12:09:23.858000+10:00 2024-06-15 12:23:23.856000+10:00
5 + ilab lab-rt-600 default 172.16.127.134 lab-rce-600 Established ipv4 unicast 10148 64604 0 0 5 2024-06-15 12:09:23.858000+10:00 2024-06-15 12:23:23.856000+10:00
suzieq>Example of using natural language for time
Assertions
SuzieQ also performs assertions for some of the data it collects. More on the assertions can be found in the SuzieQ documentation. SuzieQ runs a number of checks for the service and providing a pass or fail. It adds a column assertReason to the output of the query to show the reason for the assertion result. Lets look at an example of the interface table:
suzieq> interface assert
namespace hostname ifname state peerHostname peerIfname result assertReason
0 ilab lab-rt-600 AppGigabitEthernet1/0/1 up fail [No Peer Found]
1 ilab lab-rt-600 GigabitEthernet0/0 up lab-gw-sw GigabitEthernet1/0/41 fail [No Peer Found]
2 ilab lab-rt-600 TenGigabitEthernet1/0/47 up lab-rce-600 GigabitEthernet5/48 fail [MTU mismatch]
3 ilab lab-rt-600 TenGigabitEthernet1/0/48 up fail [No Peer Found]
4 ilab lab-rt-600 Vlan1 up pass -
5 ilab lab-rce-600 GigabitEthernet5/1 up sddc-lab-mgmt-sw GigabitEthernet1/0/45 fail [No Peer Found]
6 ilab lab-rce-600 GigabitEthernet5/48 up lab-rt-600 TenGigabitEthernet1/0/47 fail [MTU mismatch]
7 ilab lab-rce-600 TenGigabitEthernet1/6 up lab-rpe-600 TenGigabitEthernet1/6.3000 fail [No Peer Found]
8 ilab lab-rce-600 TenGigabitEthernet1/6.3000 up lab-rpe-600 TenGigabitEthernet1/6.3000 fail [No Peer Found]
9 Example of an assertion
SuzieQ REST API
SuzieQ also provides a REST API that allows you to interact with the data collected by SuzieQ programmatically. The REST API provides endpoints to query the data, run assertions, and more similar to the CLI.The REST API documentation can be accessed by visiting the /api/docs endpoint of the SuzieQ REST Container. For example, if you are running SuzieQ using docker-compose, you can access the REST API documentation by visiting http://localhost:8000/api/docs. It lands you on a swagger UI page where you can see all the endpoints available in the SuzieQ REST API.
You can try out the endpoints directly from the Swagger UI by using the API key set in the configuration file. It also provides the curl command to try out the endpoints. Below is a screenshots of the Swagger UI.
Wrapping Up
Wrapping up this part, we looked at how to interact with SuzieQ using the command line interface (CLI) and its REST API. We saw how to query the data collected by SuzieQ using the CLI and how to run assertions. We also looked at how to access the REST API documentation and try out the endpoints using the swagger UI.
With this we have just scratched the surface of what SuzieQ can do, the possibilities of what information you can get from the data collected by SuzieQ are endless. You would have to try it for yourself to see the full potential of SuzieQ and how it can help you in your day-to-day work.
