Metrics: List

Description

Retrieves a list of metrics matching the specified filters.

Request

Method Path
GET /api/v1/metrics

Query Parameters

Name Type Description
expression string Include metrics that match a filter expression consisting of fields and operators. Example: name LIKE 'cpu*'.
Supported wildcards: * and ?.
minInsertDate string Include metrics with lastInsertDate equal or greater than minInsertDate.
ISO-8601 date or a calendar expression.
maxInsertDate string Include metrics with lastInsertDate less than maxInsertDate, including metrics without lastInsertDate.
ISO-8601 date or a calendar expression.
limit integer Maximum number of metrics to retrieve, ordered by name.
tags string Comma-separated list of metric tag names to include in the response, for example, tags=table,frequency.
Specify tags=* to include all metric tags.
Specify tags=env.* to include all metric tags starting with env..
addInsertTime boolean Controls whether lastInsertDate field is included in the response.
The default value is inherited from the default.addInsertTime setting on the Settings > Server Properties page which is set to true by default.

Expression

The expression can include any field listed below, such as name, label, and minValue, except the filter field and lastInsertDate which can be filtered using minInsertDate and maxInsertDate parameters for performance reasons.

String literals must be enclosed in single or double quotes.

Examples:

name LIKE 'meminfo.*'
name NOT LIKE 'cpu*' AND createdDate > '2017-10-01T00:00:00Z'
retentionDays > 0 OR seriesRetentionDays > 0

Response

Fields

Name Type Description
name string Metric name.
label string Metric label.
description string Metric description.
tags object An object containing tags as names and values.
For example, "tags": {"table": "axibase-collector"}
dataType string Data Type.
interpolate string Interpolation mode: LINEAR or PREVIOUS.
Used in SQL WITH INTERPOLATE clause when interpolation mode is set to AUTO, for example, WITH INTERPOLATE(1 MINUTE, AUTO).
units string Measurement units.
timeZone string Time Zone ID, for example EST.
Refer to Time Zone table for a list of supported Time Zone IDs.
The time zone is applied by date-formatting functions to return local time in metric-specific time zone.
timePrecision string Time precision: SECONDS or MILLISECONDS.
enabled boolean Enabled status. Incoming data is discarded for disabled metrics.
persistent boolean Persistence status. Non-persistent metrics are not stored in the database and are only processed by the rule engine.
filter string Persistence filter expression. Discards series that do not match this filter.
createdDate string Date when this metric was created in ISO-8601 format.
lastInsertDate string Last time a value was received for this metric by any series in ISO-8601 format.
retentionDays integer Number of days to store the values for this metric. Samples with insert date earlier than current time minus retention days are removed on schedule.
seriesRetentionDays integer Number of days to retain series. Expired series with last insert date earlier than current time minus series retention days are removed on schedule.
versioned boolean If set to true, enables versioning for the specified metric.
When metrics are versioned, the database retains the history of series value changes for the same timestamp along with version_source and version_status.
minValue double Minimum value for Invalid Action trigger.
maxValue double Maximum value for Invalid Action trigger.
invalidAction string Invalid Action type.

Data Types

Type Storage Size, bytes
SHORT 2
INTEGER 4
LONG 8
FLOAT 4
DOUBLE 8
DECIMAL variable

Default data type for new metrics, when auto-created, is float.

Invalid Actions

Invalid Action is triggered if the received series value is less than the Minimum value, or if the value is greater than the Maximum value.

Action Description
NONE Retain value as is.
DISCARD Do not process the received value, discard it.
TRANSFORM Set value to min_value or max_value, if value is outside of range.
RAISE_ERROR Log an ERROR event in the database log.
SET_VERION_STATUS For versioned metrics, set status to 'Invalid'.

Interpolate

Type
LINEAR
PREVIOUS

Time Precision

Precision
MILLISECONDS
SECONDS

Example 1

Request

URI

GET /api/v1/metrics?limit=2

Payload

None.

curl

curl https://atsd_hostname:8443/api/v1/metrics?limit=2 \
  --insecure --include --user {username}:{password}

Response

[
  {
    "name": "m-vers",
    "enabled": true,
    "dataType": "FLOAT",
    "persistent": true,
    "timePrecision": "MILLISECONDS",
    "retentionDays": 0,
    "invalidAction": "NONE",
    "lastInsertDate": "2016-05-19T00:15:02.000Z",
    "versioned": true,
    "interpolate":"LINEAR",
    "createdDate": "2015-10-03T07:03:45.558Z"
  },
  {
    "name": "temperature",
    "enabled": true,
    "dataType": "FLOAT",
    "persistent": true,
    "timePrecision": "MILLISECONDS",
    "retentionDays": 0,
    "invalidAction": "NONE",
    "lastInsertDate": "2016-05-18T00:35:12.000Z",
    "versioned": false,
    "interpolate":"LINEAR",
    "timeZone":"America/New_York"
  }
]

Example 2

Expression text:

name != "" OR tags.keyName != "" OR label! = "" OR description != "" OR enabled = true OR persistent=true OR persistenceFilter != "" OR retentionDays=0 OR dataType="FLOAT" OR timePrecision="MILLISECONDS" OR versioning=false AND invalidAction="NONE" OR timeZone="" OR interpolate="LINEAR"

Request

URI

GET /api/v1/metrics?tags=*&expression=versioning=true%20and%20retentionDays%3E0%20and%20dataType=%22FLOAT%22

Payload

None.

curl

curl "https://atsd_hostname:8443/api/v1/metrics?expression=versioning=true%20and%20retentionDays%3E0%20and%20dataType=%22FLOAT%22" \
  --insecure --include --user {username}:{password}

Response

[
  {
    "name": "metric",
    "enabled": true,
    "dataType": "FLOAT",
    "persistent": true,
    "timePrecision": "MILLISECONDS",
    "retentionDays": 3,
    "invalidAction": "NONE",
    "lastInsertDate": "2016-10-28T08:18:17.218Z",
    "versioned": true,
    "interpolate": "LINEAR"
  }
]

Additional Examples