Measurements API
Use the Measurements API to retrieve collected values stored in RRD (or JRB) files and in Newts.
Unless otherwise specified, all units of time are expressed in milliseconds. |
GETs (reading data)
Resource | Description |
---|---|
/measurements/{resourceid}/{attribute} |
Retrieve the measurements for a single attribute. |
The following table shows all supported query string parameters and their default values:
Name | Default Value | Description |
---|---|---|
start |
-14400000 |
Timestamp. |
end |
0 |
Timestamp.
If <= |
step |
300000 |
Requested time interval between rows. Actual step may differ. |
maxrows |
0 |
When using the measurements to render a graph, this should be set to the graph’s pixel width. |
aggregation |
AVERAGE |
Consolidation function used.
Can typically be |
fallback-attribute |
Blank |
Secondary attribute that will be queried if the primary attribute does not exist. |
Step sizes
The behavior of the step
parameter changes based on the time series strategy in use.
When using persistence strategies based on RRD, the available step sizes are limited to those defined by the RRA when the file was created. The effective step size used will be one that covers the requested period, and is closest to the requested step size. For maximum accuracy, use a step size of 1.
When using Newts, you can set the step size arbitrarily since the aggregation is performed at the time of request.
To help prevent large requests, we limit the step size to a minimum of 5 minutes, the default collection rate.
Decrease this value by setting the org.opennms.newts.query.minimum_step
system property.
Use examples with cURL
curl -u admin:admin "http://127.0.0.1:8980/opennms/rest/measurements/node%5B1%5D.nodeSnmp%5B%5D/CpuRawUser?start=-7200000&maxrows=30&aggregation=AVERAGE"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<query-response end="1425588138256" start="1425580938256" step="300000">
<columns>
<values>159.5957271523179</values>
<values>158.08531037527592</values>
<values>158.45835584842285</values>
...
</columns>
<labels>CpuRawUser</labels>
<metadata>
<resources>
...
</resources>
<nodes>
...
</nodes>
</metadata>
<timestamps>1425581100000</timestamps>
<timestamps>1425581400000</timestamps>
<timestamps>1425581700000</timestamps>
...
</query-response>
POST (reading data)
Resource | Description |
---|---|
/measurements |
Retrieve the measurements for one or more attributes, possibly spanning multiple resources, with support for JEXL expressions. |
Here we use a POST instead of a GET to retrieve the measurements, which lets you perform complex queries that are difficult to express in a query string. These requests cannot be used to update or create new metrics.
An example of the POST body is available below.
Use examples with cURL
curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -u admin:admin -d @report.json http://127.0.0.1:8980/opennms/rest/measurements
{
"start": 1425563626316,
"end": 1425585226316,
"step": 10000,
"maxrows": 1600,
"source": [
{
"aggregation": "AVERAGE",
"attribute": "ifHCInOctets",
"label": "ifHCInOctets",
"resourceId": "nodeSource[Servers:1424038123222].interfaceSnmp[eth0-04013f75f101]",
"transient": "false"
},
{
"aggregation": "AVERAGE",
"attribute": "ifHCOutOctets",
"label": "ifHCOutOctets",
"resourceId": "nodeSource[Servers:1424038123222].interfaceSnmp[eth0-04013f75f101]",
"transient": "true"
}
],
"expression": [
{
"label": "ifHCOutOctetsNeg",
"value": "-1.0 * ifHCOutOctets",
"transient": "false"
}
]
}
{
"step": 300000,
"start": 1425563626316,
"end": 1425585226316,
"timestamps": [
1425563700000,
1425564000000,
1425564300000,
...
],
"labels": [
"ifHCInOctets",
"ifHCOutOctetsNeg"
],
"columns": [
{
"values": [
139.94817275747508,
199.0062569213732,
162.6264894795127,
...
]
},
{
"values": [
-151.66179401993355,
-214.7415503875969,
-184.9012624584718,
...
]
}
],
"metadata": {
"resources": [
{
"id": "nodeSource[Servers:1424038123222].interfaceSnmp[eth0-04013f75f101]",
"label": "eth0-04013f75f101",
"name": "eth0-04013f75f101",
"parent-id": "nodeSource[Servers:1424038123222]",
"node-id": 1
},
{
"id": "nodeSource[Servers:1424038123222].interfaceSnmp[eth0-04013f75f101]",
"label": "eth0-04013f75f101",
"name": "eth0-04013f75f101",
"parent-id": "nodeSource[Servers:1424038123222]",
"node-id": 1
}
],
"nodes": [
{
"id": 1,
"label": "Test Server",
"foreign-source": "Servers",
"foreign-id": "1424038123222"
}
]
}
}
More advanced expressions
The JEXL 2.1.x library is used to parse the expression string and this also lets Java objects and predefined functions to be included in the expression.
JEXL uses a context that is pre-populated by OpenNMS with the results of the query. Several constants and arrays are also predefined as references in the context by OpenNMS.
Constant/Prefix | Description |
---|---|
__inf |
|
__neg_inf |
|
NaN |
|
__E |
|
__PI |
|
__diff_time |
Time span between start and end of samples. |
__step |
Difference in time between subsequent values. |
__i |
Index into the samples array which the present calculation is referencing. |
__AttributeName (where |
This returns the complete |
OpenNMS predefines a number of functions for use in expressions that are referenced by namespace:function
.
All of these functions return a Java double value.
Function | Description | Example |
---|---|---|
jexl:evaluate("_formula"): |
Passes a string to the JEXL engine to be evaluated as if it were entered as a normal expression. Like normal expressions, expressions evaluated through this function will return a Java double value. This makes it possible to reference and evaluate a formula that has been stored in Meridian as a string variable. The use case for this capability is that it gives us the ability to define and store a per-node and per-value correction formula that can normalize samples from different sample sources. |
None |
math: |
References |
math:cos(20) |
strictmath: |
References |
math:cos(20) |
fn: |
References the class |
None |
fn:arrayNaN("sampleName", n) |
References the nth previous sample in the "sampleName" sample series, replacing the |
fn:arrayNaN("x", 5) |
fn:arrayZero("sampleName", n) |
References the nth previous sample in the "sampleName" sample series, replacing the |
fn:arrayZero("x", 5) |
fn:arrayFirst("sampleName", n) |
References the nth previous sample in the "sampleName" sample series, replacing the |
fn:arrayFirst("x", 5) |
fn:arrayStart("sampleName", n, constant) |
References the nth previous sample in the "sampleName" sample series, replacing the |
fn:arrayStart("x", 5, 10) |
With these additional variables and functions it is possible, for example, to create a finite impulse response (FIR) filter function such as
y = a * f(n) + b * f(n-1) + c * f(n-2)
using the following expression where a, b, and c are string constants and x is a time series value
a * x + b * fn:arrayNaN("x", 1) + c * fn:arrayNaN("x", 2)