Metrics() Function

To get metric data, use the metrics() function.

This function provides a way to retrieve:

metric time series
metric data rollup into a single scalar value

Additionally, you can:

slice metric data by dimensions
filter metric data by dimension values
get metric data for all the sources
perform arithmetic metric expression calculations

The structure of the metrics() function is as follows:

Code Snippet

Copy
FETCH
   serviceId: id,
   metrics(calls_per_minute, infra_source)
      [attributes(region) IN ['pdx', 'fra']]
      {timestamp, value, max, percentile(99.98)}
FROM
   entities(service_type)
LIMITS
   metrics.granularityDuration(PT5M)

Supported Metric Consumption Functions

The supported consumption functions are:

Function	Description
`average()`	Returns the average value of a metric data for a time period.
`count()`	Returns the number of measurements of a metric data for a time period.
`groupCount()`	Returns the number of instances involved in generating metric data.
`max()`	Returns the maximum value of a metric data for a time period.
`min()`	Returns the minimum value of a metric data for a time period.
`ratePerMin()`	Returns the rate of change per minute of a metric data for a time period.
`ratePerSec()`	Returns the rate of change per second of a metric data for a time period.
`stdDev()`	Returns the standard deviation of a metric data.
`sum()`	Returns the sum of the metric values for a time period.
`sumCumulative()`	The sum of the cumulative metric values for a time period.
`value()`	Returns a reference to the metric category's underlying function.
`weightValue()`	Returns a weighted value for a metric.
`weightValueSquare()`	Returns a weighted value square for a metric.

Parameters, Filters, Fields

Code Snippet

Copymetrics(<metric-type>, <source>)[<filter-expression>]{<fields>}
metrics(<metric-type>, <source>)[<filter-expression>].<field>

Parameters

<metric-type> (mandatory): the metric type that identifies the metric. For example, common:calls_per_minute.
<source> (optional): the source that identifies the metric, for example, infra-agent; if you omit this parameter, the returned metric data is grouped per available source.

Filter expression

The filter expression allows you to set criteria for the dimensions such as:

To filter for values of attributes (for example, attributes("location")), tags (for example, tags("my-tag")), source (i.e., source)
To use operators:
- equal =
- not equal !=,
- IN []
- Like ~ for wildcard filtering

For more information, see Filters.

Example:

The following is an example of a filter expression:

Code Snippet

Copy
   FETCH
      metrics(calls_per_minute, infra_source)
         [attributes(region) IN ['pdx', 'fra'] && tags(health) != 0 && attributes("os") = 'linux']
         {timestamp, value, max}
   FROM
      entities(service_type)

Getting the time series of value and max of the calls per minute for the infra_source source. Limiting to only services in the regions pdx and fra with non-zero health tag and with os equal to linux.

Fields

The fields / field allows you to specify what exact data to fetch. You can specify:

consumption function(s) such as {max, min} or just .sum
attributes such as attributes("location")
tags such as tags("my-tag-name")
timestamp

Example:

Code Snippet

Copy
   FETCH
      metrics(logs_per_minute, infra_source)
      {timestamp, count, attributes("severity")}
   FROM
      entities(service_type)

Fetches the time series of count of the logs per minute for the infra_source source. Slices the resulting metrics per attribute severity, effectively dividing into buckets with severities (for example, error, warn, ...)

Metric Expressions

Use the Metric Expressions to request the Metric Store to perform basic arithmetic operations over constants and/or other metrics. The expression calculation is entirely done by Metric Store.

Note

The arithmetic operations' priority applies

Use parenthesis to group binary operations as you like

Use as many distinct metrics you want in an expression

Use constants on any side of the binary operation

Example 1:

The metric expression for time series:

Code Snippet

Copy
   FETCH
      metrics(errors, infra){timestamp, count} / metrics(calls, "sys:derived"){timestamp, count} * 100
   FROM
      entities(service_type)

Fetches percentage of errors out of all calls.

Example 2:

The metric expression for inline rollup metric:

Code Snippet

Copy
   FETCH
      metrics(errors, infra).count / metrics(calls, cloudmon).count * 100
   FROM
      entities(service_type)

Fetches percentage of errors rollup value out of all calls.

Example 3:

The metric expression for the referenced rollup metric:

Code Snippet

Copy
   FETCH
      metrics(errors, infra){count} / metrics(calls, infra){count} * 100
   FROM
      entities(service_type)

Fetches percentage of errors rollup value out of all calls.

Everything that is acceptable for the metrics() function is also valid for metric expressions. However, the following limitations apply:

UQL supports +,-,* and / binary operations only
You must provide a source dimension for each metric
You must provide a single consumption function only in the scope of a metric
You cannot include filter expressions over metrics within a metric expression
You cannot mix the time series metrics with rollup metrics in the same expression
UQL does not support Unary operations
You can use only a single entity set throughout a particular metric expression

Limits

Use the following options to limit the returned metric data:

To set the maximum number of returned data points:
Code Snippet
CopyLIMITS metrics.granularityDataPoints(50)
Returns up to 50 data points for all the queried time series of the given time range.
To set the minimum duration of each of the returned data points:
Code Snippet
CopyLIMITS metrics.granularityDuration(PT5M)
The returned time series contains data points of at least 5 minutes duration.
To set rounding to N decimal places on numeric values:
Code Snippet
CopyLIMITS metrics.round(3)
The returned time series and rollup values will be rounded using half-up method after the 3rd position after decimal point.

Rules to Round the Values

Limit without scale value LIMITS metrics.round rounds the metric values to integers
Integer values are not converted to decimals when non-zero rounding is set
When you set the rounding to 0, all decimal values are converted to integers
Rounding does not add tailing zeros

All these rules apply to the entire UQL query.

Result

What you specify in the parameters and the fields determines the structure of the result. For example,

Source parameter [yes], timestamp field [yes]

Given:

timestamp field is present
source parameter is present

Then the resulting data is of

type: timeseries
form: reference

Example:

Code Snippet

Copymetrics("common:calls_per_minute", "infra-agent"){max, min, timestamp}

Fetches time series of max and min followed by each data point timestamp of the calls per minute for the infra-agent source.

Note that if you omit the fields section, then it is equal to {timestamp, value}, which is also applicable for metric expressions.

Source parameter [yes], timestamp field [no]

Given:

timestamp field is missing
source parameter is present

Then the resulting data is of

type: complex
form: reference

Examples:

Code Snippet

Copymetrics(common:calls_per_minute, "infra-agent"){max, min}

Fetches max and min of the calls per minute for the infra-agent source.

This is also applicable for metric expressions that are requesting rollup data, but metric expression just accepts a single referenced consumption function.

Code Snippet

Copymetrics(errors, infra){count} / metrics(calls, infra){count} * 100

Fetches percentage of errors out of all calls rollup metric.

Source parameter [yes], timestamp field [no], single consumption function

Given:

timestamp field is missing
source parameter is present
single consumption function connected with . is used (for example, .max)

Then the resulting data is of

-type: number -form: inline

Examples:

Code Snippet

Copymetrics("common:calls_per_minute", "infra-agent").sum

Fetches time rollup of sum of the calls per minute for the infra-agent source.

This is also applicable for metric expressions that are requesting rollup data.

Code Snippet

Copymetrics(errors, infra).count / metrics(calls, infra).count * 100

Fetches percentage of errors out of all calls rollup metric.

Source parameter [no], timestamp field [yes]

Given:

-timestamp field is present

source parameter is missing

Then the resulting data is of

type: complex
form: reference
fields: (1) source and (2) inlined 2-dimensional array of metric data of type: timeseries

Example:

Code Snippet

Copymetrics("common:calls_per_minute"){max, min, timestamp}

Fetches time series of max and min followed by each data point timestamp of the calls per minute grouped per available source.

Source parameter [no], timestamp field [no]

Given:

timestamp field is missing
source parameter is missing

Then the resulting data is of

type: complex
form: reference
fields: (1) source and (2) inlined 2-dimensional array of metric data of type: complex

Example:

Code Snippet

Copymetrics("common:calls_per_minute"){max, min}

Fetches max and min of the calls per minute grouped per available source.

Source parameter [no], timestamp field [no], single consumption function

Given:

timestamp field is missing
source parameter is missing
single consumption function connected with . is used (for example, .max)

Then the resulting data is of

type: complex
form: reference
fields: (1) source and (2) inlined data of type: number

Example:

Code Snippet

Copymetrics("common:calls_per_minute").max

Fetches time rollup of max of the calls per minute grouped per available source.