Metrics API

The inbound Metrics API provides an endpoint where you can send time series metrics from your monitoring services. For example, you can set up a simple script that regularly posts data to the REST integration. Alternatively, you could set up the REST integration as an endpoint for a webhook from a monitoring system.

For a full description of the metric schema, see Metrics API schema below. The Integrations > Inbound Integrations > Metrics. page also includes auto-generated cURL commands with example JSON metrics. The metric schema is highly flexible, with a few required fields, several more optional fields, and a tags field for including additional data.

Note the following:

  • All timestamps must be specified as UNIX timestamps normalized to Coordinated Universal Time (UTC).

  • Express stores all timestamps in UTC format. The dates and times displayed in the UI are based on your browser's local time.

  • This integration expects data in the following JSON format. The "data" and "source" fields are required. If you do not specify a timestamp, the "timestamp" value is the time when Express ingests the metric.

    '{
       "data": <datum> , 
       "source": <source>, 
       "timestamp": <timestamp>
    }'
  • You can include metadata as additional key/value pairs in a JSON data point, although Express only considers the "data" key when detecting anomalies. For example, you can specify a data point such as:

    '{
        "data": 1.2345 , 
        "source": "source.server.com", 
        "timestamp": 1571435450540, 
        "tags": {
            "protocol" : "tcp",
            "seq" : 12, 
            "total" : 157, 
            "bytes" : 1274
        } 
    }'
  • Express uses the Adaptive anomaly detector with default settings on all metrics ingested through the API. Custom anomaly detection of these metrics is not supported. The Adaptive detector identifies anomalies based on a statistical calculation against a median absolute deviation. This deviation varies over time and determines the high and low thresholds.

  • To search for metrics that were ingested via the API, go to the UI > Metrics page and enter the following search:

    "managed object" = moog:integration:rest
  • You can use the Collectors API to do the following:

    • Retrieve metric data from a collector.

    • Post metric data from a collector.

    • Retrieve the set of available metrics from a collector.

Metrics API schema

This table describes the JSON schema for posting metric data to Express.

Metric fields

Table 1. Metrics API field reference

Field

Description

Type

metric

REQUIRED

A human-readable description of the metric. A good description summarizes the exact condition that the metric measures. You can also specify this in the description itself or in the unit field described below. Examples include:

  • "en0 bandwidth util %"

  • "myApp response time msec"

  • "myWebService 4xx https responses/sec %"

  • "myService available"

When Express creates or updates an alert with a new metric, this description becomes the alert description.

string

data

REQUIRED

The numerical value of the data point.

Integer

source

REQUIRED

The server, node, or other entity that generated the metric. This can be any unique, human-readable name such as a hostname, fully qualified domain name, or URL. 

In some cases, a process or application might trigger a metric that has no node identification. In this case, specify a unique identifier of the generating instance such as a database name, container name, or cluster node name.

string

time

Event time in UTC format. You can specify the time in either seconds or milliseconds. If the payload does not include a time, Express uses the event arrival time.

integer

key

This field is useful for classifying different metrics that share the same description. For example, the metric name might be "throughput in bps" and the key might be "eth0."

string

tags

If desired, you can include additional information about an event using the tags key. You can specify data as an array or as a series of key-value pairs.

JSON object



Metric schema example

 {
    "metric": "your-metric",
    "data": 10,
    "source": "www.your-source.com",
    "time": 1585589286917,
    "key": "dev",
    "tags": {
        "key": "value"
    }

API specification