sFlow-RT Reference

Writing Applications describes how to combine the API function to build sFlow-RT applications. Topology describes how to extend the capabilities by importing network topology. The JavaScript API, REST 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 periodic sFlow counter records received from Agents and new metrics can be created by Defining Flows or by sending Custom Metrics.

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

JavaScript API

The embedded JavaScript ES6 engine includes the following additional functions:

Server

Get statistics for sFlow agent(s).

parameter	type	description
selected	Array[String]	List of agent addresses (optional)

Returns

Object

Example

Get statistics for all sFlow agents.

var stats = agents();
logInfo(JSON.stringify(stats,null,1));

Result:

2021-08-19T18:34:42Z INFO: {
 "10.0.0.252": {
  "sFlowDatagramsLost": 0,
  "sFlowDatagramSource": [
   "172.17.0.1"
  ],
  "sFlowNotificationSamples": 0,
  "sFlowFlowDuplicateSamples": 0,
  "sFlowDatagramsReceived": 2,
  "sFlowNotificationDrops": 0,
  "sFlowFlowSamples": 0,
  "sFlowDatagramsOutOfOrder": 0,
  "sFlowNotificationDuplicateSamples": 0,
  "sFlowFlowDrops": 0,
  "sFlowFlowLostSamples": 0,
  "sFlowNotificationLostSamples": 0,
  "sFlowCounterSamples": 0,
  "sFlowFlowDatasources": 1,
  "sFlowCounterOutOfOrderSamples": 0,
  "sFlowNotificationOutOfOrderSamples": 0,
  "firstSeen": 247,
  "sFlowCounterDatasources": 1,
  "sFlowFlowOutOfOrderSamples": 0,
  "sFlowNotificationDatasources": 0,
  "uptime": 1234519704,
  "sFlowCounterDuplicateSamples": 0,
  "lastSeen": 243,
  "sFlowDatagramsDuplicates": 1,
  "sFlowCounterLostSamples": 0
 },
 "10.0.0.172": {
  "sFlowDatagramsLost": 0,
  "sFlowDatagramSource": [
   "172.17.0.1"
  ],
  "sFlowNotificationSamples": 0,
  "sFlowFlowDuplicateSamples": 0,
  "sFlowDatagramsReceived": 2,
  "sFlowNotificationDrops": 0,
  "sFlowFlowSamples": 0,
  "sFlowDatagramsOutOfOrder": 0,
  "sFlowNotificationDuplicateSamples": 0,
  "sFlowFlowDrops": 0,
  "sFlowFlowLostSamples": 0,
  "sFlowNotificationLostSamples": 0,
  "sFlowCounterSamples": 0,
  "sFlowFlowDatasources": 0,
  "sFlowCounterOutOfOrderSamples": 0,
  "sFlowNotificationOutOfOrderSamples": 0,
  "firstSeen": 219,
  "sFlowCounterDatasources": 4,
  "sFlowFlowOutOfOrderSamples": 0,
  "sFlowNotificationDatasources": 0,
  "uptime": 1561481175,
  "sFlowCounterDuplicateSamples": 0,
  "lastSeen": 219,
  "sFlowDatagramsDuplicates": 1,
  "sFlowCounterLostSamples": 0
 }
}

Get statistics for specific agents.

var stats = agents(['10.0.0.252']);
logInfo(JSON.stringify(stats,null,1));

Result:

2021-08-19T18:38:58Z INFO: {
 "10.0.0.252": {
  "sFlowDatagramsLost": 0,
  "sFlowDatagramSource": [
   "172.17.0.1"
  ],
  "sFlowNotificationSamples": 0,
  "sFlowFlowDuplicateSamples": 0,
  "sFlowDatagramsReceived": 2,
  "sFlowNotificationDrops": 0,
  "sFlowFlowSamples": 0,
  "sFlowDatagramsOutOfOrder": 0,
  "sFlowNotificationDuplicateSamples": 0,
  "sFlowFlowDrops": 0,
  "sFlowFlowLostSamples": 0,
  "sFlowNotificationLostSamples": 0,
  "sFlowCounterSamples": 0,
  "sFlowFlowDatasources": 2,
  "sFlowCounterOutOfOrderSamples": 0,
  "sFlowNotificationOutOfOrderSamples": 0,
  "firstSeen": 75,
  "sFlowCounterDatasources": 1,
  "sFlowFlowOutOfOrderSamples": 0,
  "sFlowNotificationDatasources": 0,
  "uptime": 1234775774,
  "sFlowCounterDuplicateSamples": 0,
  "lastSeen": 74,
  "sFlowDatagramsDuplicates": 1,
  "sFlowCounterLostSamples": 0
 }
}

Get statistics describing analyzer performance.

Returns

Object

Example

var stats = analyzer();
logInfo(JSON.stringify(stats,null,1));

Result:

2021-08-19T18:41:24Z INFO: {
 "httpMessagesSent": 0,
 "nonHeapCommitted": 28639232,
 "javaVersion": "11.0.11",
 "sFlowDatagramsReceived": 2,
 "eventsGenerated": 0,
 "nonHeapInit": 7667712,
 "httpBytesReceived": 0,
 "sFlowParseErrors": 0,
 "httpMessagesReceived": 0,
 "httpBytesSent": 0,
 "flowsGenerated": 0,
 "cpuLoadProcess": 0,
 "sFlowBytesReceived": 1624,
 "cpuTime": 3660,
 "gcTime": 0,
 "cpuLoadSystem": 0.5,
 "jvmName": "OpenJDK 64-Bit Server VM",
 "threadDaemonCount": 10,
 "sFlowUnsupportedVersion": 0,
 "loadAverage": 0.39111328125,
 "heapCommitted": 1073741824,
 "updateAvailable": false,
 "httpConnectionsCurrent": 0,
 "httpConnectionsTotal": 0,
 "sFlowDatagramsDiscarded": 0,
 "heapUsed": 85983232,
 "jvmVendor": "Alpine",
 "availableProcessors": 12,
 "memFree": 29056565248,
 "gcCount": 0,
 "memTotal": 33674657792,
 "threadCount": 21,
 "nonHeapMax": -1,
 "version": "3.0-1606",
 "uptime": 1934,
 "sFlowAgents": 1,
 "nonHeapUsed": 24605664,
 "heapMax": 1073741824,
 "jvmVersion": "11.0.11+9-alpine-r0",
 "threadTotalStartedCount": 23,
 "heapInit": 1073741824
}

Get information about data source polling and sampling.

parameter	type	description
agent	String	Agent IP address
datasource	String	Datasource index

Returns

Object

Example

var stats = datasourceInfo('10.0.0.231','10');
logInfo(JSON.stringify(stats,null,1));

Result

2021-08-23T22:04:40Z INFO: {
 "counterSamplesLost": 0,
 "samplingDirection": "bidirectional",
 "samplingRate": 2000,
 "dropProbability": 0,
 "flowSamples": 20,
 "flowSamplesLost": 0,
 "effectiveSamplingRate": 2000,
 "counterSamples": 28,
 "effectivePollingInterval": 34683.84615772708
}

Get the sFlow-RT software version number.

Returns

String

Example

var ver = version();
logInfo(ver);

Result:

2021-08-19T18:43:33Z INFO: 3.0-1606

Metrics

Update the named baseline with a new metric value and return a status.

parameter	type	description
name	String	Name of baseline
value	Number	Metric value

Returns

String. 'learning', 'normal', 'high', or 'low'

Throws

Exception for missing or malformed arguments or if baseline doesn't exist

Example

baselineCreate('load');
setIntervalHandler(function(now) {
 let val = metric('ALL','sum:load_one');
 let status = baselineCheck('load', val[0].metricValue || 0);
 switch(status) {
   case 'learning':
     break;
   case 'normal':
     break;
   case 'high':
     logWarning('load over baseline');
     break;
   case 'low':
     logWarning('load below baseline');
     break;
 }
}, 1);

Create a new baseline object for calculating long term statistics.

parameter	type	description
name	String	Name of new baseline
window	Number	Number of updates to compute statistics over (optional, default 120)
sensitivity	Number	Multiple of standard deviation used to identify outliers (optional, default 2)
repeat	Number	Number of sequential data points that must exceed the standard deviation threshold before considering the metric value an anomaly (optional, default 1)

Throws

Exception for missing or malformed arguments or if baseline already exists

Example

baselineCreate('load',600,3,2);

Delete the named baseline and free associated resources

parameter	type	description
name	String	Name of baseline

Example

baselineDelete('load');

Reset the statistics for the named baseline

parameter	type	description
name	String	Name of baseline

Example

baselineReset('load');

Get mean, variance, sdev, min, and max values for the named baseline

parameter	type	description
name	String	Name of baseline

Returns

Object

Example

baselineCreate('load');
setIntervalHandler(function(now) {
 let val = metric('ALL','sum:load_one');
 let status = baselineCheck('load', val[0].metricValue || 0);
 let stats = baselineStatistics('load');
 logInfo(JSON.stringify(stats,null,1));
}, 1);

Result:

{
 "mean": 0.017811619819249013,
 "variance": 0.00003897858783710143,
 "sdev": 0.0062432834179701815,
 "min": 0.00532505298330865,
 "max": 0.030298186655189376
}

Remove interval handler function.

Example

clearIntevalHandler();

Get metric values

parameter	type	description
agents	String	'ALL', 'TOPOLOGY', 'EDGE', 'CORE', or comma separated list of agent addresses
metrics	String	Comma separated list of metric names. e.g. `load_one,load_five`
filter	Object	Select data sources based on attributes (optional)

Returns

Array[Object]

Example

var stats = dump('ALL','ifinoctets,ifoutoctets',{os_name:['linux'],ifname:['swp*']});
logInfo(JSON.stringify(stats,null,1));

2021-08-23T22:31:50Z INFO: [
 {
  "agent": "10.0.0.171",
  "metricName": "ifinoctets",
  "lastUpdate": 2965,
  "metricValue": 67.94505393196275,
  "dataSource": "3"
 },
 {
  "agent": "10.0.0.171",
  "metricName": "ifoutoctets",
  "lastUpdate": 2965,
  "metricValue": 84.07854706370425,
  "dataSource": "3"
 },
 {
  "agent": "10.0.0.171",
  "metricName": "ifinoctets",
  "lastUpdate": 5131,
  "metricValue": 99.94473102431834,
  "dataSource": "4"
 },
 {
  "agent": "10.0.0.171",
  "metricName": "ifoutoctets",
  "lastUpdate": 5131,
  "metricValue": 99.85261606484893,
  "dataSource": "4"
 },
 {
  "agent": "10.0.0.171",
  "metricName": "ifinoctets",
  "lastUpdate": 2965,
  "metricValue": 0,
  "dataSource": "5"
 },
 {
  "agent": "10.0.0.171",
  "metricName": "ifoutoctets",
  "lastUpdate": 2965,
  "metricValue": 0,
  "dataSource": "5"
 },
 {
  "agent": "10.0.0.171",
  "metricName": "ifinoctets",
  "lastUpdate": 1887,
  "metricValue": 0,
  "dataSource": "8"
 },
 {
  "agent": "10.0.0.171",
  "metricName": "ifoutoctets",
  "lastUpdate": 1887,
  "metricValue": 0,
  "dataSource": "8"
 },
 {
  "agent": "10.0.0.172",
  "metricName": "ifinoctets",
  "lastUpdate": 1167,
  "metricValue": 101.9031781226903,
  "dataSource": "3"
 },
 {
  "agent": "10.0.0.172",
  "metricName": "ifoutoctets",
  "lastUpdate": 1167,
  "metricValue": 77.79009608277902,
  "dataSource": "3"
 },
 {
  "agent": "10.0.0.172",
  "metricName": "ifinoctets",
  "lastUpdate": 85,
  "metricValue": 69.87060998151571,
  "dataSource": "4"
 },
 {
  "agent": "10.0.0.172",
  "metricName": "ifoutoctets",
  "lastUpdate": 85,
  "metricValue": 77.81885397412199,
  "dataSource": "4"
 },
 {
  "agent": "10.0.0.172",
  "metricName": "ifinoctets",
  "lastUpdate": 2252,
  "metricValue": 0,
  "dataSource": "7"
 },
 {
  "agent": "10.0.0.172",
  "metricName": "ifoutoctets",
  "lastUpdate": 2252,
  "metricValue": 0,
  "dataSource": "7"
 },
 {
  "agent": "10.0.0.172",
  "metricName": "ifinoctets",
  "lastUpdate": 4419,
  "metricValue": 0,
  "dataSource": "9"
 },
 {
  "agent": "10.0.0.172",
  "metricName": "ifoutoctets",
  "lastUpdate": 4419,
  "metricValue": 0,
  "dataSource": "9"
 }
]

Get summary statistics for specific metrics.

parameter	type	description
agents	String	'ALL', 'TOPOLOGY', 'EDGE', 'CORE', or comma separated list of agent addresses
metrics	String	Comma separated 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
filter	Object	Select data sources based on attributes (optional)

Returns

Array[Object]

Example

var stats = metric('ALL','ifinoctets,ifoutoctets',{os_name:['linux'],ifname:['swp*']});
logInfo(JSON.stringify(stats,null,1));

Result:

2021-08-23T21:27:35Z INFO: [
 {
  "agent": "10.0.0.172",
  "metricName": "ifinoctets",
  "metricN": 15,
  "lastUpdate": 545,
  "lastUpdateMax": 10796,
  "metricValue": 77.6323068412318,
  "dataSource": "4",
  "lastUpdateMin": 545
 },
 {
  "agent": "10.0.0.173",
  "metricName": "ifoutoctets",
  "metricN": 15,
  "lastUpdate": 4048,
  "lastUpdateMax": 10796,
  "metricValue": 83.26092353525323,
  "dataSource": "3",
  "lastUpdateMin": 1629
 }
]

Get metric names and interval, in milliseconds, since they were last updated.

Example

var names = metrics();
logInfo(JSON.stringify(names,null,1));

Result:

2021-08-23T20:55:50Z INFO: {
 "cpu_wio": 4436,
 "mem_utilization": 4436,
 "swap_total": 4436,
 "interrupts": 4436,
 "node_mem_free": 4436,
 "cpu_steal": 4436,
 "pkts_in": 4436,
 "cpu_speed": 4436,
 "cpu_sintr": 4436,
 "proc_run": 4436,
 "write_time": 4436,
 "disk_free": 4436,
 "load_one_per_cpu": 4436,
 "node_cpus": 4436,
 "swap_in": 4436,
 "errs_out": 4436,
 "load_five_per_cpu": 4436,
 "node_cpu_mhz": 4436,
 "mem_buffers": 4436,
 "cpu_system": 4436,
 "read_time": 4436,
 "cpu_nice": 4436,
 "pkts_out": 4436,
 "os_name": 4436,
 "cpu_intr": 4436,
 "drops_out": 4436,
 "os_release": 4436,
 "load_one": 4436,
 "contexts": 4436,
 "errs_in": 4436,
 "uuid": 4436,
 "machine_type": 4436,
 "page_out": 4436,
 "drops_in": 4436,
 "load_five": 4436,
 "cpu_num": 4436,
 "swap_out": 4436,
 "cpu_utilization": 4436,
 "cpu_guest": 4436,
 "bytes_out": 4436,
 "node_domains": 4436,
 "mem_free": 4436,
 "mem_shared": 4436,
 "swap_free": 4436,
 "mem_used": 4436,
 "bytes_in": 4436,
 "mem_cached": 4436,
 "cpu_guest_nice": 4436,
 "page_in": 4436,
 "bytes_written": 4436,
 "disk_utilization": 4436,
 "proc_total": 4436,
 "cpu_user": 4436,
 "reads": 4436,
 "bytes_read": 4436,
 "cpu_idle": 4436,
 "node_mem_total": 4436,
 "mem_total": 4436,
 "uptime": 4436,
 "load_fifteen": 4436,
 "disk_total": 4436,
 "load_fifteen_per_cpu": 4436,
 "writes": 4436,
 "part_max_used": 4436,
 "host_name": 4436
}

Get all metric values for specific agent.

var stats = metrics('10.0.0.238');
logInfo(JSON.stringify(stats,null,1));

Result:

2021-08-23T20:54:05Z INFO: {
 "8.ifoutpkts": 0,
 "6.ifinucastpkts": 0,
 "7.ifinutilization": 0.000012258086006462144,
 "1.ifinucastpkts": 0.2831021332578394,
 "4.ifinutilization": 0,
 "4.ifadminstatus": "up",
 "7.ifdirection": "full-duplex",
 "8.ifdirection": "full-duplex",
 "7.ifinpkts": 0,
 "3.ifindiscards": 0,
 "4.ifoututilization": 0.0005954002697886655,
 "1.ifinutilization": 0.044896667721360896,
 "2.ifoperstatus": "down",
 "8.ifinerrors": 0,
 "6.ifoperstatus": "up",
 "7.ifindiscards": 0,
 "1.ifspeed": 10000000,
 "1.ifoutpkts": 0.2831021332578394,
 "1.ifindex": "1",
 "7.ifinoctets": 4.596782252423304,
 "6.ifinpkts": 0,
 "8.ifoututilization": 0,
 "6.ifoutucastpkts": 2.764731354718364,
 "8.ifoutdiscards": 0,
 "6.ifoututilization": 0.0006008238677370285,
 "6.ifadminstatus": "up",
 "1.ifadminstatus": "up",
 "2.ifoutpkts": 0,
 "1.ifinpkts": 0.2831021332578394,
 "1.ifinoctets": 561.2083465170111,
 "3.ifoutdiscards": 0,
 "6.ifindex": "6",
 "4.ifinerrors": 0,
 "6.ifoutdiscards": 0,
 "2.iftype": "ethernetCsmacd",
 "4.ifinucastpkts": 16.92007927123753,
 "4.ifindiscards": 0,
 "1.iftype": "ethernetCsmacd",
 "1.ifinerrors": 0,
 "2.ifouterrors": 0,
 "6.iftype": "ethernetCsmacd",
 "8.ifinpkts": 0,
 "2.ifindex": "2",
 "3.ifouterrors": 0,
 "4.ifouterrors": 0,
 "2.ifspeed": 10000000,
 "6.ifindiscards": 0,
 "7.ifadminstatus": "up",
 "6.ifouterrors": 0,
 "8.ifindiscards": 0,
 "3.ifinpkts": 61.168751144936465,
 "7.ifoutpkts": 2.66480130575264,
 "2.ifinerrors": 0,
 "7.ifouterrors": 0,
 "8.ifouterrors": 0,
 "3.ifinucastpkts": 61.168751144936465,
 "8.ifoperstatus": "up",
 "2.ifoutucastpkts": 0,
 "3.ifdirection": "full-duplex",
 "4.ifdirection": "full-duplex",
 "2.ifinucastpkts": 0,
 "2.ifindiscards": 0,
 "1.ifdirection": "full-duplex",
 "2.ifdirection": "full-duplex",
 "3.ifinerrors": 0,
 "6.ifdirection": "full-duplex",
 "6.ifspeed": 300000000,
 "2.ifoututilization": 0,
 "8.ifadminstatus": "up",
 "7.ifoutoctets": 200.62622830685186,
 "4.ifoutdiscards": 0,
 "6.ifoutoctets": 225.30895040138572,
 "3.ifoutoctets": 220.29410295268707,
 "4.ifinpkts": 16.92007927123753,
 "4.ifoutucastpkts": 4.479824137758755,
 "4.ifoutoctets": 223.2751011707496,
 "4.ifoutpkts": 4.479824137758755,
 "4.ifoperstatus": "up",
 "3.ifspeed": 300000000,
 "1.ifoutoctets": 164.83205382271146,
 "3.ifindex": "3",
 "2.ifoutoctets": 0,
 "3.ifinoctets": 0,
 "1.ifoutucastpkts": 0.2831021332578394,
 "3.ifinutilization": 0,
 "3.ifoututilization": 0.0005874509412071655,
 "6.ifinutilization": 0,
 "7.ifoutdiscards": 0,
 "7.iftype": "ethernetCsmacd",
 "1.ifouterrors": 0,
 "8.ifoutucastpkts": 0,
 "6.ifinerrors": 0,
 "7.ifoutucastpkts": 2.66480130575264,
 "7.ifspeed": 300000000,
 "8.ifoutoctets": 0,
 "7.ifindex": "7",
 "7.ifinerrors": 0,
 "2.ifadminstatus": "down",
 "1.ifoututilization": 0.013186564305816917,
 "2.ifinoctets": 0,
 "8.ifinoctets": 0,
 "3.iftype": "ieee80211",
 "3.ifoutpkts": 6.728063017303112,
 "4.iftype": "ieee80211",
 "4.ifindex": "4",
 "8.ifinucastpkts": 0,
 "3.ifoperstatus": "up",
 "2.ifinpkts": 0,
 "2.ifoutdiscards": 0,
 "1.ifoperstatus": "up",
 "7.ifoperstatus": "up",
 "6.ifoutpkts": 2.764731354718364,
 "8.ifspeed": 10000000,
 "8.iftype": "ethernetCsmacd",
 "4.ifinoctets": 0,
 "3.ifadminstatus": "up",
 "6.ifinoctets": 0,
 "3.ifoutucastpkts": 6.728063017303112,
 "4.ifspeed": 300000000,
 "1.ifoutdiscards": 0,
 "1.ifindiscards": 0,
 "7.ifoututilization": 0.0005350032754849383,
 "8.ifindex": "8",
 "8.ifinutilization": 0,
 "7.ifinucastpkts": 0,
 "2.ifinutilization": 0
}

Set interval handler function.

parameter	type	description
handler	Function	Function to handle periodic tasks
interval	Number	Interval seconds (optional, default 5)

Throws

Exception if handler already defined

Example

setIntervalHandler(function(now) {
  var val = metric('ALL','sum:load_one')[0].metricValue || 0;
  logInfo(val);
}, 10);

Result

2021-08-24T16:48:20Z INFO: 0.11999999731779099
2021-08-24T16:48:30Z INFO: 0.22000000067055225
2021-08-24T16:48:40Z INFO: 0.38000000081956387

Get table of metric values

parameter	type	description
agents	String	'ALL', 'TOPOLOGY', 'EDGE', 'CORE', or comma separated list of agent addresses
metrics	String	Comma separated list of metric names. e.g. `ifname,ifinoctets,ifoutoctets` The table can be sorted by prefixing a metric name with the token sort:, e.g. `sort:ifinoctets:-10` sorts the table by ifinoctets in reverse order (largest to smallest value) and truncates at 10 values. By default, table rows will only be included if all named metrics have values. Prefixing a metric name with the token null:, e.g. `null:host_name`, includes rows that do not have a value for the metric.
filter	Object	Select data sources based on attributes (optional)

Returns

Array[Object]

Example

var stats = table('ALL','ifname,sort:ifinoctets:-5,ifoutoctets',{os_name:['linux'],ifname:['swp*']});
logInfo(JSON.stringify(stats,null,1));

Result:

2021-08-23T22:21:40Z INFO: [
 [
  {
   "agent": "10.0.0.171",
   "metricName": "ifname",
   "lastUpdate": 2559,
   "metricValue": "swp2",
   "dataSource": "4"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifinoctets",
   "lastUpdate": 2559,
   "metricValue": 101.77929381395778,
   "dataSource": "4"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifoutoctets",
   "lastUpdate": 2559,
   "metricValue": 101.68710242463354,
   "dataSource": "4"
  }
 ],
 [
  {
   "agent": "10.0.0.171",
   "metricName": "ifname",
   "lastUpdate": 416,
   "metricValue": "swp1",
   "dataSource": "3"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifinoctets",
   "lastUpdate": 416,
   "metricValue": 94.05025868440504,
   "dataSource": "3"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifoutoctets",
   "lastUpdate": 416,
   "metricValue": 93.9578713968958,
   "dataSource": "3"
  }
 ],
 [
  {
   "agent": "10.0.0.171",
   "metricName": "ifname",
   "lastUpdate": 416,
   "metricValue": "swp3",
   "dataSource": "5"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifinoctets",
   "lastUpdate": 416,
   "metricValue": 0,
   "dataSource": "5"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifoutoctets",
   "lastUpdate": 416,
   "metricValue": 7.945306725794532,
   "dataSource": "5"
  }
 ],
 [
  {
   "agent": "10.0.0.171",
   "metricName": "ifname",
   "lastUpdate": 3644,
   "metricValue": "swp4",
   "dataSource": "6"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifinoctets",
   "lastUpdate": 3644,
   "metricValue": 0,
   "dataSource": "6"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifoutoctets",
   "lastUpdate": 3644,
   "metricValue": 0,
   "dataSource": "6"
  }
 ],
 [
  {
   "agent": "10.0.0.171",
   "metricName": "ifname",
   "lastUpdate": 7983,
   "metricValue": "swp5",
   "dataSource": "7"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifinoctets",
   "lastUpdate": 7983,
   "metricValue": 0,
   "dataSource": "7"
  },
  {
   "agent": "10.0.0.171",
   "metricName": "ifoutoctets",
   "lastUpdate": 7983,
   "metricValue": 0,
   "dataSource": "7"
  }
 ]
]

Threshold

Remove event handler function

Example

clearEventHandler();

Remove threshold

parameter	type	description
name	String	Name of threshold definition to remove

Example

clearThreshold('my_event');

Set event handler function.

parameter	type	description
handler	Function	Function to handle events
events	Array[String]	Threshold names to be handled (optional, default all thresholds)

Throws

Exception if handler already defined

Example

setThreshold('my_event', {metric:'ifinoctets', value:1000, filter:{ifspeed:[1000000000]}});
setEventHandler(function(event) {
  logInfo(JSON.stringify(event,null,1));
},['my_event']);

Result

2021-08-24T16:24:36Z INFO: {
 "agent": "10.0.0.231",
 "dataSource": "2",
 "metric": "ifinoctets",
 "threshold": 1000,
 "value": 3255.9952038369306,
 "timestamp": 1629822276428,
 "thresholdID": "my_event",
 "eventID": 1
}

Set threshold on a metric

parameter	type	attribute	type	description
name	String			Threshold definition name
spec	Object	metric	String	Metric to apply threshold to
		value	Number	Maximum value of metric
		timeout	Number	Seconds of hysteresis before re-arming threshold (optional, default 60)
		byFlow	Boolean	Set to true to generate a new event for each new flow exceeding threshold (optional, default false)
		filter	Object	Select data sources based on attributes (optional)

Example

setThreshold('my_event', {metric:'ifinoctets', value:1000, filter:{ifspeed:[1000000000]}});
setEventHandler(function(event) {
  logInfo(JSON.stringify(event,null,1));
},['my_event']);

Result

2021-08-24T16:24:36Z INFO: {
 "agent": "10.0.0.231",
 "dataSource": "2",
 "metric": "ifinoctets",
 "threshold": 1000,
 "value": 3255.9952038369306,
 "timestamp": 1629822276428,
 "thresholdID": "my_event",
 "eventID": 1
}

Detecting large "Elephant" flows

setFlow('pair', {'keys':'ipsource,ipdestination','value':'bytes'});
setThreshold('elephant', {'metric':'pair','value':50000000/8,'byFlow':true,'timeout':1});
setEventHandler(function(evt) {
  logInfo(JSON.stringify(evt,null,1));
},['elephant']);

Result

2021-11-12T11:32:37-08:00 INFO: {
 "agent": "10.0.0.232",
 "dataSource": "9",
 "metric": "pair",
 "threshold": 6250000,
 "value": 6420125.99290418,
 "timestamp": 1636745557757,
 "thresholdID": "elephant",
 "eventID": 2,
 "flowKey": "10.0.0.252,10.0.0.70"
}

Test threshold state

parameter	type	description
name	String	Name of threshold definition
agent	String	Agent address
metric	String	Must include datasource, e.g. "2.bytes"
flowkey	String	Flow key (optional, if threshold definition sets byFlow flag)

Returns

Boolean

Example

var active = thresholdState('my_event','10.0.0.231','2.ifinoctets');

Flows

List top active flows

parameter	type	description
agent	String	'ALL', 'TOPOLOGY', 'EDGE', 'CORE', or comma separated list of agent addresses
name	String	Flow definition name
maxFlows	Number	Maximum number of flows (optional, default 100)
minValue	Number	Minimum flow value (optional, default 0)
aggMode	String	Method of combining flows across data sources: 'sum', 'avg', 'max', 'edge', or 'core' (optional, default 'max')

Returns

Array[Object]

Example

setFlow('pair', {keys:'ipsource,ipdestination',value:'bytes'});
setIntervalHandler(function(now) {
  var top = activeFlows('ALL','pair',5,0.1);
  logInfo(JSON.stringify(top,null,1));
}, 10);

Result

2021-08-24T17:54:50Z INFO: [
 {
  "flowN": 4,
  "agent": "10.0.0.232",
  "value": 1369064.13020965,
  "dataSource": "9",
  "key": "10.0.0.70,10.0.0.236"
 },
 {
  "flowN": 4,
  "agent": "10.0.0.232",
  "value": 940589.4623549506,
  "dataSource": "2",
  "key": "10.0.0.236,10.0.0.70"
 },
 {
  "flowN": 1,
  "agent": "10.0.0.252",
  "value": 597522.446947001,
  "dataSource": "1",
  "key": "10.0.0.172,10.0.0.30"
 },
 {
  "flowN": 1,
  "agent": "10.0.0.252",
  "value": 42634.529201136625,
  "dataSource": "7",
  "key": "142.250.191.37,10.0.0.70"
 },
 {
  "flowN": 1,
  "agent": "10.0.0.252",
  "value": 18462.676644399788,
  "dataSource": "4",
  "key": "10.0.0.20,10.0.0.236"
 }
]

Remove flow definition

parameter	type	description
name	String	Flow definition name

Example

clearFlow('pair');

Remove flow handler function.

Example

clearFlowHandler();

List available flow keys and interval, in milliseconds, since they were last seen.

Returns

Object

Example

var keys = flowKeys();
logInfo(JSON.stringify(keys,null,1));

Result

2021-08-24T17:57:36Z INFO: {
 "stack": 392,
 "agent": 392,
 "inputifindex": 392,
 "ethernetprotocol": 392,
 "stripped": 392,
 "ipoptionslength": 392,
 "tcpwindow": 392,
 "ipbytes": 392,
 "ds": 392,
 "tcpsourceport": 392,
 "ipdscpname": 392,
 "macdestination": 392,
 "tcpdestinationport": 392,
 "ip_offset": 392,
 "tcp_offset": 392,
 "ipttl": 392,
 "isunicast": 392,
 "isbroadcast": 392,
 "prioritydestination": 392,
 "ipflags": 392,
 "tcpoptbytes": 392,
 "direction": 392,
 "tcpopts": 392,
 "frames": 392,
 "tcppayloadbytes": 392,
 "macsource": 392,
 "eth_offset": 392,
 "ipdscp": 392,
 "ipprotocol": 392,
 "prioritysource": 392,
 "ipsource": 392,
 "tcpseqno": 392,
 "iptos": 392,
 "ismulticast": 392,
 "ipid": 392,
 "tcpoffset": 392,
 "ipecn": 392,
 "vlansource": 392,
 "bytes": 392,
 "tcpflags": 392,
 "ipdestination": 392,
 "tcpackno": 392,
 "outputifindex": 392,
 "ipfragoffset": 392,
 "vlandestination": 392
}

Get locations that observed a specific flow

parameter	type	description
agent	String	'ALL', 'TOPOLOGY', 'EDGE', 'CORE', or comma separated list of agent addresses
name	String	Flow definition name
key	String	Flow key

Returns

Array[Object]

Example

setFlow('pair', {keys:'ipsource,ipdestination',value:'bytes'});
setIntervalHandler(function(now) {
  var locs = flowLocations('ALL','pair','10.0.0.70,10.0.0.236');
  logInfo(JSON.stringify(locs,null,1));
}, 10);

Result

2021-08-24T19:38:10Z INFO: [
 {
  "agent": "10.0.0.252",
  "dataSource": "7",
  "value": 18302.32266467178
 }
]

Get value for specific flow

parameter	type	description
agent	String	Agent address
name	String	Flow definition name prefixed by datasource index
key	String	Flow key

Returns

Number

Example

setFlow('pair', {keys:'ipsource,ipdestination',value:'bytes'});
setIntervalHandler(function(now) {
  var val = flowValue('10.0.0.252','7.pair','10.0.0.70,10.0.0.236');
  logInfo(val);
}, 10);

Result

2021-08-24T19:38:10Z INFO: 18302.32266467178

Get values for specific flow

parameter	type	description
agent	String	Agent address
name	String	Flow definition name prefixed by datasource index
key	String	Flow key

Returns

Object

Example

setFlow('pair', {keys:'ipsource,ipdestination',value:'bytes',values:['frames']});
setIntervalHandler(function(now) {
  var val = flowValues('10.0.0.252','7.pair','10.0.0.70,10.0.0.236');
  logInfo(JSON.stringify(val));
}, 10);

Result

2023-03-01T15:08:20-08:00 INFO: {"lastUpdate":1584,"values":[1811.2050914284814],"value":126784.3563999937}

Create flow definition - see Defining Flows

parameter	type	description
name	String	Flow definition name
definition	Object	Flow definition

Example

setFlow('pair', {keys:'ipsource,ipdestination',value:'bytes',log:true});
setFlowHandler(function(rec) {
 logInfo(JSON.stringify(rec,null,1));
}, ['pair']);

Result

2021-08-24T17:01:38Z INFO: {
 "name": "pair",
 "agent": "10.0.0.30",
 "dataSource": "2",
 "value": 823296,
 "start": 1629824434158,
 "end": 1629824498354,
 "flowID": 0,
 "flowKeys": "10.0.0.30,10.0.0.73"
}

Set flow handler function.

parameter	type	description
handler	Function	Function to handle flow records
flows	Array[String]	Flow names to be handled (optional, default all flows)

Throws

Exception if handler already defined

Example

setFlow('pair', {keys:'ipsource,ipdestination',value:'bytes',log:true});
setFlowHandler(function(rec) {
 logInfo(JSON.stringify(rec,null,1));
}, ['pair']);

Result

2021-08-24T17:01:38Z INFO: {
 "name": "pair",
 "agent": "10.0.0.30",
 "dataSource": "2",
 "value": 823296,
 "start": 1629824434158,
 "end": 1629824498354,
 "flowID": 0,
 "flowKeys": "10.0.0.30,10.0.0.73"
}

Create or update address group

parameter	type	description
name	String	Name of address group
spec	Object	Groups are used to map IP address ranges to names when defining flows

Example

var groups = {
  "external":["0.0.0.0/0"],
  "internal":["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]
};
setGroups('my_groups',groups);
setFlow('grouped',{keys:'group:ipsource:my_groups', value:'bytes'});
setIntervalHandler(function(now) {
  var top = activeFlows('ALL','grouped',5,0.1,'sum');
  logInfo(JSON.stringify(top,null,1));
});

Result

2021-08-24T20:10:25Z INFO: [
 {
  "flowN": 9,
  "agent": "10.0.0.252",
  "value": 233258.77995373044,
  "dataSource": "2",
  "key": "internal"
 },
 {
  "flowN": 1,
  "agent": "10.0.0.232",
  "value": 6145.886010184038,
  "dataSource": "9",
  "key": "external"
 }
]

Create or update attribute map

parameter	type	description
name	String	Name of address group
spec	Object	Maps are used to map flow attributes to names when defining flows

Example

var map = {
  "web":["80","8080","8008"],
  "shell":["22"]
};
setMap('my_map',map);
setFlow('mapped',{keys:'map:tcpsourceport:my_map', value:'bytes'});
setIntervalHandler(function(now) {
  var top = activeFlows('ALL','mapped',5,0.1,'sum');
  logInfo(JSON.stringify(top,null,1));
});

Result

2021-08-24T20:21:55Z INFO: [
 {
  "flowN": 4,
  "value": 1112184.712496698,
  "key": "shell"
 }
]

Topology

Get network topology

Returns

Object

Example

var top = getTopology();
logInfo(JSON.stringify(top,null,1));

Result

2021-08-25T18:50:19Z INFO: {
 "links": {
  "link1": {
   "node2": "spine1",
   "node1": "leaf1",
   "port1": "swp1",
   "port2": "swp1"
  },
  "link4": {
   "node2": "spine2",
   "node1": "leaf2",
   "port1": "swp2",
   "port2": "swp2"
  },
  "link3": {
   "node2": "spine1",
   "node1": "leaf2",
   "port1": "swp1",
   "port2": "swp2"
  },
  "link2": {
   "node2": "spine2",
   "node1": "leaf1",
   "port1": "swp2",
   "port2": "swp1"
  }
 },
 "version": 0
}

Get interface name associated with SNMP ifIndex

parameter	type	description
agent	String	Agent address
ifIndex	Number	SNMP ifIndex

Returns

String

Example

var name = ifName('192.168.1.1',3);
logInfo(name);

Result

2021-08-25T18:55:19Z INFO: swp1

Set network topology

parameter	type	description
topology	Object	network topology

Example

var top = {
  "links": {
    "link1": {
      "node1": "leaf1",
      "port1": "swp1",
      "node2": "spine1",
      "port2": "swp1"
    },
    "link2": {
      "node1": "leaf1",
      "port1": "swp2",
      "node2": "spine2",
      "port2": "swp1"
    },
    "link3": {
      "node1": "leaf2",
      "port1": "swp1",
      "node2": "spine1",
      "port2": "swp2"
    },
    "link4": {
      "node1": "leaf2",
      "port1": "swp2",
      "node2": "spine2",
      "port2": "swp2"
    }
  }
};
setTopology(top);

Return the sFlow agent reporting on node

parameter	type	description
node	String	Node name

Returns

String

Example

var agt = topologyAgentForNode('spine2');
logInfo(agt);

Result

2021-08-25T19:10:30Z INFO: 192.168.1.4

Get network diameter

Returns

Number

Example

var diam = topologyDiameter();
logInfo(diam);

Result

2021-08-25T19:54:12Z INFO: 2

Lookup link based on agent and ifIndex

parameter	type	description
agent	String	Agent address
ifIndex	Number	SNMP ifIndex

Returns

Object

Example

var link = topologyInterfaceToLink('192.168.1.3',2);
logInfo(JSON.stringify(link,null,1));

Result

2021-08-25T20:29:27Z INFO: {
 "remoteagent": "192.168.1.2",
 "remotenode": "leaf2",
 "remoteifindex": "3",
 "localnode": "spine1",
 "localport": "swp2",
 "remoteport": "swp1",
 "linkname": "link3"
}

Lookup port based on agent and ifIndex

parameter	type	description
agent	String	Agent address
ifIndex	Number	SNMP ifIndex

Returns

Object

Example

var port = topologyInterfaceToPort('192.168.1.3',2);
logInfo(JSON.stringify(port));

Result

2021-08-25T20:31:40Z INFO: {"node":"spine1","port":"swp2"}

Lookup link by name

parameter	type	description
name	String	Link name

Returns

Object

Example

var link = topologyLink('link3');
logInfo(JSON.stringify(link,null,1));

Result

2021-08-25T20:38:22Z INFO: {
 "node2": "spine1",
 "node1": "leaf2",
 "port1": "swp1",
 "port2": "swp2"
}

Get metrics associated with interfaces at each end of link

parameter	type	description
name	String	Link name
metric	String	Metric name
start	String	Start node to indicate direction (optional)

Returns

Object

Example

var stats = topologyLinkMetric('link1','ifinutilization','spine1');
logInfo(JSON.stringify(stats,null,1));

Result

2021-08-25T20:54:40Z INFO: [
 {
  "agent": "192.168.1.1",
  "metricName": "ifinutilization",
  "lastUpdate": 23765,
  "metricValue": 0.0000013702525218333217,
  "dataSource": "3"
 },
 {
  "agent": "192.168.1.3",
  "metricName": "ifinutilization",
  "lastUpdate": 10988,
  "metricValue": 0.000002183220316447281,
  "dataSource": "1"
 }
]

Get link names

Returns

Array[String]

Example

var names = topologyLinkNames();
logInfo(JSON.stringify(names));

Result

2021-08-25T20:59:03Z INFO: ["link1","link4","link3","link2"]

Get value of tag for link

parameter	type	description
link	String	Link name
tag	String	Tag name

Returns

String

Example

var val = topologyLinkTag('link1','type');
logInfo(val);

Result

2021-08-25T21:03:23Z INFO: pod

Get interfaces associated with link

parameter	type	description
name	String	Link name

Returns

Object

Example

var ifaces = topologyLinkToInterfaces('link1');
logInfo(JSON.stringify(ifaces,null,1));

Result

2021-08-25T21:11:28Z INFO: {
 "node1": "leaf1",
 "port1": "swp1",
 "node2": "spine1",
 "port2": "swp1",
 "agent1": "192.168.1.1",
 "ifindex1": "3",
 "agent2": "192.168.1.3",
 "ifindex2": "1"
}

Get host MAC addresses that have been located to access ports

parameter	type	description
agent	String	Only return addresses located to agent (optional)
ifindex	String	Only return addresses located to agent and ifindex (optional)

Returns

Array[String]

Example

var macs = topologyLocatedHostMacs();
logInfo(JSON.stringify(macs));

Result

2021-08-25T21:17:05Z INFO: ["000AF725C062","000AF725C060","000AF725C422","000AF725C420"]

Get information about switch port(s) connected to Host sFlow agent

parameter	type	description
agent	String	Host sFlow agent address

Returns

Array[Object]

Example

var loc = topologyLocateHostAgent('10.0.0.30');
logInfo(JSON.stringify(loc,null,1));

Result

2021-08-25T21:44:40Z INFO: [
 {
  "machine_type": "x86_64",
  "agent": "192.168.1.1",
  "ipaddress": "10.0.0.30",
  "ifindex": "1",
  "ip6address": "FE80::9A4B:E1FF:FE03:4A61",
  "vlan": 1,
  "os_name": "linux",
  "os_release": "3.10.0-1062.4.3.el7.x86_64",
  "uuid": "1f6d0200-1dd2-11b2-8000-000af725c062",
  "mac": "000AF725C062",
  "host_name": "centos7.sf.inmon.com"
 }
]

Get information about switch port(s) connected to host IP address

parameter	type	description
address	String	Host IP address

Returns

Array[Object]

Example

var loc = topologyLocateHostIP('10.0.0.30');
logInfo(JSON.stringify(loc,null,1));

Result

2021-08-25T21:44:40Z INFO: [
 {
  "machine_type": "x86_64",
  "agent": "192.168.1.1",
  "ipaddress": "10.0.0.30",
  "ifindex": "1",
  "ip6address": "FE80::9A4B:E1FF:FE03:4A61",
  "vlan": 1,
  "os_name": "linux",
  "os_release": "3.10.0-1062.4.3.el7.x86_64",
  "uuid": "1f6d0200-1dd2-11b2-8000-000af725c062",
  "mac": "000AF725C062",
  "host_name": "centos7.sf.inmon.com"
 }
]

Get information about switch port(s) connected to host IPv6 address

parameter	type	description
address	String	Host IPv6 address

Returns

Array[Object]

Example

var loc = topologyLocateHostIP6('');
logInfo(JSON.stringify(loc,null,1));

Result

2021-08-25T21:44:40Z INFO: [
 {
  "machine_type": "x86_64",
  "agent": "192.168.1.1",
  "ipaddress": "10.0.0.30",
  "ifindex": "1",
  "ip6address": "FE80::9A4B:E1FF:FE03:4A61",
  "vlan": 1,
  "os_name": "linux",
  "os_release": "3.10.0-1062.4.3.el7.x86_64",
  "uuid": "1f6d0200-1dd2-11b2-8000-000af725c062",
  "mac": "000AF725C062",
  "host_name": "centos7.sf.inmon.com"
 }
]

Get information about switch port(s) connected to host MAC address

parameter	type	description
address	String	Host MAC address

Returns

Array[Object]

Example

var loc = topologyLocateHostMac('000AF725C062');
logInfo(JSON.stringify(loc,null,1));

Result

2021-08-25T21:44:40Z INFO: [
 {
  "machine_type": "x86_64",
  "agent": "192.168.1.1",
  "ipaddress": "10.0.0.30",
  "ifindex": "1",
  "ip6address": "FE80::9A4B:E1FF:FE03:4A61",
  "vlan": 1,
  "os_name": "linux",
  "os_release": "3.10.0-1062.4.3.el7.x86_64",
  "uuid": "1f6d0200-1dd2-11b2-8000-000af725c062",
  "mac": "000AF725C062",
  "host_name": "centos7.sf.inmon.com"
 }
]

Get information about switch port(s) connected to Host sFlow agent

parameter	type	description
uuid	String	Host UUID

Returns

Array[Object]

Example

var loc = topologyLocateHostUUID('1f6d0200-1dd2-11b2-8000-000af725c062');
logInfo(JSON.stringify(loc,null,1));

Result

2021-08-25T21:44:40Z INFO: [
 {
  "machine_type": "x86_64",
  "agent": "192.168.1.1",
  "ipaddress": "10.0.0.30",
  "ifindex": "1",
  "ip6address": "FE80::9A4B:E1FF:FE03:4A61",
  "vlan": 1,
  "os_name": "linux",
  "os_release": "3.10.0-1062.4.3.el7.x86_64",
  "uuid": "1f6d0200-1dd2-11b2-8000-000af725c062",
  "mac": "000AF725C062",
  "host_name": "centos7.sf.inmon.com"
 }
]

Get network minimum spanning tree

Returns

Array[String]

Example

var msp = topologyMinimumSpanningTree();
logInfo(JSON.stringify(msp));

Result

2021-08-25T22:29:35Z INFO: ["link1","link4","link3"]

Get links connected to node

parameter	type	description
name	String	Node name

Returns

Array[Object]

Example

var links = topologyNodeLinks('leaf1');
logInfo(JSON.stringify(links,null,1));

Result

2021-08-25T22:38:12Z INFO: [
 {
  "linkname": "link2",
  "localport": "swp2",
  "remotenode": "spine2",
  "remoteport": "swp1"
 },
 {
  "linkname": "link1",
  "localport": "swp1",
  "remotenode": "spine1",
  "remoteport": "swp1"
 }
]

Get node names

Returns

Array[String]

Example

var names = topologyNodeNames();
logInfo(JSON.stringify(names));

Result

2021-08-25T22:42:07Z INFO: ["leaf1","leaf2","spine1","spine2"]

Get port names for node

parameter	type	description
name	String	Node name

Returns

Array[String]

Example

var names = topologyNodePortNames('leaf1');
logInfo(JSON.stringify(names));

Result

2021-08-25T22:45:09Z INFO: ["swp2","swp1"]

Get node names for agent

parameter	type	description
agent	String	Agent address

Returns

Array[String]

Example

var nodes = topologyNodesForAgent('192.168.1.1');
logInfo(JSON.stringify(nodes));

Result

2021-08-25T22:49:52Z INFO: ["leaf1"]

Get value of tag for node

parameter	type	description
node	String	Node name
tag	String	Tag name

Returns

String

Example

var val = topologyNodeTag('leaf1','type');
logInfo(val);

Result

2021-08-25T21:03:23Z INFO: leaf

Get value of tag for port

parameter	type	description
node	String	Node name
port	String	Port name
tag	String	Tag name

Returns

String

Example

var val = topologyPortTag('leaf1','swp1','type');
logInfo(val);

Result

2021-08-25T21:03:23Z INFO: secure

Get interface associated with port

parameter	type	description
node	String	Node name
port	String	Port name

Returns

Object

Example

var iface = topologyPortToInterface('leaf1','swp1');
logInfo(JSON.stringify(iface));

Result

2021-08-25T23:00:09Z INFO: {"agent":"192.168.1.1","ifindex":"3"}

Get shortest path between nodes

parameter	type	description
start	String	Start node name
end	String	End node name

Returns

Object

Example

var path = topologyShortestPath('leaf1','leaf2');
logInfo(JSON.stringify(path,null,1));

Result

2021-08-25T23:05:52Z INFO: [
 {
  "linkname": "link1",
  "startnode": "leaf1",
  "endnode": "spine1",
  "startport": "swp1",
  "endport": "swp1"
 },
 {
  "linkname": "link3",
  "startnode": "spine1",
  "endnode": "leaf2",
  "startport": "swp2",
  "endport": "swp1"
 }
]

Get k shortest paths between nodes

parameter	type	description
start	String	Start node name
end	String	End node name
k	Number	Number of paths to find
n	Number	Path length limit (optional)

Returns

Object

Example

var paths = topologyShortestPaths('leaf1','leaf2',2);
logInfo(JSON.stringify(paths,null,1));

Result

2021-08-25T23:10:38Z INFO: [
 [
  {
   "linkname": "link1",
   "startnode": "leaf1",
   "endnode": "spine1",
   "startport": "swp1",
   "endport": "swp1"
  },
  {
   "linkname": "link3",
   "startnode": "spine1",
   "endnode": "leaf2",
   "startport": "swp2",
   "endport": "swp1"
  }
 ],
 [
  {
   "linkname": "link2",
   "startnode": "leaf1",
   "endnode": "spine2",
   "startport": "swp2",
   "endport": "swp1"
  },
  {
   "linkname": "link4",
   "startnode": "spine2",
   "endnode": "leaf2",
   "startport": "swp2",
   "endport": "swp2"
  }
 ]
]

Get tag names

Returns

Array[String]

Example

var tags = topologyTags();
logInfo(JSON.stringify(tags));

Result

2021-08-25T23:14:29Z INFO: ["rack","type"]

Get monotonically increasing version number of installed topology

Returns

Number

Example

var ver = topologyVersion();
logInfo(ver);

Result

2021-08-25T23:17:58Z INFO: 0

BGP

Add BGP Flowspec rule

parameter	type	attribute	type	description
router	String			Router address
spec	Object	match	Object	Packet fields to match on: `version`, `source`, `destination`, `protocol`, `protocol`, `port`, `destination-port`, `source-port`, `icmp-type`, `icmp-code`, `tcp-flags`, `length`, `dscp`, and `fragment`
spec	Object	then	Object	Actions to take: `traffic-rate`, `traffic-action`, `redirect`, `traffic-marking`, and `communities`

Returns

Boolean

Throws

Exception for missing or malformed arguments

Example

var spec = {
  'match': {
    'protocol':'=17',
    'source-port':'=53',
    'destination': '172.17.0.1'
  },
  'then': {
    'traffic-rate':0
  }
};
var success = bgpAddFlow('192.168.1.1', spec);

Peer with BGP router. Router is expected to open BGP connection to sFlow-RT (default port 1179)

parameter	type	attribute	type	description
router	String			Router address
AS	String			Local AS number
ID	String			Local ID (optional, defaults to host unicast IP address or '0.0.63.43')
options	Object	as4	Boolean	Request 4 byte AS numbers, (optional, default true)
		ipv6	Boolean	Request IPv6, (optional, default false)
		flowspec	Boolean	Request IP Flowspec, (optional, default false)
		flowspec6	Boolean	Request IPv6 Flowspec, (optional, default false)
open	Function			Function to call after session open (optional)
close	Function			Function to call after session close (optional)

Throws

Exception for missing or malformed arguments

Example

bgpAddNeighbor('192.168.1.1','65001');

Advertise BGP prefix to peer

parameter	type	attribute	type	description
router	String			Router address
spec	Object	prefix	String	CIDR
		nexthop	String	Nexthop address
		nexthoplinklocal	String	Link local next hop (optional)
		aspath	String	AS path (optional)
		origin	String	Origin (optional)
		communities	String	Communities (optional)
		med	Number	Multi-exit descriminator (optional)
		localpref	Number	Local preference (optional, default 100)

Returns

Boolean

Throws

Exception for missing or malformed arguments

Example

var spec = {
  prefix: '192.0.2.0/24',
  nexthop: '192.0.2.1',
  communities: '65535:666'
};
var success = bgpAddRoute('192.168.1.1', spec);

Join sampled packet records from sFlow agent with BGP route information associated with prefix. Define Flow metrics that include BGP related keys (e.g. bgpdestinationaspath). Use bgpTopPrefixes() and bgpTopPrefixes6() to identify prefixes carrying most traffic (as specified by t and value settings below).

Note Each agent can be mapped to only one router, each router can have mutiple agents mapped to it. All sampled packet records mapped to the router will contribute to prefix traffic measurements.

parameter	type	description
agent	String	sFlow agent address
router	String	Router address
t	Number	Flow smoothing interval in seconds (optional, default 2)
value	String	Value to compute, 'bytes' or 'frames' per second (optional, default 'bytes')

Throws

Exception for missing or malformed arguments

Example

bgpAddNeighbor('192.168.1.1','65001');
bgpAddSource('192.168.1.1','192.168.1.1');

Number of BGP Flowspec rules pushed to router

parameter	type	description
router	String	Router address

Returns

Number

Example

var n = bgpFlowCount('192.168.1.1');
logInfo(n);

Result

2021-08-25T23:17:58Z INFO: 0

Get BGP Flowspec rules installed on router

parameter	type	description
router	String	Router address

Returns

Array[Object]

Throws

Exception for missing or malformed arguments

Example

var flows = bgpFlows('192.168.1.1');
logInfo(JSON.stringify(flows,null,1));

Result

2021-08-25T23:17:58Z INFO: [
  {
    "match": {
      "destination": "172.17.0.1/32",
      "source-port": "=53",
      "protocol": "=17",
      "version": "4"
    },
    "then": {
      "traffic-rate": "0.0"
    }
  }
]

Get route advertised to peer

parameter	type	description
router	String	Router address
prefix	String	CIDR

Returns

Object

Throws

Exception for missing or malformed arguments

Example

var route = bgpGetRoute('192.168.1.1','172.17.0.1/32');
logInfo(JSON.stringify(route,null,1));

Result

2021-08-25T23:17:58Z INFO: {
 "localpref": 100,
 "aspath": "65001",
 "nexthop": "192.0.2.1",
 "communities": "65535:666"
}

Get prefix covering address

parameter	type	description
router	String	Router address
address	String	IP address

Returns

Object

Throws

Exception for missing or malformed arguments

Example

var route = bgpPrefixForAddress('172.17.0.1','192.0.2.2');
logInfo(JSON.stringify(route,null,1);

Result

2021-08-25T23:17:58Z INFO: {
 "aspath": "65000",
 "valueIngress": 0,
 "valueEgress": 0,
 "prefix": "192.0.2.0/24",
 "nexthop": "192.168.1.1",
 "origin": "IGP"
}

Withdraw BGP Flowspec rule

parameter	type	description
router	String	Router address
spec	Object	BGP Flowspec added with `bgpAddFlow()`

Returns

Object

Throws

Exception for missing or malformed arguments

Example

var spec = {
  'match': {
    'protocol':'=17',
    'source-port':'=53',
    'destination': '172.17.0.1'
  },
  'then': {
    'traffic-rate':0
  }
};
var success = bgpRemoveFlow('192.168.1.1', spec);

Remove BGP peer

parameter	type	description
router	String	Router address

Throws

Exception for missing or malformed arguments

Example

bgpRemoveNeighbor('192.168.1.1');

Remove advertised prefix

parameter	type	description
router	String	Router address
prefix	String	CIDR added with `bgpAddRoute()`

Returns

Boolean

Throws

Exception for missing or malformed arguments

Example

var success = bgpRemoveRoute('192.162.1.1','192.0.2.0/24');

Remove sFlow source

parameter	type	description
agent	String	Agent address

Throws

Exception for missing or malformed arguments

Example

bgpRemoveSource('192.168.1.1');

Number of prefixes advertised to router

parameter	type	description
router	String	Router address

Returns

Number

Example

var n = bgpRouteCount('192.168.1.1');
logInfo(n);

Result

Get prefixes advertised to router

parameter	type	description
router	String	Router address

Returns

Array[String]

Throws

Exception for missing or malformed arguments

Example

var cidrs = bgpRoutes('192.168.1.1');
logInfo(JSON.stringify(cidrs));

Result

2021-08-25T23:17:58Z INFO: ["192.0.2.0/24"]

Get IPv4 prefixes with most traffic.

parameter	type	description
router	String	Router address
maxPrefixes	Number	Maximum number of prefixes to return (optional, default 100)
minValue	Number	Minimum value to report for prefix (optional, default 0)
direction	String	Traffic direction: 'source' or 'destination' (optional, default 'destination')
includeCovered	Boolean	Include prefixes that are covered by the top prefix, but wouldn't otherwise make the list (optional, default false)
minPrefix	Number	Minimum prefix length (optional, default 0)
pruneCovered	Boolean	Eliminate covered prefixes that share the same next hop (optional, default false)

Returns

Object

Example

bgpAddNeighbor('192.168.1.1','65001');
bgpAddSource('192.168.1.1','192.168.1.1');
setIntervalHandler(function(now) {
 var top = bgpTopPrefixes('192.168.1.1');
 logInfo(JSON.stringify(top,null,1));
});

Result

2021-08-25T23:17:58Z INFO: {
 "as": 65152,
 "direction": "destination",
 "id": "192.168.152.3",
 "learnedPrefixesAdded": 2,
 "learnedPrefixesRemoved": 0,
 "nPrefixes": 2,
 "pushedPrefixesAdded": 0,
 "pushedPrefixesRemoved": 0,
 "startTime": 1437535255553,
 "state": "established",
 "topPrefixes": [
  {
   "aspath": "65150",
   "localpref": 100,
   "med": 0,
   "nexthop": "192.168.150.1",
   "origin": "IGP",
   "prefix": "192.168.250.0/24",
   "value": 1.4462334178258518E7
  },
  {
   "aspath": "65151",
   "localpref": 100,
   "med": 0,
   "nexthop": "192.168.151.1",
   "origin": "IGP",
   "prefix": "192.168.251.0/24",
   "value": 391390.33359066787
  }
 ],
 "valuePercentCoverage": 100,
 "valueTopPrefixes": 1.4853724511849185E7,
 "valueTotal": 1.4853724511849185E7
}

Get IPv6 prefixes with most traffic

parameter	type	description
router	String	Router address
maxPrefixes	Number	Maximum number of prefixes to return (optional, default 100)
minValue	Number	Minimum value to report for prefix (optional, default 0)
direction	String	Traffic direction: 'source' or 'destination' (optional, default 'destination')
includeCovered	Boolean	Include prefixes that are covered by the top prefix, but wouldn't otherwise make the list (optional, default false)
minPrefix	Number	Minimum prefix length (optional, default 0)
pruneCovered	Boolean	Eliminate covered prefixes that share the same next hop (optional, default false)

Returns

Object

Example

bgpAddNeighbor('192.168.1.1','65001');
bgpAddSource('192.168.1.1','192.168.1.1');
setIntervalHandler(function(now) {
 var top = bgpTopPrefixes6('192.168.1.1');
 logInfo(JSON.stringify(top,null,1));
});

Result

2021-08-25T23:17:58Z INFO: {
 "as": 65152,
 "direction": "destination",
 "id": "192.168.152.3",
 "learnedPrefixesAdded": 2,
 "learnedPrefixesRemoved": 0,
 "nPrefixes": 2,
 "pushedPrefixesAdded": 0,
 "pushedPrefixesRemoved": 0,
 "startTime": 1437535255553,
 "state": "established",
 "topPrefixes": [
  {
   "aspath": "65150",
   "localpref": 100,
   "med": 0,
   "nexthop": "2001:DB8::96",
   "origin": "IGP",
   "prefix": "2001:DB8:96::/48",
   "value": 1.4462334178258518E7
  },
  {
   "aspath": "65151",
   "localpref": 100,
   "med": 0,
   "nexthop": "2001:DB8::97",
   "origin": "IGP",
   "prefix": "2001:DB8:97::/48",
   "value": 391390.33359066787
  }
 ],
 "valuePercentCoverage": 100,
 "valueTopPrefixes": 1.4853724511849185E7,
 "valueTotal": 1.4853724511849185E7
}

Forwarding

Remove sFlow forwarding entry

parameter	type	description
name	String	Forwarding entry name

Example

clearForward('ddos-analyzer');

Create sFlow forwarding entry

parameter	type	description
name	String	Forwarding entry name
address	String	sFlow receiver address
port	Number	sFlow receiver port (optional, default 6343)

Throws

Exception for missing or malformed arguments

Example

setForward('ddos-analyzer','192.168.1.2');

Create sFlow forwarding entry with filter

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.

parameter	type	attribute	type	description
name	String			Name of tenant entry
address	String			sFlow receiver address
port	Number			sFlow receiver port (optional, default 6343)
filters	Object	cidr	Array[String]	List of CIDRs (optional)
		ifindex	Array[String]	List of switch ports expressed as agent_ifindex strings (optional)
		ifname	Array[String]	List of switch ports expressed as agent_ifname strings (optional)
		mac	Array[String]	List MAC of addresses (optional)

Example

var filter = {"cidr":["10.0.0.0/24"]};
setTenant('engineering','192.168.1.5',6343,filter);

HTTP

Remove the HTTP handler function.

Example

clearHttpHandler();

Make an GET request

parameter	type	description
url	String	URL for request
operation	'GET'	HTTP method (optional)
user	String	Basic authentication username (optional)
password	String	Basic authentication password (optional)
accept	String	Accept mime type (optional)

Returns

String

Throws

Exception for missing or malformed arguments or I/O error

Example

var latest = http('https://inmon.com/products/sFlow-RT/latest.txt');
logInfo(latest);

Result

2021-08-20T22:08:37Z INFO: 3.0-1606

Make an POST, PUT, DELETE request

parameter	type	description
url	String	URL for request
operation	String	HTTP method, POST, PUT, or DELETE
contentType	String	Mime type of message body
content	String	Message body
user	String	Basic authentication username (optional)
password	String	Basic authentication password (optional)
accept	String	Accept mime type (optional)

Returns

String

Throws

Exception for missing or malformed arguments or I/O error

Example

var latest = http(url,'PUT','application/json',JSON.stringify(body));

Asynchronously make an HTTP request

parameter	type	attribute	type	description
args	Object	url	String	URL for request
		operation	String	HTTP method (optional, default 'GET')
		body	String	Message body (optional)
		headers	Object	HTTP headers (optional)
		user	String	Basic authentication username (optional)
		password	String	Basic authentication password (optional)
		success	Function	Function to call with successful request
		error	Function	Function to call with failed request

Throws

Exception for missing or malformed arguments

Example

httpAsync({
  url:'https://inmon.com/products/sFlow-RT/latest.txt',
  headers:{'Accept':'text/plain'},
  operation:'GET',
  success: (res) => logInfo(JSON.stringify(res,null,1))
});

Result

2021-08-20T22:50:02Z INFO: {
 "headers": {
  "Accept-Ranges": [
   "bytes"
  ],
  "null": [
   "HTTP/1.1 200 OK"
  ],
  "Server": [
   "Apache/2.4.41 (Ubuntu)"
  ],
  "ETag": [
   "\"9-5c8e74405be8d\""
  ],
  "Connection": [
   "close"
  ],
  "Last-Modified": [
   "Fri, 06 Aug 2021 17:21:27 GMT"
  ],
  "Content-Length": [
   "9"
  ],
  "Date": [
   "Fri, 20 Aug 2021 22:50:02 GMT"
  ],
  "Content-Type": [
   "text/plain"
  ]
 },
 "body": "3.0-1606\n",
 "url": "https://inmon.com/products/sFlow-RT/latest.txt",
 "status": 200
}

Make an HTTP request

parameter	type	attribute	type	description
args	Object	url	String	URL for request
		operation	String	HTTP method (optional, default 'GET')
		body	String	Message body (optional)
		headers	Object	HTTP headers (optional)
		user	String	Basic authentication username (optional)
		password	String	Basic authentication password (optional)

Returns

Object

Throws

Exception for missing or malformed arguments or I/O error

Example

var latest = http2({
  url:'https://inmon.com/products/sFlow-RT/latest.txt',
  headers:{'Accept':'text/plain'},
  operation:'GET'
});
logInfo(JSON.stringify(latest,null,1));

Result

2021-08-20T22:39:08Z INFO: {
 "headers": {
  "Accept-Ranges": [
   "bytes"
  ],
  "null": [
   "HTTP/1.1 200 OK"
  ],
  "Server": [
   "Apache/2.4.41 (Ubuntu)"
  ],
  "ETag": [
   "\"9-5c8e74405be8d\""
  ],
  "Connection": [
   "close"
  ],
  "Last-Modified": [
   "Fri, 06 Aug 2021 17:21:27 GMT"
  ],
  "Content-Length": [
   "9"
  ],
  "Date": [
   "Fri, 20 Aug 2021 22:39:07 GMT"
  ],
  "Content-Type": [
   "text/plain"
  ]
 },
 "body": "3.0-1606\n",
 "url": "https://inmon.com/products/sFlow-RT/latest.txt",
 "status": 200
}

Set the HTTP handler function.

parameter	type	description
handler	Function	Function to handle HTTP requests. If request path ends with `/json`, then Function must return a JavaScript object that will be converted to JSON. If request path ends with `/txt`, then Function must return a string. Throwing the following exceptions will return corresponding HTTP status codes: `'not_found'`, `'bad_request'`, `'forbidden'`, `'conflict'`, `'service_unavailable'`, and `'internal_server_error'`.

Example

setHttpHandler(function(request) {
  return request;
});

Returns

$ curl  "http://localhost:8008/app/echo/scripts/echo.js/a/b/json?arg1=val1&arg2=val2"
{
 "path": [
  "a",
  "b"
 ],
 "method": "GET",
 "query": {
  "arg2": [
   "val2"
  ],
  "arg1": [
   "val1"
  ]
 },
 "format": "json"
}

Utilities

Decode Base64 string

parameter	type	description
encoded	String	String to decode

Returns

String

Example

var decoded = base64Decode('SGVsbG8gV29ybGQ=');
logInfo(decoded);

Result

2021-08-19T18:28:01Z INFO: Hello World

Encode Base64 string

parameter	type	description
message	String	String to encode

Returns

String

Example

var encoded = base64Encode('Hello World');
logInfo(encoded);

Result

2021-08-19T18:20:11Z INFO: SGVsbG8gV29ybGQ=

Make a DNS request.

parameter	type	description
name	String	DNS name to look up

Returns

Array[String]

Example

var result = dnsGetAllByName("sflow-rt.com");
logInfo(JSON.stringify(result));

Result

2021-08-23T19:01:10Z INFO: ["54.190.130.38"]

Format a JavaScript Date object

parameter	type	description
date	Date	Date to be formatted
format	string	See DateTimeFormatter (optional, default 'yyyy-MM-dd'T'HH:mm:ssXXX')
language	string	See Locale (optional)
country	string	See Locale (optional)
timezone	string	See ZoneId (optional)

Returns

String

Example

var str = formatDate(new Date(),'yyyy MM dd hh:mm','en','US','America/Los_Angeles');
logInfo(str);

Result

2021-08-19T18:17:29Z INFO: 2021 08 19 11:17

Format a JavaScript number

parameter	type	description
number	number	Number to be formatted
format	string	See DecimalFormat
language	string	See Locale (optional)
country	string	See Locale (optional)

Returns

String

Example

var str = formatNumber(1234,'0.###E0','en','US');
logInfo(str);

Result

2021-08-19T18:16:05Z INFO: 1.234E3

Get value of an environment variable.

parameter	type	description
name	string	Environment variable name

Returns

String

Example

var home = getenv('HOME');
logInfo(home);

Result

2021-08-19T18:13:49Z INFO: /sflow-rt

Get value of System Property

parameter	type	description
name	string	System Property name

Returns

String

Example

var ver = getSystemProperty('java.version');
logInfo(ver);

Result

2021-08-19T17:30:29Z INFO: 11.0.11

Get names of defined System Properties

Returns

Array of strings

Example

var names = getSystemPropertyNames();
logInfo(JSON.stringify(names,null,1));

Result

2021-08-19T17:26:47Z INFO: [
 "awt.toolkit",
 "java.specification.version",
 "sun.cpu.isalist",
 "http.keepAlive",
 "sun.jnu.encoding",
 "user.region",
 "java.class.path",
 "java.vm.vendor",
 "sun.arch.data.model",
 "java.vendor.url",
 "user.timezone",
 "os.name",
 "java.vm.specification.version",
 "sun.java.launcher",
 "user.country",
 "sun.boot.library.path",
 "sun.java.command",
 "jdk.debug",
 "sun.cpu.endian",
 "user.home",
 "user.language",
 "java.specification.vendor",
 "java.version.date",
 "java.home",
 "file.separator",
 "line.separator",
 "java.specification.name",
 "java.vm.specification.vendor",
 "java.awt.graphicsenv",
 "java.awt.headless",
 "http.agent",
 "java.util.logging.config.file",
 "sun.management.compiler",
 "java.runtime.version",
 "user.name",
 "path.separator",
 "os.version",
 "java.runtime.name",
 "file.encoding",
 "java.vm.name",
 "java.vendor.url.bug",
 "jetty.git.hash",
 "java.io.tmpdir",
 "script.file",
 "java.version",
 "user.dir",
 "os.arch",
 "java.vm.specification.name",
 "java.awt.printerjob",
 "sun.os.patch.level",
 "java.library.path",
 "java.vm.info",
 "java.vendor",
 "java.vm.version",
 "sun.io.unicode.encoding",
 "java.class.version"
]

Send a set of metrics to specified Graphite server using text protocol.

parameter	type	description
server	string	IP address of Graphite server
port	number	TCP port on server (optional, default 2003)
metrics	object	Metric name and value pairs

Throws

Exception for I/O errors

Example

setIntervalHandler(function(now) {
  var vals = {
    'load.sum': metric('ALL','sum:load_one')[0].metricValue || 0
  };
  try { graphite('10.0.0.1',null,vals); } catch(e) { logWarning(e); }
}, 15);

Load JavaScript file.

parameter	type	description
script	String	Name of file containing JavaScript.

Example

include(scriptdir() + '/inc/trend.js');

Return an array of CDIRs representing an IP address range

parameter	type	description
start	String	IP address at start of range
end	String	IP address at end of range

Returns

Array[String]

Throws

Exception for missing or malformed arguments

Example

var cidrs = ipRangeToCidrList('10.0.1.0','10.0.2.255');
logInfo(cidrs);

Result

2021-08-24T20:35:31Z INFO: 10.0.1.0/24,10.0.2.0/24

Log FINE level message, see Logger.fine()

Note: Edit sflow-rt/resources/config/logging.properties and set com.sflow.rt.level = FINE for messages to be logged.

parameter	type	description
message	String	Message to log

Example

logInfo('this is fine detail');

Result

2021-08-19T17:07:40Z FINE: this is fine detail

Log INFO level message, see Logger.info()

parameter	type	description
message	String	Message to log

Example

logInfo('this is for information');

Result

2021-08-19T17:07:40Z INFO: this is for information

Log SEVERE level message, see Logger.severe()

parameter	type	description
message	String	Message to log

Example

logSevere('this is severe');

Result

2021-08-19T17:07:40Z SEVERE: this is severe

Log WARNING level message, see Logger.warning()

parameter	type	description
message	String	Message to log

Example

logWarning('this is a warning');

Result

2021-08-19T17:03:09Z WARNING: this is a warning

Apply a mask to an IP address and return result in CIDR notation

parameter	type	description
address	String	IP address
bits	Number	Number of prefix bits

Returns

String

Throws

Exception for missing or malformed arguments

Example

var masked = mask('10.1.2.3',24);
var masked6 = mask('fe80::9a4b:e1ff:fe03:4a61',64);
logInfo(masked);
logInfo(masked6);

Result

2021-08-24T20:31:14Z INFO: 10.1.2.0/24
2021-08-24T20:31:14Z INFO: FE80::/64

Calculate MD5 checksum for string.

parameter	type	description
string	String	String over which checksum is to be computed.

Returns

MD5 checksum encoded as hexadecimal string

Example

var checksum = md5('Hello World');
logInfo(checksum);

Result

2021-08-19T16:57:07Z INFO: fb8919b6b96d27ce9402a5835d24779d

Run a command, see Java Runtine.exec

parameter	type	description
command	Array[String]	Command and its arguments
envp	Array[String]	Array of strings of format name=value (optional)
dir	String	Working directory for command (optional)

Returns

Object

Throws

Exception for missing or malformed arguments or I/O error

Example

var result = runCmd(['hostname','-f']);
logInfo(JSON.stringify(result));

Result

2021-08-19T16:57:07Z INFO: {"stdout":["sflow-rt"],"stderr":[],"status":0}

Asynchronously run a command, see Java Runtine.exec

parameter	type	attribute	type	description
args	object	cmd	Array[String]	Command and its arguments
		envp	Array[String]	Array of strings of format name=value (optional)
		dir	String	Working directory for command (optional)
		error	Function	Function to call with object containing status and stderr lines
		success	Function	Function to call with array of stdout lines

Throws

Exception for missing or malformed arguments or I/O error

Example

runCmdAsync({cmd:['hostname','-f'], success:(stdout)=>logInfo(stdout)});

Result

2021-08-19T16:57:07Z INFO: sflow-rt

Get directory containing this script.

Returns

String

Example

include(scriptdir() + '/inc/trend.js');

Delete value from shared volatile store

parameter	type	description
key	String	Key referencing value to be deleted

Example

sharedDelete('mykey');

Get value from shared volatile store

parameter	type	description
key	String	Key referencing value to be retrieved

Returns

Object

Example

sharedSet('mykey',{one:1,two:2});
var val = sharedGet('mykey');
logInfo(JSON.stringify(val));

Result

2021-08-23T19:32:23Z INFO: {"one":1,"two":2}

Returns list of keys from shared volatile store

Returns

Array[String]

Example

sharedSet('mykey',{one:1,two:2});
var keys = sharedKeys();
logInfo(JSON.stringify(keys));

Result

2021-08-23T19:37:16Z INFO: ["mykey"]

Save object to shared volatile store

parameter	type	description
key	String	Key to reference value being stored
value	Object	Object to be stored

Example

sharedSet('mykey',{one:1,two:2});
var val = sharedGet('mykey');
logInfo(JSON.stringify(val));

Result

2021-08-23T19:32:23Z INFO: {"one":1,"two":2}

Delete value from persistent store

parameter	type	description
key	String	Key referencing value to be deleted

Throws

Exception for I/O errors

Example

storeDelete('mykey');

Get value from persistent store

parameter	type	description
key	String	Key referencing value to be retrieved

Returns

Object

Throws

Exception for I/O errors

Example

storeSet('mykey',{one:1,two:2});
var val = storeGet('mykey');
logInfo(JSON.stringify(val));

Result

2021-08-23T19:32:23Z INFO: {"one":1,"two":2}

Returns list of keys from persistent store

Returns

Array[String]

Throws

Exception for I/O errors

Example

storeSet('mykey',{one:1,two:2});
var keys = storeKeys();
logInfo(JSON.stringify(keys));

Result

2021-08-23T19:37:16Z INFO: ["mykey"]

Save object in persistent store

parameter	type	description
key	String	Key to reference value being stored
value	Object	Object to be stored

Throws

Exception for I/O errors

Example

storeSet('mykey',{one:1,two:2});
var val = storeGet('mykey');
logInfo(JSON.stringify(val));

Result

2021-08-23T19:32:23Z INFO: {"one":1,"two":2}

Send an event to a specified syslog server.

parameter	type	description
server	string	IP address of syslog server
port	number	UDP port on server (optional, default 514)
facility	number	syslog facility (optional, default 16 (local0))
severity	number	syslog severity (optional, default 5 (notice))
params	object	key value pairs for body of message
msgid	string	RFC 5424 msgid (optional, default is to use RFC 3164 encoding)

Throws

Exception for missing or malformed arguments and I/O errors

Example

syslog('10.0.0.1',null,null,null,{type:'ddos',target:'server.local'});

Resulting log on 10.0.0.1

Aug 20 21:11:52 sflow-rt sflow-rt: type=ddos target=server.local

REST API

Use a web browser to access the sFlow-RT web user interface, by default on port 8008, and open the REST API Explorer for detailed documentation and to interact with the API.

The following REST commands are available:

application

OK if application scripts exited without error or are still running

parameter	in	required	description
name	path	true	Application name

Responses

code	description	content
200	OK	text/plain
404	Not found
503	Service Unavailable	text/plain

Information about application scripts loaded at startup

Responses

code	description	content
200	OK	application/json
404	Not found

Status of scripts loaded at startup

Responses

code	description	content
200	OK	application/json

OK if all scripts for all applications exited without error or are still running

Responses

code	description	content
200	OK	text/plain
503	Service Unavailable	text/plain

bgp

Delete Flowspec

parameter	in	required	description
router	path	true	Router IP address

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

List installed FlowSpecs

parameter	in	required	description
router	path	true	Router IP address

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not Found

Add Flowspec

parameter	in	required	description
router	path	true	Router IP address

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Get information on BGP prefix associated with IP address

parameter	in	required	description
router	path	true	Router IP address
address	query	false	IPv4 or IPv6 address to query

Responses

code	description	content
200	OK
400	Bad request

Get list of prefixes

parameter	in	required	description
router	path	false	Router IP address

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not found

Delete route

parameter	in	required	description
router	path	true	Router IP address
address	path	true	IP address part of CIDR
bits	path	true	Bits part of CIDR

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Get route

parameter	in	required	description
router	path	true	Router IP address
address	path	true	IP address part of CIDR
bits	path	true	Bits part of CIDR

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not found

Create or update route

parameter	in	required	description
router	path	true	Router IP address
address	path	true	IP address part of CIDR
bits	path	true	Bits part of CIDR

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Query for most active IPv4 prefixes

parameter	in	required	description
router	path	true	Router IP address
maxPrefixes	query	false	Maximum number of prefixes to return
minValue	query	false	Minimum value to include in result
direction	query	false	Direction of traffic, source or destination
includeCovered	query	false	Include prefixes that are covered by top prefix but wouldn't otherwise make list
pruneCovered	query	false	Eliminate covered prefixes that share same next-hop
minPrefix	query	false	Exlude short prefixes, e.g. set to 1 to exclude 0.0.0.0/0

Responses

code	description	content
200	OK

Query for most active IPv6 prefixes

parameter	in	required	description
router	path	true	Router IP address
maxPrefixes	query	false	Maximum number of prefixes to return
minValue	query	false	Minimum value to include in result
direction	query	false	Direction of traffic, source or destination
includeCovered	query	false	Include prefixes that are covered by top prefix but wouldn't otherwise make list
pruneCovered	query	false	Eliminate covered prefixes that share same next-hop
minPrefix	query	false	Exlude short prefixes, e.g. set to 1 to exclude 0.0.0.0/0

Responses

code	description	content
200	OK

flows

List top active flows

parameter	in	required	description
agent	path	true	IP address(es) or ALL or TOPOLOGY or EDGE or CORE
name	path	true	Flow definition name
maxFlows	query	false	Maximum number of flows
minValue	query	false	Minimum flow value
aggMode	query	false	Method for combining flows across data sources; sum, avg, max, edge, or core
filter	query	false	Select flow keys matching pattern

Responses

code	description	content
200	OK
400	Bad request

Get flow definitions

Responses

code	description	content
200	OK	application/json

Remove flow definition

parameter	in	required	description
name	path	true	Flow definition name

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Get flow definition

parameter	in	required	description
name	path	true	Flow definition name

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not Found

Create or update flow definition

parameter	in	required	description
name	path	true	Flow definition name

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

List available flow keys

Responses

code	description	content
200	OK

Get locations that observed a specific flow

parameter	in	required	description
agent	path	true	IP address(es) or ALL or TOPOLOGY or EDGE or CORE
name	path	true	Flow metric name, e.g. tcp
key	query	false	Flow key, e.g. 10.0.0.1,10.0.0.2,22,45333

Responses

code	description	content
200	OK
400	Bad request
404	Not found

Get most recently logged flows

parameter	in	required	description
name	query	false	Select flows matching definition name
flowID	query	false	Wait for flows after flowID
maxFlows	query	false	Maximum number of flows to return
timeout	query	false	Maximum number of seconds to wait for new flows

Responses

code	description	content
200	OK
400	Bad request

Get value for specific flow

parameter	in	required	description
agent	path	true	IP address of agent
name	path	true	Location and flow metric name, e.g. 22.tcp for tcp flows on port 22
key	query	true	Flow key, e.g. 10.0.0.1,10.0.0.2,22,45333

Responses

code	description	content
200	OK
404	Not found

forwarding

List sFlow forwarding entries

Responses

code	description	content
200	OK	application/json

Delete forwarding entry

parameter	in	required	description
name	path	true	Forwarding entry name

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Get forwarding entry

parameter	in	required	description
name	path	true	Forwarding entry name

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not Found

Create or update forwarding entry

parameter	in	required	description
name	path	true	Forwarding entry name

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

List tenant sFlow forwarding entries

Responses

code	description	content
200	OK

Delete tenant forwarding entry

parameter	in	required	description
name	path	true	Tenant name

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Get tenant sFlow forwarding entry

parameter	in	required	description
name	path	true	Tenant name

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not Found

Create or update tenant sFlow forwarding entry

parameter	in	required	description
name	path	true	Tenant name

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request

group

List address groups

Responses

code	description	content
200	OK

Delete group

parameter	in	required	description
name	path	true	Group definition name

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Get group definition

parameter	in	required	description
name	path	true	Group definition name

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not Found

Create or update group

parameter	in	required	description
name	path	true	Group definition name

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request

map

List maps

Responses

code	description	content
200	OK

Delete map

parameter	in	required	description
name	path	true	Map definition name

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Get map definition

parameter	in	required	description
name	path	true	Map definition name

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not Found

Create or update map

parameter	in	required	description
name	path	true	Map definition name

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

metrics

Get metric values

parameter	in	required	description
agent	path	true	IP address(es) or ALL or TOPOLOGY or EDGE or CORE
metric	path	true	Metric name(s) or ALL
filter	query	true	Filter data sources

Responses

code	description	content
200	OK	application/json

List names of available metrics and latest values received from agent

parameter	in	required	description
agent	path	true	IP address

Responses

code	description	content
200	OK
404	Not found

Get summary statistics for metrics

parameter	in	required	description
agent	path	true	IP address(es) or ALL or TOPOLOGY or EDGE or CORE
metric	path	true	Metric name(s)
filter	query	true	Filter data sources

Responses

code	description	content
200	OK	application/json

List names of available metrics

Responses

code	description	content
200	OK

Get Prometheus metrics

parameter	in	required	description
agent	path	true	IP address(es) or ALL or TOPOLOGY or EDGE or CORE
metric	path	true	Metric name(s) or ALL
filter	query	true	Filter data sources

Responses

code	description	content
200	OK	text/plain

Get table of metric values

parameter	in	required	description
agent	path	true	IP address(es) or ALL or TOPOLOGY or EDGE or CORE
metric	path	true	Metric name(s)
filter	query	true	Filter data sources

Responses

code	description	content
200	OK	application/json

prometheus

sFlow analyzer performance information as Prometheus metrics

Responses

code	description	content
200	OK	text/plain

Get Prometheus metrics

parameter	in	required	description
agent	path	true	IP address(es) or ALL or TOPOLOGY or EDGE or CORE
metric	path	true	Metric name(s) or ALL
filter	query	true	Filter data sources

Responses

code	description	content
200	OK	text/plain

server

List sFlow agents with session information

parameter	in	required	description
agent	query	false	Agent IP address

Responses

code	description	content
200	OK

sFlow analyzer performance information

Responses

code	description	content
200	OK

License type and status

Responses

code	description	content
200	OK

sFlow analyzer performance information as Prometheus metrics

Responses

code	description	content
200	OK	text/plain

Software version

Responses

code	description	content
200	OK	text/plain

threshold

Get most recently logged events

parameter	in	required	description
thresholdID	query	false	Select events matching threshold definition name
eventID	query	false	Wait for flows after eventID
maxEvents	query	false	Maximum number of events to return
timeout	query	false	Maximum number of seconds to wait for new events

Responses

code	description	content
200	OK
400	Bad request

List threshold definitions

Responses

code	description	content
200	OK	application/json

Delete threshold

parameter	in	required	description
name	path	true	Threshold definition name

Responses

code	description	content
204	No content
400	Bad request
403	Forbidden

Get threshold definition

parameter	in	required	description
name	path	true	Threshold definition name

Responses

code	description	content
200	OK	application/json
400	Bad request
404	Not Found

Create or update threshold definition

parameter	in	required	description
name	path	true	Threshold definition name

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content
400	Bad request

topology

Get network topology

Responses

code	description	content
200	OK	application/json

Set network topology

Request Body

type	required
application/json	true

Responses

code	description	content
204	No content

System Properties

The System Properties can be specified as arguments to the start.sh script, e.g.:

./start.sh -Dhttp.hostname=127.0.0.1 -Dhttp.port=8080

On the docker command line:

docker run -p 6343:6343/udp -p 8008:8008 sflow/sflow-rt -Dhttp.log=yes

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. Alternatively, create a file under the conf.d directory with .conf extension containing additional preferences.

Property	Default	Description
http.hostname		Bind HTTP server to specified address
http.port	8008	TCP port to receive HTTP requests
http.log	no	Set to yes to enable http request logging
http.html	yes	Set to no to exclude HTML pages
http.html.redirect	./html/index.html	Default page to display
http.readonly	no	Set to yes to prevent POST/PUT operations from modifying thresholds, flows, and groups
http.rest	yes	Set to no to disable REST API if HTML pages are disabled.
http.requestheadersize	4096	Size of the buffer to be used for request headers
http.responseheadersize	4096	Size of the buffer to be used for response headers
http.responsebuffersize	32768	Size of the content buffer for sending responses
http.idletimeout	300	Timeout in seconds before closing idle requests
http.timeout.connect	5000	Timeout in milliseconds for JavaScript HTTP client
http.timeout.read	5000	Timeout in milliseconds for JavaScript HTTP client
http.checkversion	yes	Check for sFlow-RT software updates
http.trustall	yes	Set to no to enable verification of https connections
script.file		Comma 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.file.<name>		JavaScript file to load at startup. Name is arbitrary but must be unique for script.
script.store	store	Directory for storing persistent objects for scripts
script.maxeventqueue	1000	Maximum number of events per script queue
script.maxflowqueue	1000	Maximum number of flow records per script queue
sflow.port	6343	UDP port to receive sFlow
sflow.hostname		Bind sFlow listener to specific address
sflow.file		Playback sFlow from pcap file (disables sflow.port)
sflow.dsentitytoport	yes	Set to no to allow entity packet samplers instead of converting them to virtual ingress port-based data sources
sflow.sumegress	no	Set to yes to create virtual egress sampled data sources from ingress only sampled data
sflow.maxbytes	2048	Maximum sFlow datagram size
sflow.rcvpktsbuffer	1000	Number of sflow.maxbytes byte packet buffers to request when opening the sFlow UDP socket
events.max	1000	Maximum number of events to keep
flows.max	1000	Maximum number of completed flows to keep
geo.country		GeoIP database location. Set to resources/config/GeoLite2-Country.mmdb to use GeoLite2 database
geo.asn		GeoIP database location. Set to resources/config/GeoLite2-ASN.mmdb to use GeoLite2 database
oui.names		OUI name file. Set to resources/config/oui.txt to lookup names
workers.maxqueue	400	Maximum number of sFlow datagrams to queue per worker
workers.number	4	Number of worker threads processing sFlow datagrams
receivers.number	1	Number of threads receiving sFlow datagrams and queuing them for workers
snmp.ifname	no	Set to yes to enable SNMP retrieval of interface names
snmp.version	2c	SNMP version number, valid options are 1, 2c, or 3
snmp.community	public	Set SNMP community string
snmp.user		Set SNMP user
snmp.authprotocol		Set SNMP authentication protocol, valid options are md5 or sha
snmp.authpasswd		Set SNMP authentication password
snmp.privprotocol		Set SNMP privacy protocol, valid options are des, 3des, aes128, aes192 or aes256
snmp.privpasswd		Set SNMP privacy password
tenant.portflows	no	Set to yes to apply tenant port filters to flow samples in addition to counter samples
tenant.coreflows	no	Set to yes to allow export of data from all ports (including internal inter-switch links
bgp.start	no	Set to yes to enable BGP listener
bgp.port	1179	TCP port for BGP listener
bgp.hostname		Bind BGP listener to specific address
dns.servers		Comma separated list of DNS servers or "resolv.conf" to read server addresses from /etc/resolv.conf file.
dns.port	53	UDP port to make DNS requests
dns.lc	no	Convert names to lowercase
dns.idn	no	Convert Internationalized Domain Names (IDNs) to unicode
dns.threads	2	Number of threads allocated to DNS lookups
dns.maxpending	100	Maximum number of outstanding DNS requrests
dns.timeout	5	Maximum number of seconds to wait for a DNS reply
dns.cache.size	100000	Maximum number of DNS replies to cache
dns.cache.minexpires	600	Minimum number of seconds to remember positive DNS response - overrides short DNS TTL values
dns.cache.negativettl	3600	Number of seconds to remember a negative DNS response
apps.enable	yes	Enable applications
apps.discover	yes	Automatically discover and run applications in the apps directory
app.{name}.enable	no	If apps.discover=no, then selectively enable application by setting app.{name}.enable=yes
host.ip.enable	yes	Discover IP address associated with host adapter
host.ip.refresh	10	Number of seconds before refreshing IP address to host adapter relationship

JavaScript API

Server

agents()

Returns

Example

analyzer()

Returns

Example

datasourceInfo()

Returns

Example

version()

Returns

Example

Metrics

baselineCheck()

Returns

Throws

Example

baselineCreate()

Throws

Example

baselineDelete()

Example

baselineReset()

Example

baselineStatistics()

Returns

Example

clearIntervalHandler()

Example

dump()

Returns

Example

metric()

Returns

Example

metrics()

Example

setIntervalHandler()

Throws

Example

table()

Returns

Example

Threshold

clearEventHandler()

Example

clearThreshold()

Example

setEventHandler()

Throws

Example

setThreshold()

Example

thresholdTriggered()

Returns

Example

Flows

activeFlows()

Returns

Example

clearFlow()

Example

clearFlowHandler()

Example

flowKeys()

Returns

Example

flowLocations()

Returns

Example

flowValue()

Returns

Example

flowValues()

Returns

Example

setFlow()

Example