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)

Measurements API GET function
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

Name	Default Value	Description
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.
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 `AVERAGE`, `MIN`, or `MAX`. Depends on `RRA` definitions.
fallback-attribute	Blank	Secondary attribute that will be queried if the primary attribute does not exist.

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

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

step

300000

Requested time interval between rows. Actual step may differ.

maxrows

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 AVERAGE, MIN, or MAX. Depends on RRA definitions.

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

Retrieve CPU counter metrics over the last 2 hours for node 1

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"

Response

<?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)

Measurements API POST function
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

Retrieve bits in and bits out metrics for a particular interface. Perform calculations on bits out, and only return the derived values.

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

Contents of report.json

{
    "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"
        }
    ]
}

Response

{
    "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.

Advanced JEXL expressions
Constant/Prefix	Description
__inf	`Double.POSITIVE_INFINITY`
__neg_inf	`Double.NEGATIVE_INFINITY`
NaN	`Double.NaN`
__E	`java.lang.Math.E`
__PI	`java.lang.Math.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 `AttributeName` is the searched-for attribute)	This returns the complete `double[]` array of samples for `AttributeName`.

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.

Meridian predefined functions
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 `java.lang.Math` class.	math:cos(20)
strictmath:	References `java.lang.StrictMath` class.	math:cos(20)
fn:	References the class `org.opennms.netmgt.measurements.impl.SampleArrayFunctions`. This contains several functions that can reference previous samples in the time series.	None
fn:arrayNaN("sampleName", n)	References the nth previous sample in the "sampleName" sample series, replacing the `N` samples before the start of the series with `NaN`.	fn:arrayNaN("x", 5)
fn:arrayZero("sampleName", n)	References the nth previous sample in the "sampleName" sample series, replacing the `N` samples before the start of the series with `0`.	fn:arrayZero("x", 5)
fn:arrayFirst("sampleName", n)	References the nth previous sample in the "sampleName" sample series, replacing the `N` samples before the start of the series with the first sample.	fn:arrayFirst("x", 5)
fn:arrayStart("sampleName", n, constant)	References the nth previous sample in the "sampleName" sample series, replacing the `N` samples before the start of the series with a supplied constant.	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)