Flow API

Use the Flow API to retrieve summary statistics and time series data derived from persisted flows.

Unless otherwise specified, all units of time are expressed in milliseconds.

GETs (Reading Data)

Resource Description

/flows/count

Retrieve the number of flows available.

/flows/exporters

Retrieve basic information for the exporter nodes that have flows available.

/flows/exporters/{nodecriteria}

Retrieve detailed information about a specific exporter node.

/flows/applications

Retrieve traffic summary statistics for the top N applications or specific applications.

/flows/applications/enumerate

Retrieve a list of the applications with flows.

/flows/applications/series

Retrieve time series metrics for the top N applications or specific applications.

/flows/conversations

Retrieve traffic summary statistics for the top N conversations or specific conversations.

/flows/conversations/enumerate

Retrieve a list of the conversations with flows.

/flows/conversations/series

Retrieve time series metrics for the top N conversations or specific conversations.

/flows/hosts

Retrieve traffic summary statistics for the top N hosts or specific hosts.

/flows/hosts/enumerate

Retrieve a list of the hosts with flows.

/flows/hosts/series

Retrieve time series metrics for the top N hosts or specific hosts.

All of the endpoints support the following query string parameters to help filter the results:

The given filters are combined using a logical AND. There is no support for using OR logic, or combinations thereof.

Name

Default

Comment

start

-14400000

Timestamp in milliseconds.

If > 0, the timestamp is relative to the UNIX epoch (January 1st 1970 00:00:00 AM).

If < 0, the timestamp is relative to the end option (i.e., default value is 4 hours ago).

end

0

Timestamp in milliseconds. If <= 0, the effective value will be the current timestamp.

ifIndex

(none)

Filter for flows that came in through the given SNMP interface.

exporterNode

(none)

Filter for flows that were exported by the given node.

Support either node id (integer) i.e., 1, or foreign source and foreign id lookups i.e., FS:FID.

The exporters endpoints do not support any parameters.

The applications/enumerate endpoint also supports:

Name Default Comment

limit

10

Number of applications with flows to return.

prefix

""

If provided, filters the results to only include applications with names that start with the given prefix (using fuzzy matching).

The applications and applications/series endpoints also support:

name default comment

N

none

Number of top entries (determined by total bytes transferred) to return.

includeOther

false

When set to true the results will also include an additional row or column that contains the bytes transferred for the flows that fall outside of the selected set.

application

none

If provided, returns only flow series that match the given application(s). This field can be repeated for any number of applications to be included in the query.

Both endpoints require one of N or application query parameters to be set and will return an error if neither or both are set.

The conversations/enumerate endpoint also supports:

Name Default Comment

limit

10

Number of hosts with flows to return.

location

".*"

If provided, filters the results to only include conversations matching the given location regex pattern.

protocol

".*"

If provided, filters the results to only include conversations matching the given protocol regex pattern.

lower

".*"

If provided, filters the results to only include conversations matching the given lower IP address regex pattern.

upper

".*"

If provided, filters the results to only include conversations matching the given upper IP address regex pattern.

application

".*"

If provided, filters the results to only include conversations matching the given application regex pattern.

The conversations and conversations/series endpoints also supports:

Name Default Comment

N

10

Number of top entries (determined by total bytes transferred) to return.

includeOther

false

When set to true the results will also include an additional row or column that contains the bytes transferred for the flows that fall outside of selected set.

conversation

none

If provided, returns only flow series that match the given conversation(s). This field can be repeated for any number of conversations to be included in the query.

hostname_mode

"replace"

Controls how IP addresses are replaced with hostnames if available:

  • replace will replace the IP with the hostname

  • append will append the hostname to the IP address

  • hide will not show the hostname at all
Make sure to URL encode the conversation value in your request.

Both endpoints require one of N or conversation query parameters to be set and will return an error if neither or both are set.

The conversations/series endpoint also supports:

Name Default Comment

step

300000

Requested time interval between rows.

The hosts/enumerate endpoint also supports:

Name Default Comment

limit

10

Number of hosts with flows to return.

pattern

".*"

If provided, filters the results to only include hosts with names that match the given regex pattern.

The hosts and hosts/series endpoints also support:

Name Default Comment

N

none

Number of top entries (determined by total bytes transferred) to return.

includeOther

false

When set to true the results will also include an additional row or column that contains the bytes transferred for the flows that fall outside of the selected set.

host

none

If provided, returns only flow series that match the given host(s). This field can be repeated for any number of hosts to be included in the query.

Both endpoints require one of N or host query parameters to be set and will return an error if neither or both are set.

Examples

Retrieve the number of flows persisted in the last 4 hours
curl -u admin:admin http://localhost:8980/opennms/rest/flows/count
Response
915
Retrieve traffic summary for top 10 applications in the last 4 hours
curl -u admin:admin http://localhost:8980/opennms/rest/flows/applications
Response
{
	"start": 1513788044417,
	"end": 1513802444417,
	"headers": ["Application", "Bytes In", "Bytes Out"],
	"rows": [
		["https", 48789, 136626],
		["http", 12430, 5265]
	]
}
Retrieve traffic summary for top 10 conversations in the last 4 hours
curl -u admin:admin http://localhost:8980/opennms/rest/flows/conversations
Response
{
	"start": 1513788228224,
	"end": 1513802628224,
	"headers": ["Location", "Protocol", "Source IP", "Source Port", "Dest. IP", "Dest. Port", "Bytes In", "Bytes Out"],
	"rows": [
		["Default", 17, "10.0.2.15", 33816, "172.217.0.66", 443, 12166, 117297],
		["Default", 17, "10.0.2.15", 32966, "172.217.0.70", 443, 5042, 107542],
		["Default", 17, "10.0.2.15", 54087, "172.217.0.67", 443, 55393, 5781],
		["Default", 17, "10.0.2.15", 58046, "172.217.0.70", 443, 4284, 46986],
		["Default", 6, "10.0.2.15", 39300, "69.172.216.58", 80, 969, 48178],
		["Default", 17, "10.0.2.15", 48691, "64.233.176.154", 443, 8187, 39847],
		["Default", 17, "10.0.2.15", 39933, "172.217.0.65", 443, 1158, 33913],
		["Default", 17, "10.0.2.15", 60751, "216.58.218.4", 443, 5504, 24957],
		["Default", 17, "10.0.2.15", 51972, "172.217.0.65", 443, 2666, 22556],
		["Default", 6, "10.0.2.15", 46644, "31.13.65.7", 443, 459, 16952]
	]
}
Retrieve time series data for top 3 applications in the last 4 hours
curl -u admin:admin http://localhost:8980/opennms/rest/flows/applications/series?N=3&includeOther=true&step=3600000
Response
{
    "start": 1516292071742,
    "end": 1516306471742,
    "columns": [
        {
            "label": "domain",
            "ingress": true
        },
        {
            "label": "https",
            "ingress": true
        },
        {
            "label": "http",
            "ingress": true
        },
        {
            "label": "Other",
            "ingress": true
        }
    ],
    "timestamps": [
        1516291200000,
        1516294800000,
        1516298400000
    ],
    "values": [
        [9725, 12962, 9725],
        [70665, 125044, 70585],
        [10937,13141,10929],
        [1976,2508,2615]
    ]
}
Retrieve time series data for top 3 conversations in the last 4 hours
curl -u admin:admin http://localhost:8980/opennms/rest/flows/conversations/series?N=3&step=3600000
Response
{
    "start": 1516292150407,
    "end": 1516306550407,
    "columns": [
        {
            "label": "10.0.2.15:55056 <-> 152.19.134.142:443",
            "ingress": false
        },
        {
            "label": "10.0.2.15:55056 <-> 152.19.134.142:443",
            "ingress": true
        },
        {
            "label": "10.0.2.15:55058 <-> 152.19.134.142:443",
            "ingress": false
        },
        {
            "label": "10.0.2.15:55058 <-> 152.19.134.142:443",
            "ingress": true
        },
        {
            "label": "10.0.2.2:61470 <-> 10.0.2.15:8980",
            "ingress": false
        },
        {
            "label": "10.0.2.2:61470 <-> 10.0.2.15:8980",
            "ingress": true
        }
    ],
    "timestamps": [
        1516294800000,
        1516298400000
    ],
    "values": [
        [17116,"NaN"],
        [1426,"NaN"],
        [20395,"NaN",
        [1455,"NaN"],
        ["NaN",5917],
        ["NaN",2739]
    ]
}