Writing Applications describes how to combine the API function to build sFlow-RT applications. The REST API, JavaScript API, and System Properties settings allow sFlow-RT to be customized to support a wide variety of use cases. Many examples are described in the sFlow Blog and in downloadable Applications.

Metrics are derived from period sFlow counter records received from Agents and new metrics can be created by Defininig Flows or by sending Custom Metrics.

Note: The following APIs are not final and are subject to change in future releases.

REST API

The following REST commands are available:

URIOperationsDescriptionArguments
/version GETSoftware version number
/analyzer/json GETStatistics describing analyzer performance
/agents/json GET List agents query Used to filter agents, e.g. agent=10.0.0.1&agent=test1 returns information on selected agents
/metrics/json GETList currently active metrics and elapsed time (in mS) since last seen
/metric/{agent}/json GET Retrieve metrics for agent agent: ip address or hostname of agent
/metric/{agent}/{metric}/json GET Retrieve metric agent: list of agent addresses/hostnames e.g. 10.0.0.1;switch1 - the token ALL represents all agents
metric: ordered list of metric names, e.g. load_one,load_five - prefix metric with max:, min:, sum:, avg:, var:, sdev:, med:, q1:, q2:, q3:, iqr: or any: to specify aggregation operation, e.g. max:load_one,min:load_one. Default aggregation max is used if no prefix specified
query: query parameters applied as filter to select agents based on metrics, e.g. os_name=linux&os_name=windows&cpu_num=2&host_name=*web.*
/table/{agent}/{metric}/json GET Tabulate metric values agent: list of agent addresses/hostnames e.g. 10.0.0.1;switch1 the token ALL represents all agents
metric: list of metric names, e.g. host_name,load_one,load_five. The table can be sorted by prefixing a metric name with the token sort:, e.g. sort:load_one:-10 sorts the table by load_one in reverse order (largest to smallest value) and truncates at 10 values.
query: query parameters applied as filter to select agents based on metrics, e.g. os_name=linux&os_name=windows&cpu_num=2&host_name=*web.*
/dump/{agent}/{metric}/json GET Dump metric values agent: list of agent addresses/hostnames e.g. 10.0.0.1;switch1 - the token ALL represents all agents
metric:list of metric names, e.g. load_one;load_five - the token ALL represents all metrics
query: query parameters applied as filter to select agents based on metrics, e.g. os_name=linux&os_name=windows&cpu_num=2&host_name=*web.*
/flowkeys/json GET List currently active flow keys and elapsed time (in mS) since last seen
/flow/json GET List flow definitions
/flow/{name}/json GET, PUT, DELETE Manage flow definition name: name used to identify flow specification
Flow parameters are expressed as JSON object, e.g. {keys:'ipsource,ipdestination', value:'bytes', filter:'ipprotocol=1'}
See Defining Flows for more information.
/activeflows/{agent}/{name}/json GET List top active flows, removing duplicates for flows reported by multiple data sources agent: list of agent addresses/hostnames e.g. 10.0.0.1;switch1 - the token ALL represents all agents and TOPOLOGY represents the agents in the topology
name: name used to identify flow specification
query: set maxFlows to change limit number of flow record returned (default is 100), minValue to only report flows exceeding specified value, aggMode to sum or max to specify how flows are combined (max is default). If a topology is set then aggMode value of EDGE aggregates traffic flowing into the edges switches and CORE aggregates traffic flowing into the core switches from the edge switches. e.g. maxFlows=200&minValue=1000&aggMode=sum returns up to 200 active flows with value >= 1000 and summing values for each flow
/flowvalue/{agent}/{name}/json GET Get value for a specific flow agent: single agent address / hostname, e.g. 10.0.0.1
name: the name used to identify particular data source and flow metric, e.g 22.tcp queries the tcp flows on interface 22
query: the key query parameter is used to specify a flow key, e.g. key=10.0.0.1,10.0.0.2,22,45333
/flowlocations/{agent}/{name}/json GET Get locations that observed a specific flow agent: list of agent addresses / hostnames, e.g. 10.0.0.1;switch1 - the token ALL represents all agents
name: the name used to identify flow metric, e.g tcp queries tcp flows
query: the key query parameter is used to specify a flow key, e.g. key=10.0.0.1,10.0.0.2,22,45333
/flows/json GET List completed flows. Flows will only be logged if log:true is specified in the flow specification. query: used to filter flows, e.g. name=udp&maxFlows=100 returns most recent 100 flows with name=udp, or to block for flows, e.g. flowID=10&maxFlows=100&timeout=60, waits for up to 60 seconds for flows after flowID 10
/groups/json GET List groups and last update times
/group/{name}/json GET, PUT, DELETE Manage IP address groups Groups are used to map IP address ranges to names when defining flows, e.g. {"external":["0.0.0.0/0"], "internal":["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]}
/maps/json GET List flow attribute maps and last update times
/map/{name}/json GET, PUT, DELETE Manage flow attribute maps Map values to categories when defining flows, e.g. to map VLAN values to names {"mgmt":["1"], "web":["80", "81"]}
/threshold/json GET Retrieve thresholds
/threshold/{name}/json GET, PUT, DELETE Manage definition of threshold name: name used to identify threshold specification
Threshold parameters are expressed as JSON object, e.g. {"metric":"load_one", "value":1, "filter":{"os_name":["linux"]}}
metric: metric to apply threshold to, e.g. load_one
value: threshold value, e.g. 1.0
filter: query encoded filter expression consistent with metric query, e.g. {"os_name":["linux"],"cpu_num":["2"]}
byFlow: set to true to generate a new event for each new flow exceeding threshold, otherwise only first flow generates event
timeout: seconds of hysteresis before re-arming threshold, i.e. metric value must be below threshold for timeout seconds.
/events/json GET List events query: Used to filter events, e.g. thresholdID=load&maxEvents=100 returns most recent 100 events generated by threshold "load", or to block for events, e.g. ?eventID=10&maxEvents=100&timeout=60, waits for up to 60 seconds for events after eventID 10
/scripts/json GET Status of scripts loaded at startup. See System Properties and JavaScript Functions
/script/{script}/json GET, POST, PUT, DELETE script specific Defined by script
/forwarding/json GET List sFlow forwarding targets
/forwarding/{name}/json GET, PUT, DELETE Manage sFlow forwarding name: name used to identify sFlow target
Target is expressed as a JSON object, e.g. {address:'10.0.0.1',port:6343}
/topology/json GET,PUT Manage network topology links link objects, e.g. {"link1":{"node1":"sysname1", "port1":"ifname1", "node1":"sysname2", "port2":"ifname2"},...}, where sysname1 and ifname1 are the SNMP sysName and ifName of the port at one end of the link and sysname2 and ifname2 are the names associated with the port at the other end of the link. If devices do not export naming information as part of their sFlow export, then either include nodes information (see below), or enable SNMP (see System Properties).
nodes node objects, e.g. {"sysname1":{"agent":"10.0.0.1", "ports":{"ifname1":{"ifindex":"3"}, ...}}, ...}. The node objects are used to map between sFlow agent addresses and ifIndex numbers and switch and port names.
/tenants/json GET List tenants
/tenant/{name}/json GET, PUT, DELETE Manage tenant configurations name: name used to identify tenant
Tenant settings are expression as a JSON object, e.g. {collectorAddress:"10.0.0.1", collectorPort:6343, filters:{cidr:["10.0.0.0/24"]}}. The tenant will receive an sFlow feed of records matching any of the filters.
Filter types are:
cidr: a list of IPv6 and IPv4 addresses or CIDRs, e.g. ["10.0.0.0/24"]
mac: a list of MAC addresses, e.g. ["D8D385B2DD2B"]
ifindex: a list of switch ports expressed as agent_ifindex strings, e.g. ["10.0.0.1_2"]
ifname: a list of switch ports expressed as agent_ifname strings, e.g. ["10.0.0.1_eth3"]
Note: By default switch port filters only match counter samples. Matching flow samples requires System property tenant.portflows=yes
By default, a topology must be installed so that multi-tenant flow export can be de-duplicated (traffic from inter-switch links will be eliminated). Setting the System property tenant.coreflows=yes disables de-duplication, forwarding data from all ports and removing the dependency on topology.
/bgp/topprefixes/{router}/json GET Query most active IPv4 prefixes router: IP address of router peered with sFlow-RT
query: Set maxPrefixes to specify the maximum number of prefixes in the result. Set minValue to only include entries with a bytes/second value greater than the threshold. Set direction to specify "source" or "destination" traffic. Set includeCovered to "true" to also include prefixes that are covered by the top prefix, but wouldn't otherwise make the list. For example, if 10.1.0.0/16 was includes, then 10.1.3.0/24 would also be included if it were in the set of prefixes advertised by the router. Set pruneCovered to "true" to eliminate covered prefixes that share the same next hop. Set minPrefix to exclude shorter prefixes. For example, minPrefix=1 would exclude 0.0.0.0/0.
/bgp/topprefixes6/{router}/json GET Query most active IPv6 prefixes Same arguments as topprefixes above
/bgp/prefix/{router}/json GET Get prefix associated with address router: IP address of router peering with sFlow-RT
query: Set address to specify an IPv4 or IPv6 address.
/bgp/routepusher/{router}/{cidr-address}/{cidr-bits}/json GET, PUT, DELETE Push BGP routes router: IP address of router peering with sFlow-RT
cidr-address: IP address part of CIDR
cidr-bits: bits part of CIDR
Path parameters are expresses as a JSON encoded object with one or more of the following properties: nexthop, nexthoplinklocal, aspath, origin, communities, med, localpref

JavaScript API

An embedded JavaScript 1.8 engine includes the following additional functions that provide a superset of the capabilities of the REST API:

FunctionDescription
version() GET /version
analyzer() GET /analyzer/json
agents() GET /agents/json
agents([addr1,addr2...]) GET /agents/json?agent=addr1&agent=addr2
metrics() GET /metrics/json
metrics(agent) GET /metric/{agent}/json
metric(agent,metric<,filter>) GET /metric/{agent}/{metric}/json?filter
table(agent,metric<,filter>) GET /table/{agent}/{metric}/json?filter
dump(agent,metric<,filter>) GET /dump/{agent}/{metric}/json?filter
flowKeys() GET /flowkeys/json
activeFlows(agent,name,<maxFlows<,minValue<,aggMode>>>) GET /activeflows/agent/{name}/json
flowValue(agent,name,key) GET /flowvalue/{agent}/{name}/json
flowLocations(agent,name,key) GET /flowlocations/{agent}/{name}/json
setFlow(name,spec) See Defining Flows
clearFlow(name) DELETE /flow/{name}/json
setThreshold(name,spec) PUT /threshold/{name}/json
clearThreshold(name) DELETE /threshold/{name}/json
boolean = thresholdTriggered(name,agent,metric<,key>) Returns true if threshold is currently triggered. Metric name must include data source, e.g. "2.bytes". Optionally include specific flow key if threshold definition sets byFlow flag.
object = datasourceInfo(agent,dataSource) Get information about data source polling and sampling.
setFlowHandler(function(flowrec)<,[name1,name2..]>) GET /flows/json
clearFlowHandler()
setEventHandler(function(event)<,[eventID1,eventID2..]>) GET /events/json
clearEventHandler()
setIntervalHandler(function()<,seconds>) Calls the function at regular intervals specified by seconds (default value is 1, i.e. every second)
clearIntervalHandler()
setHttpHandler(function(request)) GET,POST,PUT,DELETE /script/name/json. The request object has the following format: {method:'GET'|'POST'|'PUT'|'DELETE', query:{key:[val1,val2..],..}, body:object}. The object returned by the function will be JSON encoded and must not have any circular references.
clearHttpHandler()
setGroups(name,spec) PUT /group/{name}/json
setMap(name,spec) PUT /map/{name}/json
include(file) Include javascript file
scriptdir() Returns directory containing this script
logFine(string) log FINE level message, see Logger.fine()
logInfo(string) log INFO level message, see Logger.info()
logWarning(string) log WARNING level message, see Logger.warning()
logSevere(string) log SEVERE level message, see Logger.severe()
value=getenv(name) Get the value of an environment variable.
value=getSystemProperty(name) Get the value of a System Property.
string=formatDate(date,formatString<,language<,country>>) Format a JavaScript Date object, see formatString, language and country.
string=formatNumber(number,formatString<,language<,country>>) Format a JavaScript number, see formatString, language and country.
result=runCmd(cmd[]<,envp[]<,dir>>)
runCmdAsync({cmd:,envp:,dir:,error:function(),success:function()})
See Java Runtine.exec
result.status the integer status code
result.stdout an array of strings containing lines of output from command
result.stderr an array of strings containing lines of error message from the command
http(url)
http(url,'get'<,user,password<,accept>>)
http(url,'put'|'post'|'delete',contentType,content<,user,password<,accept>>)
http2({url:,operation:,body:,user:,password:,headers:{}})
httpAsync({url:,operation:,body:,user:,password:,headers:{},error:function(),success:function()})
Interact with remote entities using HTTP protocol
object = storeGet(key) Get value from persistent store
storeSet(key,object) Save object in persistent store
storeDelete(key) Delete value from persistent store
array = storeKeys() Returns list of keys from persistent store
object = sharedGet(key) Get value from shared volatile store
sharedSet(key,object) Save object to shared volatile store
sharedDelete(key) Delete value from shared volatile store
array = sharedKeys() Returns list of keys from shared volatile store
string=md5(string) Calculate md5 hash of string
string=base64Encode(string<,newlines>) Base64 encode a string, inserting newlines every 76 characters if newlines flag is true.
string=base64Decode(string) Base64 decode a string
cidr=mask(ipaddress,number) Apply a mask to an IP address and return result in CIDR notation. e.g. mask("10.0.0.5",24) return "10.0.0.0/24"
array=ipRangeToCidrList(start,end) Return an array of CDIRs representing an IP address range, e.g. ipRangeToCidrList("10.0.0.0","10.0.0.32") returns ["10.0.0.0/27","10.0.0.32/32"]
graphite(server,port|null,metrics) Send a set of metrics to specified Graphite server using text protocol over TCP. Default port is 2003 and metrics is an object containing name,value pairs, e.g. {metric1:100,metric2:0.12}. Periodic metrics are typicall sent within the intervalHandler function.
syslog(server,port|null,facility|null,severity|null,params) Send an event to a specified syslog server over UDP. Default port is 514, default facility is 16 (local0), default severity is 5 (Notice), and params contains name/value pairs, e.g. {source:"10.0.0.1",frameRate:1000}
setForward(name,address<,port>) PUT /forwarding/{name}/json
clearForward(name) DELETE /forwarding/{name}/json
setTopology(spec) PUT /topology/json
spec = getTopology() GET /topology/json
number = topologyVersion() Returns version number associated with current topology
array = topologyLinkNames() Returns link names
array = topologyNodeNames() Returns node names
link = topologyLink(name) Get link
node = topologyNodePortNames(name) Get list of port names associated with node
array = topologyTags() Get a list of tags associated with topology
boolean = topologyNodeHasTag(node,tag) Test if node has tag
boolean = topologyPortHasTag(node,port,tag) Test if port has tag
boolean = topologyLinkHasTag(link,tag) Test if link has tag
number = topologyDiameter() Calculate graph diameter
array = topologyShortestPath(name1,name2) Calculate shortest path between node name1 and node name2
array = topologyShortestPaths(name1,name2,k,<,n>) Calculate k shortest paths with an optional path length limit of n
array = topologyMinimumSpanningTree() Calculate minimum spanning tree
obj = topologyNodeLinks(name) Return links connected to node
array = topologyNodePortNames(node) Return array of named of connected ports for node
obj = topologyInterfaceToLink(agent,ifIndex) Lookup the link based on sFlow agent and ifIndex
obj = topologyInterfaceToPort(agent,ifIndex) Lookup the node and port name based on sFlow agent and ifIndex
obj = topologyPortToInterface(node,port) Lookup the sFlow agent and ifIndex based on node and port name
obj = topologyLinkToInterfaces(name) Lookup interfaces attached to link
array = topologyNodesForAgent(agent) Return array of node names associated with sFlow agent
obj = topologyAgentForNode(node) Return the sFlow agent reporting on node
array = topologyLocatedHostMacs() Return a list of host MAC addresses that have been located to access ports
array = topologyLocateHostMac(macaddress) Return information about switch port(s) connected to host
array = topologyLocateHostAgent(agent) Return information about switch port(s) connected to Host sFlow agent
array = topologyLocateHostUUID(uuid) Return information about switch port(s) connected to Host sFlow agent
array = topologyLocateHostIP(addr) Return information about switch port(s) connected to host IP address
array = topologyLocateHostIP6(addr) Return information about switch port(s) connected to host IPv6 address
array = topologyLinkMetric(name,metric<,node>) Get metrics associated with interfaces at each end of link. Optionally indicate direction by naming start node
string = ifName(agent,ifIndex) Get interface name associated with agent and SNMP ifIndex
setTenant(name,collectorAddress,collectorPort,filters) GET,PUT,DELETE /tenant/{name}/json
bgpTopPrefixes(router, maxPrefixes, minValue, direction, includeCovered, minPrefix, pruneCovered) GET /bgp/topprefixes/{router}/json
bgpTopPrefixes6(router, maxPrefixes, minValue, direction, includeCovered, minPrefix, pruneCovered) GET /bgp/topprefixes6/{router}/json
bgpPrefixForAddress(router, address) GET /bgp/prefix/{router}/json
bgpAddNeighbor(router, AS<, ID<, {as4:true,ipv6:false}<,openFn, closeFn>>>) Peer with router IPv4 or IPv6 address. Specify local AS number (e.g. 65001), optionally local ID (e.g. "0.0.0.1"), BGP options, and connection open/close notification functions.
bgpRemoveNeighbor(router) End peering session with router.
bgpAddSource(agent,router,<t,<value>>) Direct sFlow from agent to router's prefix list, where t is smoothing factor (in seconds) and value is "bytes" or "frames"
bgpRemoveSource(agent) Stop directing sFlow from agent to router
bgpAddRoute(router, {prefix:, nexthop:, aspath:, origin:, communities:, med:, localpref:}) PUT /bgp/routepusher/{router}/{cidr-address}/{cidr-bits}/json
bgpRemoveRoute(router,prefix) DELETE /bgp/routepusher/{router}/{cidr-address}/{cidr-bits}/json
bgpAddFlow(router, {match:{version:, source:, destination:, protocol:, port:, destination-port:, source-port:, icmp-type:, icmp-code:, tcp-flags:, length:, dscp:, fragment:}, then:{traffic-rate:, traffic-action:, redirect:, traffic-marking:, communities:}}) Push FlowSpec to router. Each FlowSpec contains one or more match fields and one or more then actions.
bgpRemoveFlow(router, {match:{...},then:{...}}) Remove previously pushed FlowSpec.
bgpReceivedFlows(router) Get list of FlowSpec records received.
baselineCreate(name<,window<sensitivity<,repeat>>>) Create a new baseline object for calculating long term statistics. The window parameter (default 120) determines how many updates to compute statistics over. The sensitivity parameter (default 2) determines the multiple of standard deviations used to identify outliers. The repeat parameter (default 1) determines the number of sequential data points that must exceed the standard deviation threshold before considering the metric value an anomaly.
status = baselineCheck(name,value) Update the named baseline with a new metric value and return a status (learning, normal, high, low)
obj = baselineStatistics(name) Get mean, variance, sdev, min, and max values for the named baseline
baselineReset(name) Reset the statistics for the named baseline
baselineDelete(name) Delete the named baseline and free associated resources
obj = hostForMAC(mac) Get agent and data source associated with host MAC address
obj = hostForIP(ip) Get agent and data source associated with host IP address
obj = hostForIP6(ip6) Get agent and data source associated with host IPv6 address

System Properties

The System Properties can be specified in the RTPROP environment variable before running the start.sh script, e.g.:

env "RTPROP=-Dhttp.hostname=127.0.0.1 -Dhttp.port=8080" ./start.sh

On the docker command line:

docker run -e "RTPROP=-Dbgp.start=yes" -p 6343:6343/udp -p 8008:8008 sflow/sflow-rt

If sFlow-RT was installed as an RPM or DEB package, edit the /usr/local/sflow-rt/conf.d/sflow-rt.conf file and restart the sflow-rt service.

PropertyDefaultDescription
http.hostnameBind HTTP server to specified address
http.port8008TCP port to receive HTTP requests
http.lognoSet to yes to enable http request logging
http.htmlyesSet to no to exclude HTML pages
http.html.redirect./html/index.htmlDefault page to display
http.readonlynoSet to yes to prevent POST/PUT operations from modifying thresholds, flows, and groups
http.restyesSet to no to disable REST API if HTML pages are disabled.
http.requestheadersize4096Size of the buffer to be used for request headers
http.requestbuffersize8192Size of the content buffer for receiving requests
http.responseheadersize4096Size of the buffer to be used for response headers
http.responsebuffersize32768Size of the content buffer for sending responses
http.timeout.connect5000Timeout in milliseconds for JavaScript HTTP client
http.timeout.read5000Timeout in milliseconds for JavaScript HTTP client
script.fileComma separated list of JavaScript files to load at startup, see JavaScript Functions. Use http.readonly=yes to prevent modification of settings installed by scripts
script.storestoreDirectory for storing persistent objects for scripts
script.maxeventqueue1000Maximum number of events per script queue
script.maxflowqueue1000Maximum number of flow records per script queue
sflow.port6343UDP port to receive sFlow
sflow.hostnameBind sFlow listener to specific address
sflow.filePlayback sFlow from pcap file (disables sflow.port)
sflow.dsentitytoportyesSet to no to allow entity packet samplers instead of converting them to virtual ingress port-based data sources
sflow.sumegressnoSet to yes to create virtual egress sampled data sources from ingress only sampled data
sflow.rcvpktsbuffer1000Number of 2028 byte packet buffers to request when opening the sFlow UDP socket
events.max1000Maximum number of events to keep
flows.max1000Maximum number of completed flows to keep
geo.countryGeoIP database location. Set to resources/config/GeoIP.dat to use GeoLite database
geo.asnGeoIP database location. Set to resources/config/GeoIPASNum.dat to use GeoLite database
geo.country6GeoIP database location. Set to resources/config/GeoIPv6.dat to use GeoLite database
geo.asn6GeoIP database location. Set to resources/config/GeoIPASNumv6.dat to use GeoLite database
oui.namesOUI name file. Set to resources/config/oui.txt to lookup names
workers.maxqueue400Maximum number of sFlow datagrams to queue per worker
workers.number4Number of worker threads processing sFlow datagrams
snmp.ifnamenoSet to yes to enable SNMP retrieval of interface names
snmp.version2cSNMP version number, valid options are 1, 2c, or 3
snmp.communitypublicSet SNMP community string
snmp.userSet SNMP user
snmp.authprotocolSet SNMP authentication protocol, valid options are md5 or sha
snmp.authpasswdSet SNMP authentication password
snmp.privprotocolSet SNMP privacy protocol, valid options are des, 3des, aes128, aes192 or aes256
snmp.privpasswdSet SNMP privacy password
tenant.portflowsnoSet to yes to apply tenant port filters to flow samples in addition to counter samples
tenant.coreflowsnoSet to yes to allow export of data from all ports (including internal inter-switch links
bgp.startnoSet to yes to enable BGP listener
bgp.port1179TCP port for BGP listener
bgp.hostnameBind BGP listener to specific address
dns.serversComma separated list of DNS servers or "resolv.conf" to read server addresses from /etc/resolv.conf file.
dns.port53UDP port to make DNS requests
dns.maxpending100Maximum number of outstanding DNS requrests
dns.timeout5Maximum number of seconds to wait for a DNS reply
dns.cache.size100000Maximum number of DNS replies to cache
dns.cache.minexpires600Minimum number of seconds to remember positive DNS response - overrides short DNS TTL values
dns.cache.negativettl3600Number of seconds to remember a negative DNS response
apps.enableyesEnable applications
apps.discoveryesAutomatically discover and run applications in the apps directory
app.{name}.enablenoIf apps.discover=no, then selectively enable application by setting app.{name}.enable=yes
host.ip.enableyesDiscover IP address associated with host adapter
host.ip.refresh10Number of seconds before refreshing IP address to host adapter relationship