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 |
/flows/applications/enumerate |
Retrieve a list of the applications with flows. |
/flows/applications/series |
Retrieve time series metrics for the top |
/flows/conversations |
Retrieve traffic summary statistics for the top |
/flows/conversations/enumerate |
Retrieve a list of the conversations with flows. |
/flows/conversations/series |
Retrieve time series metrics for the top |
/flows/hosts |
Retrieve traffic summary statistics for the top |
/flows/hosts/enumerate |
Retrieve a list of the hosts with flows. |
/flows/hosts/series |
Retrieve time series metrics for the top |
All of the endpoints support the following query string parameters to help filter the results:
Name | Default Value | Comment |
---|---|---|
start |
-14400000 |
Timestamp. |
end |
0 |
Timestamp.
If <= |
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. |
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 |
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 |
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:
|
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 |
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
curl -u admin:admin http://localhost:8980/opennms/rest/flows/count
915
curl -u admin:admin http://localhost:8980/opennms/rest/flows/applications
{
"start": 1513788044417,
"end": 1513802444417,
"headers": ["Application", "Bytes In", "Bytes Out"],
"rows": [
["https", 48789, 136626],
["http", 12430, 5265]
]
}
curl -u admin:admin http://localhost:8980/opennms/rest/flows/conversations
{
"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]
]
}
curl -u admin:admin http://localhost:8980/opennms/rest/flows/applications/series?N=3&includeOther=true&step=3600000
{
"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]
]
}
curl -u admin:admin http://localhost:8980/opennms/rest/flows/conversations/series?N=3&step=3600000
{
"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]
]
}