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)

Flow API GET functions
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:

Name Default Value Comment

start

-14400000

Timestamp.
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 (for example, default value is 4 hours ago).

end

0

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

ifIndex

Blank

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

exporterNode

Blank

Filter for flows that were exported by the given node.
Support either node ID (for example, 1), or foreign source and foreign ID lookups (for example, FS:FID).
The given filters are combined using a logical AND. There is no support for using OR logic, or combinations thereof.

The exporters endpoints do not support any parameters.

The applications/enumerate endpoint also supports:

Name Default Value Comment

limit

10

Number of applications with flows to return.

prefix

Blank

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

The applications and applications/series endpoints also support:

Name Default Value Comment

N

Blank

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

Blank

If provided, returns only flow series that match the given applications. 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 Value Comment

limit

10

Number of hosts with flows to return.

location

".*"

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

protocol

".*"

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

lower

".*"

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

upper

".*"

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

application

".*"

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

The conversations and conversations/series endpoints also support:

Name Default Value 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 the selected set.

conversation

Blank

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

hostname_mode

replace

Controls how IP addresses are replaced with hostnames if available:

  • replace will replace the IP address 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 Value Comment

step

300000

Requested time interval between rows.

The hosts/enumerate endpoint also supports:

Name Default Value Comment

limit

10

Number of hosts with flows to return.

pattern

".*"

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

The hosts and hosts/series endpoints also support:

Name Default Value Comment

N

Blank

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

Blank

If provided, returns only flow series that match the given hosts. 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]
    ]
}