The Wavefront Query Language allows you to extract the information you need from your data. You use the query language for queries that display in charts and for alerts. This page is a complete reference to all query language elements and functions. You can click most functions for a page with details and examples.
Query Expressions
A query expression describes data of a particular type: time series, histogram series, events, traces, or spans.
Expression  Definition 

<tsExpression> 
Describes one or more time series. A time series is a sequence of data points that each consists of a data value and a timestamp. Every time series is identified by a unique combination of metric name, source name, and point tag values. A tsExpression may be any of the following:

<hsExpression> 
Describes one or more histogram series. A histogram series is a sequence of histogram distributions Wavefront has computed from the data points of a time series. Each distribution summarizes the points in a time interval (minute, hour, day). An hsExpression may be one of the following:

<eventsExpression> 
Describes a set of events. An eventsExpression may be one of the following:

<tracesExpression> 
Describes a set of traces. A tracesExpression may be one of the following:

<spansExpression> 
Describes a set of spans. A spansExpression may be one of the following:

Common Parameters
Query expressions use a number of common parameters to specify names and values that describe the data of interest. You can use wildcards to match multiple names or values.
 Rules for valid names are here: Wavefront Data Format.
 Enclose a metric, source, or tag name, or a tag value, in double quotes if it is also a Wavefront reserved word, such as a function name or keyword. For example, if you’re using a point tag named
default
, use"default"
.
Parameter  Definition 

<metricName>  The name of a metric that describes one or more time series in a tsExpression. Examples:
cpu.load.metric cpu.*.metric cpu.load.metric or cpu.idle.metric 
<hsMetricName>  The name of a histogram metric that describes one or more histogram series in an hsExpression. A histogram metric name contains the name of the metric from which distributions were calculated, and has an extension (.m, .h, or .d) that indicates the histogram's aggregation interval (minute, hour, or day). Examples:
request.latency.web.m request.latency.*.m request.latency.*.m and not request.latency.web.m 
<sourceName>  The name of a source, such as a host or container, that emits the data of interest (time series, histogram series, or trace data). Specify a source name with the source keyword.
Examples:
source="appServer15" source="app1*" source="app10" or source="app20" 
<sourceTag>  A source tag that has been assigned to a group of data sources. Specify a source tag with the tag keyword.
Examples:
tag="appServers" tag="env.cluster.role.*" tag="appServer" and tag="local" 
<pointTagKey>, <pointTagValue>  The key and value of a point tag that is associated with the data of interest. Point tags are a type of custom metadata for identifying a time series and any histogram series computed from a time series.
Examples:
region="uswest2a" region="uswest*" region="uswest2a" or region="uswest2b" 
<filterName>, <filterValue>  Metadata that you can use to filter a set of data. Filter names and their values might be reserved keywords or custom strings. Available filters depend on the type of data you are querying. Sources, source tags, point tags, event filters, alert tags, and span tags are all examples of filters.
Filter operators include or exclude data based on the filter value:

<timeWindow>  A measure of time expressed as an integer number of units. You can specify:

Wildcards, Aliases, and Variables
You can use wildcards as shortcuts for specifying multiple names or values. You can use query line variables, aliases, and dashboard variables as shortcuts for building queries out of other expressions or predefined strings.
You can combine wildcards, aliases, query line variables, and dashboard variables in the same query line.
Term  Definition 

wildcard 
Matches strings or components in a name or a value.

alias  Defines a convenient name for referring to a tsExpression any number of times in a query. You can define multiple aliases in the same query.
if(ts(requests.latency, source="app1*") as latency, $latency) join(ts(cpu.load) AS ts1 JOIN ts(request.rate) AS ts2 ON ts1.env = ts2.env, ... )Rules for valid alias names:

query line variable  Lets one query line refer to another for the same chart.
The referenced query line must be named and must contain a complete tsExpression.
latency ts(requests.latency, source="app1*" or source="app2*", env="dev")You can reference the named query in another query as follows: newQuery max(${latency})Note: If a query line variable and dashboard variable have the same name, the query line variable overrides the dashboard variable. 
dashboard variable  Defines a convenient name that expands to a particular string of text in any query line of any chart of a dashboard.
ts(requests.latency, ${az})This is equivalent to typing in: ts(requests.latency, tag="az3" or tag="az4")Note: A dashboard variable can expand to any text string, unlike query line variables and aliases, which must be complete tsExpressions. 
TimeSeries Operators
All operations between tsExpression
s are subject to the matching processes described in Series Matching. The result is always interpolated.
 Boolean operators  Combine
tsExpression
s, constants, or filters, such as source names, source tags, point tags, alert names, alert tags. and
,AND
: Returns 1 if both arguments are nonzero. Otherwise, returns 0.or
,OR
: Returns 1 if at least one argument is nonzero. Otherwise, returns 0.
Note: Do not use OR with point tags. Wavefront stops executing the query if the first item fails. Instead, use collect(), for example,collect(ts(metric, my_tag="tag1"), ts(metric, my_tag="tag2"))
not
,NOT
: Use this operator to exclude a source, tag, or metric. See the examples below.[and]
,[AND]
,[or]
,[OR]
: Perform strict ‘inner join’ versions of the Boolean operators. Strict operators match metric/source/point tag combinations on both sides of the operator and filter out unmatched combinations. Arithmetic operators  Perform addition, subtraction, multiplication, or division on corresponding values of time series that are described by the
tsExpression
arguments on either side of the operator. +
,
,*
,/
: Operate on pairs of time series that have matching metric, source, and point tag combinations. If either side of the operator is a ‘singleton’ – that is, a single series with a unique metric/source/point tag combination – it automatically matches up with every time series on the other side of the operator.[+]
,[]
,[*]
,[/]
: Perform strict ‘inner join’ versions of the arithmetic operators. Strict operators match metric/source/point tag combinations on both sides of the operator and filter out unmatched combinations. Comparison operators – Compare corresponding values of time series that are described by the
tsExpression
arguments on either side of the operator. <
,<=
,>
,>=
,!=
,=
: Returns 1 if the condition is true. Otherwise returns 0. Double equals (==) is not a supported Wavefront operator.[<]
,[<=]
,[>]
,[>=]
,[=]
,[!=]
: Perform strict ‘inner join’ versions of the comparison operators. Strict operators match metric/source/point tag combinations on both sides of the operator and filter out unmatched combinations. Examples
(ts(my.metric) > 10) and (ts(my.metric) < 20)
returns 1 ifmy.metric
is between 10 and 20. Otherwise, returns 0.ts(cpu.load.1m, tag=prod AND tag=db)
returnscpu.load.1m
for all sources tagged with bothprod
anddb
.ts(db.query.rate, tag=db and not source="db5.wavefront.com")
returnsdb.query.rate
for all sources tagged withdb
, except for thedb5.wavefront.com
source.ts("smpfax*.count" AND NOT "smpfax*.metrics.wavefront.*", source="eq*"
returns all metrics that match"smpfax*.count"
except for those matching"smpfax*.metrics.wavefront.*"
for any sources that start witheq
.
In addition, Wavefront supports the pow() and mod() functions, which support power of and modulo arithmetic operations.
Aggregation Functions
Aggregation functions are a way to combine (aggregate) multiple time series into a single result series. Wavefront provides two types of aggregation functions. They handle data points that do not line up differently:
 Standard aggregation functions like
sum()
interpolate values wherever necessary in each input series. Then the aggregation function itself is applied to the interpolated series.  Raw aggregation functions like
rawsum()
do not interpolate the underlying series before aggregation.
All aggregation functions provide:
 Filtering: Parameters for filtering the set of input series, for example, to show only points from one source.
 Grouping: Parameters for returning separate results for groups of input series that share common metric names, source names, source tags, point tags, and pointtag values. For example, if you have an
env
point tag with valuesdev
andprod
, you can return one series for all points that come fromdev
and another for all points that come fromprod
.
tag=
) explicitly in the ts() expression. See A Closer Look at grouping with sourceTags. Function  Definition 

sum(<tsExpression> [,metricssourcessourceTagspointTags<pointTagKey> ]) 
Returns the sum of the time series described by tsExpression. The results might be computed from real reported values and interpolated values. 
rawsum(<tsExpression> [,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the raw sum of the time series described by tsExpression. The results are computed from real reported data values only, with no interpolated values. 
avg(<tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the average (mean) of the time series described by tsExpression. The results might be computed from real reported values and interpolated values. 
rawavg(<tsExpression> [,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the raw average (mean) of the time series described by tsExpression. The results are computed from real reported data values only, with no interpolated values. 
min(<tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the lowest value across the time series described by tsExpression. The results might be computed from real reported values and interpolated values. 
rawmin(<tsExpression>
[, metricssources sourceTagspointTags<pointTagKey>]) 
Returns the lowest value across the time series described by tsExpression. The results are computed from real reported data values only, with no interpolated values. 
max(<tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the highest value across the time series described by tsExpression. The results might be computed from real reported values and interpolated values. 
rawmax(<tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the highest value across the time series described by tsExpression. The results are computed from real reported data values only, with no interpolated values. 
count(<tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the number of reporting time series described by tsExpression, where a time series is counted as reporting even if it has interpolated values. 
rawcount(<tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the number of reporting time series described by tsExpression, where a time series is counted as reporting at a given moment only if it has a real data value, instead of an interpolated value. 
variance(<tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the variance based on the time series described by tsExpression. The results might be computed from real reported values and interpolated values. 
rawvariance(<tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the variance across the time series described by tsExpression. The results are computed from real reported data values only, with no interpolated values. 
percentile(<percentage>, <tsExpression>
[,metricssourcessourceTagspointTags<pointTagKey>]) 
Returns the estimated percentile for percentage, across the time series described by tsExpression. The results might be computed from real reported values and interpolated values. 
rawpercentile(<percentage>, <tsExpression>
[,metricssources sourceTagspointTags<pointTagKey>]) 
Returns the estimated percentile for percentage, across the time series described by tsExpression. The results are computed from real reported data values only, with no interpolated values. 
Filtering and Comparison Functions
Filtering functions help you select a subset of the time series that are returned by a tsExpression
.
Function  Definition 

clampMax(max, <tsExpression>)  Changes any point larger than max to max. 
clampMin(min, <tsExpression>)  Changes any point smaller than min to min. 
highpass(<tsExpression1>, <tsExpression2>[, inner])  Returns only the points in tsExpression2 that are above tsExpression1. tsExpression1 can be a constant. 
lowpass(<tsExpression1>, <tsExpression2>[, inner])  Returns only the points in tsExpression2 that are below tsExpression1. tsExpression1 can be a constant. 
min(<tsExpression1>, <tsExpression2>)  Returns the lower value in each pair of corresponding values in tsExpression1 and tsExpression2. 
max(<tsExpression1>, <tsExpression2>)  Returns the higher value in each pair of corresponding values in tsExpression1 and tsExpression2. 
between(<tsExpression>, <lower>, <upper>)  Returns 1 if tsExpression is >= lower and <= upper. Otherwise, returns 0. This function outputs continuous time series. 
downsample(<timeWindow>, <tsExpression>)  Returns the values in tsExpression that occur in each time window. For example: downsample(30m, ts(my.metric)) returns the values of my.metric every half hour. 
align(<timeWindow>,[meanmedianminmaxfirstlastsumcount,] <tsExpression>)  Groups the data values of a time series into buckets of size timeWindow and returns one displayed value per bucket. Each returned value is the result of combining the data values in a bucket using the specified summarization method. 
topk(<numberOfTimeSeries>,
[meanmedianminmaxsumcountlast, [<timeWindow>,]] <tsExpression>) 
Returns the top numberOfTimeSeries time series described by tsExpression. Ranking for a series is based on its last displayed data value or on data values summarized over a time window. 
bottomk(<numberOfTimeSeries>,
[meanmedianminmaxsumcount, [<timeWindow>,]] <tsExpression>) 
Returns the bottom numberOfTimeSeries time series described by tsExpression. Ranking for a series is based on its last displayed data value or on data values summarized over a time window. 
top(<numberOfTimeSeries>,
[meanmedianminmaxsumcountlast, [<timeWindow>,]] <tsExpression>) 
Returns 1 for the top numberOfTimeSeries time series described by tsExpression, and 0 for the remaining series. Ranking for a series is based on its last displayed data value or on data values summarized over a time window. 
bottom(<numberOfTimeSeries>,
[meanmedianminmaxsumcount, [<timeWindow>,]] <tsExpression>) 
Returns 1 for the bottom numberOfTimeSeries time series described by tsExpression, and 0 for the remaining series. Ranking for a series is based on its last displayed data value or on data values summarized over a time window. 
filter(<tsExpression>, <filter1> [andor [not] <filter2>] … ) 
Retains only the time series in tsExpression that match one or more specified filters, which can include any combination of metric names, sources (source=), or point tags. Use Boolean operators to combine multiple filters.
Does not support filtering by source tag. 
retainSeries(<tsExpression>, <filter1> [andor [not] <filter2>] … ) 
Retains only the time series in tsExpression that match one or more specified filters, which can include any combination of metric names, sources (source=), source tags (tag=), or point tags. Use Boolean operators to combine multiple filters. 
removeSeries(<tsExpression>, <filter1> [andor [not] <filter2>] … ) 
Suppresses any time series in tsExpression that matches one or more specified filters, which can include any combination of metric names, sources (source=), source tags (tag=), or point tags. Use Boolean operators to combine multiple filters. 
globalFilter(<tsExpression  hsExpression>, <filter1> [andor [not] <filter2>] … ) 
Retains only the time series or histograms in tsExpression that match one or more specified filters, which can include any combination of metric names, sources (source=), source tags (tag=), or point tags. Use Boolean operators to combine multiple filters. 
sample(<numberOfTimeSeries>, <tsExpression>)  Returns a nonrandom sample set of numberOfTimeSeries time series based on tsExpression. Repeated calls display the same sample set as long as the underlying set of time series stays the same. 
random(<numberOfTimeSeries>, <tsExpression>)  Returns a random set of numberOfTimeSeries time series based on tsExpression. Repeated calls always display different sample sets. 
limit(<numberOfTimeSeries>[, <offsetNumber>], <tsExpression>)  Limits the number of time series returned by the query. numberOfTimeSeries specifies the maximum number of time series returned. Optionally, use offsetNumber to specify the starting index. 
hideBefore(<timeWindow>, <tsExpression>)  Hides data before a specified time. For example, hideBefore(10m) hides data that’s older than 10 minutes. 
hideAfter(<timeWindow>, <tsExpression>)  Hides data after a specified time. For example, hideAfter(10m) hides data that’s newer than 10 minutes ago. 
Standard Time Functions
Standard time functions can help you:
 Analyze how time series change over time:
rate()
,derive()
,ratediff()
)  Compare current values to earlier or later values of the same time series:
lag()
,lead()
,at()
 Examine time series during particular time windows:
year()
,month()
,dayOfYear()
, and so on
Function  Definition 

rate([<timeWindow> ] <,tsExpression>)  Returns the persecond change of the time series described by tsExpression. Recommended for counter metrics that report only increasing data values over regular time intervals. Handles counter resets. 
deriv(<tsExpression>)  Returns the persecond change of the time series described by tsExpression. Appropriate for metrics that report increasing or decreasing data values. 
ratediff(<tsExpression>)  Returns the differences between adjacent values in each time series described by tsExpression. Recommended for counter metrics that report only increasing data values over irregular time intervals. Handles counter resets. 
lag(<timeWindow>, <tsExpression>)  Returns earlier data values from the time series described by tsExpression, timeshifting the values by timeWindow to enable you to compare a time series with its own past behavior. 
lead(<timeWindow>, <tsExpression>)  Returns later data values from the time series described by tsExpression, timeshifting the values by timeWindow to enable you to compare a time series with its own subsequent or forecasted behavior. 
at(<atTime>, [<lookbackWindow>,] <tsExpression>)  Returns a data value reported at a particular time by the time series described by tsExpression. The returned value is displayed continuously across the chart, so you can use it as a reference value for comparing against other queries. 
atEpoch(<epochTime> <, tsExpression>)  Returns the value at the specified time for the time series described by the expression. The returned value is displayed continuously across the chart, so you can use it as a reference value. 
year(<timezone> [,<tsExpression>])  Returns the year in the specified time zone. Years are returned as 4digit numbers in the Gregorian calendar. 
month(<timezone> [,<tsExpression>])  Returns the month of the year in the specified time zone. Months are returned as whole numbers from 1 (January) through 12 (December). 
daysInMonth(<timezone> [,<tsExpression>])  Returns the number of days in a month for the timestamp of the specified time zone. The values returned are integer only and are in the range 2831. 
dayOfYear(<timezone> [,<tsExpression> ])  Returns the day of the year in the specified time zone. Days of the year are returned as whole numbers from 1 to 366. 
day(<timezone> [,<tsExpression>])  Returns the day of the month in the specified time zone. Days of the month are returned as whole numbers from 1 to 31. 
weekday(<timezone> [,<tsExpression>])  Returns the day of the week in the specified time zone. Days of the week are returned as whole numbers from 1 (Monday) to 7 (Sunday). 
hour(<timezone> [,<tsExpression>])  Returns the hour in the day in the specified timeZome. The values returned are integer only and are in the range 023. 
minute(<timezone> [,<tsExpression>])  Returns the minute of the hour for the timestamp specified by timeZome. The values returned are integer only and are in the range 059. 
isToday(<timezone> [,<tsExpression>])  Tests for the current day in the specified time zone. Return values are 1 for times during the current day, or 0 for times before or after today. 
timestamp(<tsExpression>)  Returns the timestamps associated with the reported data values in the time series described by tsExpression. 
time()  Returns the epoch seconds representing each point in time. 
Moving Window Time Functions
Moving window time functions combine or test the values of a time series over a sliding window. For further information, see Using Moving and Tumbling Windows to Highlight Trends.
These functions output continuous time series, with the exception of integral()
.
Function  Definition 

mvalues(<timeWindow>, <tsExpression> [,metricssourcessourceTagspointTags<pointTagKey>])  Returns the number of unique values over the specified time window. 
mslope(<timeWindow>, <tsExpression>)  Returns the persecond derivative of the linear regression of the time series over the specified time window. 
mavg(<timeWindow>, <tsExpression>)  Returns the moving average of each series for the specified time window. 
msum(<timeWindow>, <tsExpression>)  Returns the moving sum of each series for the specified time window. Don't confuse this function with mcount(), which returns the number of data points. 
mmedian(<timeWindow>, <tsExpression>)  Returns the moving median of each series for the specified time window. 
mvar(<timeWindow>, <tsExpression>)  Returns the moving variance of each series for the specified time window. 
mcount(<timeWindow>, <tsExpression>)  Returns the number of data points reported by each time series over the specified time window. 
mmin(<timeWindow>, <tsExpression>)  Returns the minimum of each series for the specified time window. 
mmax(<timeWindow>, <tsExpression>)  Returns the maximum of each series for the specified time window. 
mpercentile(<timeWindow>, <percentage>, <tsExpression>)  Returns the percentage percentile of each series for the specified time window. 
mseriescount(<timeWindow>, <tsExpression> [,metricssourcessourceTagspointTags<pointTagKey>])  Returns the aggregated number of series reporting during the specified time window. 
mdiff(<timeWindow>, <tsExpression>)  Returns the difference between the current value of the expression and the expression's value at the point in time that is timeWindow ago. This function doesn't interpolate the points before doing the subtraction. 
mcorr(<timeWindow>, <tsExpression1>, <tsExpression2> [, inner])  Returns the moving correlation between two expressions for a specified time window. 
integrate(<timeWindow>, <tsExpression>)  Returns the moving integration for the specified expression for the specified time window. 
integral(<tsExpression>)  Returns the moving sum over time for the given expression over the time window of the current chart window. 
mchanges(<timeWindow>, <tsExpression>)  Returns the number of times a counter has reset within the specified time window. 
flapping(<timeWindow>, <tsExpression>)  Returns the number of times a counter changed directions (going up or going down) within the specified time window. 
any(<timeWindow>, <tsExpression>)  Returns 1 if the expression has been nonzero at any time during the specified time window. Otherwise, returns 0. 
all(<timeWindow>, <tsExpression>)  Returns 1 if the expression has been nonzero at every point in time during the time window. Otherwise, returns 0. 
Missing Data Functions
Missing data functions allow you to interpolate data points in time series that have gaps. To check for missing functions see the missing()
function and the exists()
function.
Function  Definition 

default([<timeWindow>,] [<delayTime>,]
<defaultValue>, <tsExpression>[.orElse(<defaultIfNoData>)]) 
Fills in gaps in each time series described by tsExpression, by inserting data points with the value defaultValue. Specify timeWindow to insert data for just a limited period of time after each existing point. Specify delayTime to allow a gap before the inserted data. Use the .orElse operator to specify a default value even if the time series did not report any values in the time window. 
last([<timeWindow>,] <tsExpression>)  Fills in gaps in each time series described by tsExpression, by inserting data points that have the last known value of the series. Specify timeWindow to insert data for just a limited period of time after each existing point. 
next([<timeWindow>,] <tsExpression>)  Fills in gaps in each time series described by tsExpression, by inserting data points that have the next known value of the series. Specify timeWindow to insert data for the specified amount of time before the first data point after each gap. 
interpolate(<tsExpression>)  Fills in gaps in the time series described by tsExpression, by inserting a continuous linear interpolation of data points. 
Conditional Function
The if()
conditional function returns data values from time series based on a specified condition.
Function  Definition 

if(<conditiontsExpression>,
<thentsExpression> [, <elsetsExpression>]) 
Returns points from thentsExpression only while conditiontsExpression > 0. Otherwise, returns points from elsetsExpression, if it is specified.
conditiontsExpression must evaluate to a series of numeric values, and typically includes numeric comparisons or transformations of time series. 
Rounding and Mathematical Functions
Rounding and mathematical functions let you transform the data values in time series. Rounding functions return time series with integer data values.
Function  Definition 

round([<toMultiple>,] <tsExpression>)  Returns the nearest integer for each data value in the specified time series. The optional toMultiple parameter supports rounding to the multiple of a specified number. 
ceil(<tsExpression>)  Returns the ceiling for the specified time series, by rounding any data values with decimals up to the next largest integer. 
floor(<tsExpression>)  Returns the floor for the specified time series, by rounding any data values with decimals down to the next smallest integer. 
abs(<tsExpression>)  Returns the absolute value of the time series described by the expression. 
normalize(<tsExpression>)  Normalizes each time series described by the expression, so that its values are scaled between 0 and 1.0. 
Exponential and Trigonometric Functions
Exponential and trigonometric functions enable you to perform mathematical transformations on each data value in the specified time series.
Function  Definition 

sqrt(<tsExpression>)  Returns the square root of each data value described by the expression. 
pow(<basetsExpression>, <exponenttsExpression>[, inner])  Raises the base expression to the power of the exponent expression. 
exp(<tsExpression>)  Returns the natural exponential for each data value described by the expression. 
log(<tsExpression>)  Returns the natural log of each data value described by the expression. 
log10(<tsExpression>)  Returns the log base 10 of each data value described by the expression. 
Trigonometric Functions
sin(<tsExpression>), cos(<tsExpression>), tan(<tsExpression>), asin(<tsExpression>), acos(<tsExpression>), atan(<tsExpression>), atan2(<yexpression>, <xexpression>), sinh(<tsExpression>), cosh(<tsExpression>), tanh(<tsExpression>) 
Performs the specified trigonometric function on each data value described by the expression. 
Trigonometric Utility Functions.
toDegrees(<numRadians>), toRadians(<numDegrees>) 
Converts radians to degrees, and vice versa. 
Join Function
See Combining Time Series With join() for syntax and examples.
The join()
function enables you to:
 Compare two or more time series, and find matches, or, conversely, find the time series that do not match.
 Combine the data points from any matching time series to form a new synthetic time series with point tags from one or both of the input series.
The Wavefront join()
function is modeled after the SQL JOIN operation, and supports inner joins, left outer joins, right outer joins, and full outer joins.
join()
for an inner join is an explicit way to perform series matching between two groups of time series. As an alternative for certain simple use cases, you can use an operator that performs implicit series matching. Metadata Functions
Metadata functions let you temporarily rename a metric, rename a source, or create a synthetic point tag on a time series. You can formulate an alias or point tag value in one of 3 ways:
 Specify a string. The string can include one or more variables that are replaced with existing metadata values.
 Specify a numeric zeroBasedNodeIndex to identify a node (string component) in an existing metadata value. The node is “extracted” and used as the new alias or value. By default, we consider nodes to be separated by periods, for example,
cpu.loadavg.1m
, but you can add an explicit delimiterDefinition, such as""
to extract nodes fromcpuloadavg1m
.  Specify a regular expression regexSearchPattern to match substrings in an existing metadata value. You can use one or more matched substrings in a replacementPattern that describes the new alias or value.
Function  Definition 

aliasMetric(<tsExpression>, [metricsource{tagk,<pointTagKey>},]
zeroBasedNodeIndex[, "delimiterDefinition"]  "regexSearchPattern", "replacementPattern"  "replacementString") 
Replaces the metric name for each time series described by tsExpression. The alias can be a specified replacementString or a string that is constructed from part or all of an existing metadata value. 
aliasSource(<tsExpression>,
[metricsource{tagk,<pointTagKey>},]
zeroBasedNodeIndex[, "delimiterDefinition"]  "regexSearchPattern", "replacementPattern"  "replacementString") 
Replaces the source name of each time series described by the tsExpression. The alias can be a specified replacementString or a string that is constructed from part or all of an existing metadata value. 
taggify(<tsExpression>, metricsource{tagk,<pointTagKey>}, <newPointTagKey>, zeroBasedNodeIndex[, "delimiterDefinition"]  "regexSearchPattern", "replacementPattern"  "replacementString")  Creates a synthetic point tag with the specified key for each time series described by tsExpression. The value of the new tag can be a specified replacementString or a string that is constructed from part or all of an existing metadata value. 
String Manipulation Functions
String manipulation functions let you manipulate the metadata of the specified time series. In each function, the first parameter identifies the type of metadata string to manipulate: the metric name, a source name, or the value of a point tag key.
String manipulation functions can help you:
 Obtain information about the string:
length()
,indexOf()
,lastIndex()
 Extract a subset from the string:
charAt()
,substring()
 Test the string:
isEmpty()
,isBlank()
,equals()
,equalsIgnore()
,startsWith()
,endsWith()
,matches()
,contains()
 Temporarily transform the string for duration of query:
toLowerCase()
,toUpperCase()
,trim()
,strip()
,stripLeading()
,stripTrailing()
,concat()
,repeat()
Function  Definition 

length(metricsource<pointTagKey>, <tsExpression>)  Returns the length of in the specified metadata string. 
isEmpty(metricsource<pointTagKey>, <tsExpression>)  Returns true if the specified metadata string is an empty string. Otherwise, returns false. 
isBlank(metricsource<pointTagKey>, <tsExpression>)  Returns true if the specified metadata string is a blank character (" "). Otherwise, returns false. 
toLowerCase(metricsource<pointTagKey>, <tsExpression>)  Converts all uppercase characters to lowercase in the specified metadata string. 
toUpperCase(metricsource<pointTagKey>, <tsExpression>)  Converts all lowercase characters to uppercase in the specified metadata string. 
trim(metricsource<pointTagKey>, <tsExpression>)  Removes a single leading white space and/or a single trailing white space from the specified metadata string but does not remove multiple leading or trailing white spaces. 
strip(metricsource<pointTagKey>, <tsExpression>)  Removes both leading and trailing white spaces from the specified metadata string. 
stripLeading(metricsource<pointTagKey>, <tsExpression>)  Removes leading white spaces from the specified metadata string. 
stripTrailing(metricsource<pointTagKey>, <tsExpression>)  Removes trailing white spaces from the specified metadata string. 
equals(metricsource<pointTagKey>, "<string>", <tsExpression>)  Returns true if the specified metadata string is equal to the comparison string. Otherwise, returns false otherwise. Both strings must match exactly. 
equalsIgnoreCase(metricsource<pointTagKey>, "<string>", <tsExpression>)  Ignores case and returns true if the specified metadata string matches the comparison string> Otherwise, returns false. With this function "string" is equal to "StRiNg" . 
matches(metricsource<pointTagKey>, "<stringOrRegex>", <tsExpression>)  Returns true if the specified metadata string matches the comparison string. Otherwise, returns false. The comparison string can be a regular expression. With this function, "us.*" matches "uswest1" .

startsWith(metricsource<pointTagKey>, "<string>", <tsExpression>)  Returns true if the specified metadata string starts with the given string. Otherwise, returns false. 
endsWith(metricsource<pointTagKey>, "<string>", <tsExpression>)  Returns true if the specified metadata string ends with the given string. Otherwise, returns false. 
indexOf(metricsource<pointTagKey>, "<subString>", <tsExpression>)  Finds the first occurrence of the specified substring in the metadata string and returns the starting position of that occurrence. 
lastIndexOf(metricsource<pointTagKey>, "<subString>", <tsExpression>)  Finds the last occurrence of the specified substring in the specified metadata string and returns the starting position of that occurrence. 
concat(metricsource<pointTagKey>, "<string>", <tsExpression>)  Concatenates the specified string by adding it to the end of the specified metadata string. 
contains(metricsource<pointTagKey>, "<subString>", <tsExpression>)  Compares a string extracted from an expression to a specified string and returns true if the extracted string contains the specified string. Otherwise, returns false. 
charAt(metricsource<pointTagKey>, <integer>, <tsExpression>)  Returns the character at the specified position in the specified metadata string. 
substring(metricsource<pointTagKey>, [<integer>][<integer1>, <integer2>], <tsExpression>)  Returns a substring that is extracted the specified metadata string. 
repeat(metricsource<pointTagKey>, <integer>, <tsExpression>)  Repeats the specified metadata string a specified number of times. 
Predictive Functions
Predictive functions enable you to forecast data values and find outlier data values in the specified time series.
Function  Definition 

anomalous(<testWindow>, [<confidenceFactor>,] [<historyWindow>, [<alignWindow>,]] <tsExpression>)  Returns the percentage of anomalous points in each time series described by the expression. Anomalous points have values that fall outside an expected range, as determined by confidenceFactor. 
hw(<historyLength> < [,seasonLength>], <samplingRate>, <tsExpression> [<smoothingFactor>, <trendFactor>, <seasonalityFactor>])  Returns a smoothed version of each time series described by the expression, and forecasts its future points using the HoltWinters double exponential smoothing algorithm. Optionally, supports the HoltWinters triple exponential smoothing algorithm for seasonal data. 
nnforecast(<forecastPeriod>, [<confidenceFactor>,] <tsExpression>, [with_bounds])  Forecasts future data values for each time series described by the expression. It uses hypothesis testing and neural networks for prediction. 
linearforecast(<forecastOffset>, <historyLength>, <tsExpression>)  Predicts the value of the points in the time series using simple linear regression. Similar to the Prometheus predict_linear() function. 
Miscellaneous TimeSeries Functions
Function  Definition 

collect(<tsExpression1>, <tsExpression2> [, <tsExpression3>, ...]) 
Returns a single tsExpression that is the combination of two or more tsExpressions. 
missing(<timeWindow>, <tsExpression>)  Checks whether there are any data points in the specified time window.

exists(<tsExpression>)  Returns 1 if any time series described by the expression exists. Othrwise, returns 0. A time series exists if it has reported a data value in the last 4 weeks. 
haversine(<lat1>, <long1>, <lat2>,<long2>)  Returns the distance between a pair of coordinates. 
random()  Returns random values between 0.0 and 1.0. Repeated calls display different random values. 
bestEffort(<tsExpression>)  Wrapping any query expression in bestEffort() tells Wavefront to use conservative targets for scheduling workloads. That means we limit thread use and asynchronous operations. 
Histogram Functions
You use histogram query functions to access the histogram distributions that Wavefront has computed from a metric. See Wavefront Histograms for background.
Histogram to Histogram Functions
Each function in the following table returns one or more series of histogram distributions and can therefore be used as the hsExpression parameter in another query.
Histogram to Histogram Function 
Definition 

hs(<hsMetricName> [andor [not] <hsMetricName2>] ...
[,andor [not] source="<sourceName>"] ... [andor [not] tag="<sourceTag>"] ... [andor [not] <pointTagKey>="<pointTagValue>"] ...) 
Returns the series of histogram distributions for hsMetricName, optionally filtered by sources and point tags.
A name extension (m, h, or d) indicates the
histogram aggregation interval,
for example: hs(users.settings.numberOfApiTokens.m, source="host1") In a timeseries chart, this function displays the median values of the distributions in the matched histogram series. 
merge(<hsExpression> [, metricssourcessourceTagspointTags<pointTagKey>]) 
Merges the centroids and counts across the series of histogram distributions described by hsExpression and returns one or more series of composite histogram distributions. In a timeseries chart, this function displays the median values of the merged distributions. 
align(<timeWindow>, <hsExpression>)  Adjusts the granularity of the series of histogram distributions described by hsExpression, by merging distributions into time buckets of size timeWindow and returning one distribution per bucket. In a timeseries chart, this function displays the median values of the aligned distributions. 
Histogram Input Conversion Functions
Each histogram input conversion function in the following table takes histogram distributions as input and returns the results as time series. You can therefore use a histogram conversion function as a tsExpression parameter in a time series query function.
Histogram to Time Series Function 
Definition 

cdf(<rawValue>, <hsExpression>)  Cumulative distribution function for histograms. Lets you find out how likely it is that a histogram is less than or equal to a specified value (raw_value). 
median(<hsExpression>)  Returns time series that consist of the median values of the histogram distributions described by hsExpression. 
avg(<hsExpression>)  Returns time series that consist of the average values from the histogram distributions described by hsExpression. 
min(<hsExpression>)  Returns time series that consist of the lowest values from the histogram distributions described by hsExpression. 
max(<hsExpression>)  Returns time series that consist of the highest values from the histogram distributions described by hsExpression. 
percentile(<percentage>, <hsExpression>)  Returns time series that consist of the <percentage> percentiles from the histogram distributions described by hsExpression. A percentile is a value below which the specified percentage of values fall. For example, percentile(75, hs(my.hsMetric.m)) returns the 75th percentile value from each distribution. 
count(<hsExpression>)  Returns time series that consist of the number of values in each histogram distribution described by hsExpression. 
summary([<percentageList>,] <hsExpression>)  Returns time series that summarize the significant values from the histogram distributions described by hsExpression. The summary includes a separate time series for each percentage percentile. By default, the summary includes series for: max, 99.9, 99, 95, 90, 75, avg, median (50), 25, and min. 
alignedSummary([<percentageList>,] <hsExpression>)  Aligns a series of histogram distributions into a single time bucket for the current chart (1vw), and then returns the significant values from the resulting composite distribution. The aligned summary includes a separate constant time series for each percentage percentile. By default, the summary includes series for: max, 99.9, 99, 95, 90, 75, avg, median (50), 25, and min. 
stddev(<hsExpression>)  Returns time series that show you how the data in your hsExpression is distributed around the mean. 
Histogram Output Conversion Functions
Each histogram output conversion function in the following table takes a time series as input and returns the results as Wavefront histogram. You can therefore use the result as input to any of the histogram functions listed in this section.
Histogram to Time Series Function 
Definition 

histo(<timeWindow>, <tsExpression>, [,metricssourcessourceTagspointTags<pointTagKey>])  Returns a histogram distribution for the time series described by the expression. Charts that display results show the median unless you use the percentile() function to change that. 
cumulativeHisto([timeWindow], [<bucketName>, ] <tsExpression> [,metricssourcessourceTagspointTags<pointTagKey> ])  Returns a cumulative histogram that comes, for example, from Prometheus or Telegraf, in Wavefront. You can then visualize the histogram in Wavefront charts using functions such as percentile. 
frequencyHisto([timeWindow], [<bucketName>, ] <tsExpression> [,metricssourcessourceTagspointTags<pointTagKey> ])  Converts a histogram coming from Google Cloud Platform(GCP) to Wavefront histogram format. When GCP Detailed Histogram Metrics is enabled, Wavefront will additionally ingest bucket counts for GCP distributions, with metric namegcp.<metric>.bucket. Enabling this increases ingestion rate and cost. 
Event Functions
Event functions let you filter and display events.
Event to Event Functions
Each function in the following table returns a set of one or more events and can therefore be used as the eventsExpression parameter in another query. Some functions filter an event set, so that only events you’re interested in are displayed. Other functions return synthetic events, which are displayed by the query, but not stored in Wavefront.
Event to Event Function 
Definition 

events(<filterName>="<filterValue>" [,andor [not] <filter2Name>="<filter2Value>"] ...) 
Returns the set of events that match the specified event filters, for example: events(type="alert", name="low space", alertTag="App1.*") This function adds a set of events to a timeseries chart. 
Event set operators  Operators (such as union, intersect, , d, m, o) that combine or compare two input eventsExpressions. 
closed(<eventsExpression>)  Returns events that have ended and instantaneous events that occurred in the past. 
until(<eventsExpression>)  Returns synthetic events that start at the beginning of epoch time (Jan 1, 1970) and end where the input events start. 
after(<eventsExpression>)  Returns synthetic ongoing events that start when the input events end. 
since(<eventsExpression>)  Returns synthetic ongoing events that start when the input events start but have no end time. 
since(<timeWindow>)  Creates a single synthetic event that started timeWindow ago and ended "now". 
timespan(<startTimestamp>, <endTimestamp>
[, prettyName=<"displayName">] [, <eventTagName>=<"eventTagValue">] ...) 
Creates a single synthetic event with the specified start and end timestamps, and, optionally, with the specified display name and tags. 
first(<eventsExpression>)  Returns the first event that started from the specified set of events. 
last(<eventsExpression>)  Returns the most recent event that started from the specified set of events. 
firstEnding(<eventsExpression>)  Returns the first event that ended from the specified set of events. 
lastEnding(<eventsExpression>)  Returns the most recent event that ended from the specified set of events. 
Events Conversion Functions
Each events conversion function in the following table takes a set of events as input and returns the results as a time series. You can therefore use an events conversion function as a tsExpression parameter in a time series query function.
Event to Time Series Function 
Definition 

count(<eventsExpression>)  Converts eventsExpression into a single time series, where every data point is computed from the number of event boundaries that occurred at that time. 
ongoing(<eventsExpression>)  Converts eventsExpression into a continuous time series that represents the number of ongoing events at each moment of the chart's time window. 
Traces Functions
You use traces functions to find and filter any traces that your applications might be sending. Traces functions are available only in the Query Editor of the Traces browser.
Each function in the following table returns a set of one or more traces and can therefore be used as the tracesExpression parameter in another function.
Function  Definition 

traces({"<fullOperationName>"
[,andor [not] <filterName>="<filterValue>"] ...}  <spansExpression>) 
Returns the traces that contain one or more qualifying spans, where a qualifying span matches the specified fullOperationName and span filters. 
limit(<numberOfTraces>, <tracesExpression>)  Limits the traces returned by tracesExpression to include the specified numberOfTraces. 
highpass(<traceDuration>, <tracesExpression>)  Filters the traces returned by tracesExpression to include only traces that are longer than traceDuration. 
lowpass(<traceDuration>, <tracesExpression>)  Filters the traces returned by tracesExpression to include only traces that are shorter than traceDuration. 
Spans Functions
You use spans functions to find and filter individual spans that your applications might be sending. Spans functions are available only in the Query Editor of the Traces browser.
traces()
function. Function  Definition 

spans("<fullOperationName>"
[,andor [not] <filterName>="<filterValue>"] ...) 
Returns the spans that match the specified fullOperationName and span filters. 
highpass(<spanDuration>, <spansExpression>)  Filters the spans returned by spansExpression to include only spans that are longer than spanDuration. 
lowpass(<spanDuration>, <spansExpression>)  Filters the spans returned by spansExpression to include only spans that are shorter than spanDuration. 
Apdex Functions
You can use the basic or advanced apdex()
function to get the apdex score of a specific service.
Function  Definition 

apdex([T,  T, 4T, ]application=<applicationName>, service=<serviceName>, [ <histogramSeries>]  Returns the apdex score of a specific service over time. Optionally supports histogram series. 
apdexLatency(application=<applicationName>, service=<serviceName> [satisfied  tolerating])  Returns the apdex threshold defined for the service or application. 