This article is an interactive tutorial intended to familiarize the reader with the REST API. The examples can be run on a laptop using recorded data so that access to a live network is not required.
The data was captured from the leaf and spine test network shown above (described in Fabric View).
curl -O https://raw.githubusercontent.com/sflow-rt/fabric-view/master/demo/ecmp.pcapFirst, download the captured sFlow data.
You will need to have a system with Java or Docker to run the sFlow-RT software.
curl -O https://inmon.com/products/sFlow-RT/sflow-rt.tar.gz tar -xzf sflow-rt.tar.gz ./sflow-rt/get-app.sh sflow-rt browse-metrics ./sflow-rt/get-app.sh sflow-rt browse-flows ./sflow-rt/get-app.sh sflow-rt prometheus ./sflow-rt/start.sh -Dsflow.file=$PWD/ecmp.pcapThe above commands download and run sFlow-RT, with browse-metrics, browse-flows, and prometheus applications on a system with Java 1.8+ installed.
docker run --rm -v $PWD/ecmp.pcap:/sflow-rt/ecmp.pcap \ -p 8008:8008 --name sflow-rt sflow/prometheus -Dsflow.file=ecmp.pcapAlternatively, the above command runs sFlow-RT and applications using Docker.
Each of the examples can be run in a terminal window using curl, or you can simply click on the link to see the results in your web browser.
curl http://localhost:8008/agents/jsonList the sFlow agents.
curl http://localhost:8008/metrics/jsonList the names of the metrics being exported by the agents. The available metrics depend on the types of agent streaming data to sFlow-RT. For a list of supported sFlow metrics, see Metrics.
curl http://localhost:8008/metric/ALL/max:ifinutilization,max:ifoututilization/jsonFind the switch ports with the highest input and output utilization.
The metric query walks the table and returns a value that summarizes each metric in a comma separated list. The following summary statistics are supported:
- max: Maximum value
- min: Smallest value
- sum: Total value
- avg: Average value
- var: Variance
- sdev: Standard deviation
- med: Median value
- q1: First quartile
- q2: Second quartile (same as med:)
- q3: Third quartile
- iqr: Inter-quartile range (i.e. q3 - q1)
http://localhost:8008/app/browse-metrics/html/index.html?metric=ifinutilizationThe following examples show how to retrieve metric values without summarization.
curl http://localhost:8008/table/ALL/ifinutilization,ifoututilization/jsonGet a table of input and output utilization for every switch port. The table query doesn't summarize metrics. Instead, the query returns rows from the logical table that include the metrics specified in the query.
curl http://localhost:8008/dump/ALL/ALL/jsonDump all metric values for all agents. The dump query is similar to the table query, but instead of walking the table row by row, individual metrics are traversed in their internal order.
curl http://localhost:8008/prometheus/metrics/ALL/ALL/txtDump all metric values in Prometheus Exporter format. For example, the Grafana sFlow-RT Network Interfaces dashboard makes use of the query to populate the Prometheus time series database.
There are two types of measurement carried by sFlow: periodically exported counters and randomly sampled packets. So far the examples have been querying metrics derived from the counters.
curl http://localhost:8008/flowkeys/jsonGet the list of attributes that are being extracted from sampled packet headers. The available attributes depend on the type of traffic flowing in the network. For a list of supported packet attributes, see Defining Flows.
curl -H "Content-Type:application/json" -X PUT \
--data '{"keys":"ipsource,ipdestination",value:"bytes"}' \
http://localhost:8008/flow/srcdst/json
Define a new "flow" metric called srcdst that calculates the bytes per second between each pair of communicating IP addresses on the network.curl http://localhost:8008/metric/ALL/max:srcdst/jsonFind the maximum value of the newly defined srcdst flow metric, i.e. the switch port on the network observing the highest bandwidth flow of packets.
[{
"agent": "192.168.0.12",
"metricName": "max:srcdst",
"topKeys": [
{
"lastUpdate": 1274,
"value": 3.392739739066506E8,
"key": "10.4.3.2,10.4.4.2"
},
{
"lastUpdate": 2352,
"value": 2.155296894816872E8,
"key": "10.4.1.2,10.4.2.2"
}
],
"metricN": 10,
"lastUpdate": 1275,
"lastUpdateMax": 2031,
"metricValue": 3.392739739066506E8,
"dataSource": "4",
"lastUpdateMin": 1267
}]
In addition to providing a metric value, the result also includes topKeys, showing the top flows seen at the switch port.
http://localhost:8008/app/browse-metrics/html/index.html?metric=srcdstThere are additional queries specific to flow metrics.
curl http://localhost:8008/activeflows/ALL/srcdst/jsonFind the largest flows gathered from all the interfaces in the network.
[
{
"flowN": 7,
"agent": "192.168.0.12",
"value": 5.537867023642346E8,
"dataSource": "4",
"key": "10.4.1.2,10.4.2.2"
},
{
"flowN": 6,
"agent": "192.168.0.11",
"value": 5.1034569007443213E8,
"dataSource": "38",
"key": "10.4.3.2,10.4.4.2"
},
{
"flowN": 6,
"agent": "192.168.0.11",
"value": 1469003.6788768284,
"dataSource": "4",
"key": "10.4.4.2,10.4.3.2"
},
{
"flowN": 7,
"agent": "192.168.0.12",
"value": 1306006.2405022713,
"dataSource": "37",
"key": "10.4.2.2,10.4.1.2"
}
]
Each flow returned identifies the number of locations it was observed and the port with the maximum value. For example, the largest flow from 10.4.1.2 to 10.4.2.2 was seen by 7 data sources and its maximum value 5.5e8 was observed by data source 4 on agent 192.168.0.12.
http://localhost:8008/app/browse-flows/html/index.html?keys=ipsource,ipdestination&value=bpsNote how quickly the graph changes as it tracks new elephant flows in real time.
See RESTflow for a more detailed discussion of sFlow-RT's flow REST API.
This tutorial has just scratches the surface of the capabilities of sFlow-RT's analytics engine. The Writing Applications tutorial provides further examples and a discussion of how to build applications using Python and JavaScript, see Real-time DDoS mitigation using BGP RTBH and FlowSpec, Fabric View and Flow metrics with Prometheus and Grafana for examples of sFlow-RT applications.
Seeing your own data is more interesting than a canned demonstration. Network Equipment lists devices that support sFlow. Ubuntu 18.04 and CentOS 8 describe how to install the open source Host sFlow agent on popular Linux distributions, extending visibility into compute and cloud infrastructure. The Host sFlow agent is also available as a Docker image for easy deployment with container orchestration systems, see Host, Docker, Swarm and Kubernetes monitoring.
Even if you don't have access to a production environment, the Docker testbed and Kubernetes testbed examples show how to build a virtual testbed using Docker Desktop. Alternatively, Mininet flow analytics and Mininet dashboard provide starting points if you want to experiment with software defined networking (SDN).
Finally, join the sFlow-RT community to ask questions and share solutions and operational experience.
