Learn about the query syntax, operators, and functions supported by Wavefront Query Language.

Query Elements

Term Definition
metric The name of a metric. For example: cpu.load.metric
source The name of the entity that emitted the metric. Specify source names with the keyword source. For example:
source=appServer15
source tag A type of source metadata. Specify source tags with the keyword tag. For example:
tag=app.*
point tag A type of custom metric metadata. Point tags have keys and values. For example:
region=us-west-2b
timeWindow A measure of time, expressed as an integer number of units. You can specify:
  • Seconds, minutes, hours, days or weeks (1s, 1m, 1h, 1d, 1w). For example, 3h specifies 3 hours.
  • Time relative to the window length of the chart you are currently looking at (1vw). If you are looking at a 30 minute window, 1vw is one view-window length, and therefore equivalent to 30m.
  • Time relative to the bucket size of the chart (1bw). Wavefront calculates bucket size based on the view window length and screen resolution. You can see bucket size at the bottom left of each chart.
The default unit is minutes if the unit is not specified.
expression An expression consisting of a ts() expression, constant, or combination of ts() expressions and constants. See Expressions.

See Organizing with Tags for information on the different types of tags and how to use them.

Note: Do not use names of functions such as default or sum or other query language elements to name a metric, source, source tag, point tag, or point tag value. If you must, surround the element with double quotes. For example, if you’re using a point tag named default, use "default".

Expressions

An expression may be a ts() expression, a constant, or an arithmetic or Boolean combination of a ts() expressions and constants.

Term Definition
ts() expression Returns all points that match a metric name, filtered by source names, alert names, source tags, alert tags, and point tags.
  • Syntax:
    ts(<metricName>,
      [source=<sourceName>] [and|or]
      [tag=<sourceTagName>] [and|or]
      [<pointTagKey1>=<pointTagValue1>[and|or] ... <pointTagKeyN>=<pointTagValueN>])
    
  • For metric, source, source tag, and point tag naming conventions, see Wavefront Data Format.
  • Sources, source tags, alert names, alert tags, and point tags are optional. For example, to return points from all sources sending the my.metric metric, specify ts(my.metric).
constant A number such as 5.01, 10000, or 40. Constants can be plotted by themselves and composed in expressions using arithmetic operators.
  • You can use SI prefixes(k, M, G, T, P, E, Z, Y) to scale constants by multiples of 1000. G (billion) and T (trillion) are useful when working with network and I/O metrics.
  • Example. Typing 1M is equivalent to typing 1000000
  • Example. Typing 7.2k is equivalent to typing 7200
wildcard Matches strings in metric names, source names, alert names, source tags, alert tags, and point tags.
  • A wildcard is represented with a "*" character. Wavefront supports no other wildcard characters.
  • Example. When filtering sources, match all sources starting with "app-1" (namely, app-10, app-11, app-12, and so on):
    source=app-1*
  • Example. When filtering point tags, match the time series that have <pointTagKey> with any value, and filter out any time series without <pointTagKey>:
    <pointTagKey>="*"
  • Example. When filtering point tags, find any time series that do not have the specified point tag.
    not <pointTagKey>="*"

Operators

All operations between expressions are subject to the matching processes described in Series Matching​.

  • Boolean operators - combine ts() expressions and constants and the filtering performed by source names, alert names, source tags, alert tags, and point tags.
    • and: Returns 1 if both arguments are nonzero. Otherwise, returns 0.
    • or: Returns 1 if at least one argument is nonzero. Otherwise, returns 0.
    • not: Use this operator to exclude a source, tag, or metric. See the examples below.
    • [and], [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
    • +, -, *, /: Match metric, source, and point tag combinations on both sides of an expression. If either side of the expression is a ‘singleton’ – that is, a single metric, source, or point tag combination–it automatically matches up with every element on the other side of the expression.
    • [+], [-], [*], [/]: 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
    • <, <=, >, >=, !=, =: 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 if my.metric is between 10 and 20. Otherwise, returns 0.
    • ts(cpu.load.1m, tag=prod and tag=db) returns cpu.load.1m for all sources tagged with both prod and db.
    • ts(db.query.rate, tag=db and not source=db5.wavefront.com) returns db.query.rate for all sources tagged with db, except for the db5.wavefront.com source.
    • ts("smp-fax*.count" and not "smp-fax*.metrics.wavefront.", source="-eq*" returns all metrics that match "smp-fax*.count" except for those matching "smp-fax*.metrics.wavefront.*".

Tags in Queries

Tags can help you organize your data. Here’s an overview. See Organizing with Tags for details.

  • Source tags allow you to group sources. For example, if you have two sources, appServer15 and appServer16 you can add the source tag app to both sources to specify that both are app servers. Source tags allow you to group sources together. For example, you can query ts(cpu.load.metric, tag=app) instead of ts(cpu.load.metric, source=appServer15 or source=appServer16) Both queries yield the same result as long as the app tag is added to each server.
  • Alert tags allow you to group alerts.
  • Point tags are an additional way to describe metrics. For example, assume your data include the point tag region with value us-west-2a and us-west-2b.

Variables in Queries

We support variables in several ways:

  • A query line variable allows you to refer to a query line as a variable in another query field within the same chart. The query line variable name is the same as the query line name and is referenced in another query field with the syntax ${queryLineName}. For example, if you have a query line named queryLine1 with ts(requests.latency) as the expression, you can enter ${queryLine1} in a another query field to reference ts(requests.latency). The query line being referenced must be a complete expression. If a query line variable and dashboard variable have the same name, the query line variable overrides the dashboard variable.
  • An alias defines any ts() expression as an alias within that single query line using a SQL-style “as” expression. The syntax of an alias is: expression as <aliasName>. If you specify expression as myAlias, you reference the alias as $myAlias. You can use $myAlias multiple times in that query line, and define multiple aliases within a query line.
    • Use names that are three letters or longer.
    • You can’t use the SI prefixes (such as k, G, or T) as alias names.
    • Numeric characters are allowed only at the end of the alias name ($test123 is ok, but $1test or $test4test is not).
  • A dashboard variable can be used within any query line in every chart contained in a specific dashboard. A dashboard variable can replace any string of text–in contrast, a query line variable and alias must be a complete expression. If you define dashvar in a dashboard, you refer to ${dashvar} within any query line. You can use aliases, query line variables, and dashboard variables in the same query line. You can even use the same variable name for a dashboard and an alias (though we don’t recommend it). See Dashboard Variables.

Aggregation and Raw Aggregation Functions

Aggregation and raw aggregation functions provide a way to combine (aggregate) multiple series into a single series. If there are gaps of data, non-raw aggregation functions first interpolate the points of the underlying set of series (up to one day) if at least 1 known value is available. Then the aggregation function iself is applied to the interpolated series. Raw aggregation functions do not interpolate the underlying series before aggregation. Raw functions aggregate data points by time buckets. For further information, see Standard Versus Raw Aggregation Functions.

Function Definition
sum(<expression> [,metrics|sources|sourceTags|pointTags|<pointTagKey> ]) Returns the sum of the time series described by expression. The results might be computed from real reported values and interpolated values.
rawsum(<expression> [,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the raw sum of the time series described by expression. The results are computed from real reported data values only, with no interpolated values.
avg(<expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the average (mean) of the time series described by expression. The results might be computed from real reported values and interpolated values.
rawavg(<expression> [,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the raw average (mean) of the time series described by expression. The results are computed from real reported data values only, with no interpolated values.
min(<expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the lowest value across the time series described by expression. The results might be computed from real reported values and interpolated values.
rawmin(<expression>[, metrics|sources| sourceTags|pointTags|<pointTagKey>]) Returns the lowest value across the time series described by expression. The results are computed from real reported data values only, with no interpolated values.
max(<expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the highest value across the time series described by expression. The results might be computed from real reported values and interpolated values.
rawmax(<expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the highest value across the time series described by expression. The results are computed from real reported data values only, with no interpolated values.
count(<expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the number of reporting time series described by expression, where a time series is counted as reporting even if it has interpolated values.
rawcount(<expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the number of reporting time series described by expression, 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(<expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the variance based on the time series described by expression. The results might be computed from real reported values and interpolated values.
rawvariance(<expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the variance across the time series described by expression. The results are computed from real reported data values only, with no interpolated values.
percentile(<percentage><expression>[,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the estimated percentile for the specified percentage, across the time series described by expression. The results might be computed from real reported values and interpolated values.
rawpercentile(<percentage>,<expression>[ ,metrics|sources| sourceTags|pointTags|<pointTagKey>]) Returns the estimated percentile for the specified percentage, across the time series described by expression. The results are computed from real reported data values only, with no interpolated values.

Grouping and Filtering

When aggregating, you can group or filter the results.

  • When you filter, you restrict the query, for example, only to certain sources. You still get one line for aggregation function. To filter, use the element to filter by inside the parenthesis.

  • You can also group the results of a query and display separate lines for the different group members. For example, when grouping by source, you get one line for each source. When grouping by source tags, you get one line for each source tag that is explicitly specified in the ts() expression.

    To group an aggregation by metrics, sources, source tags, all point tags keys, or a specific point tag key, include the
    [, metrics|sources|sourceTags|pointTags|<pointTagKey>] keyword after the ts() expression, separated by a comma.

Filter Example

sum(ts(~sample.cpu.loadavg.1m, source=app-1*)) shows the sum of the values reported for the metric, but only from the sources that match app-1*.

Grouping Examples

  • Group by metrics: sum(ts(cpu.loadavg.1m),metrics)
  • Group by sources: sum(ts(cpu.loadavg.1m),sources)
  • Group by source tags: sum(ts(cpu.loadavg.1m, tag=prod or tag=db),sourceTags)
  • Group by all available point tag keys: sum(ts(cpu.loadavg.1m),pointTags)
  • Group by the region point tag key: sum(ts(cpu.loadavg.1m),region)

Filtering and Comparison Functions

Function Definition
highpass(<expression1>, <expression2>[, inner]) Returns only the points in expression2 that are above expression1. expression1 can be a constant.
lowpass(<expression1>, <expression2>[, inner]) Returns only the points in expression2 that are below expression1. expression1 can be a constant.
min(<expression1>, <expression2>) Returns the lower of the two values in expression1 and expression2. For example: min(160, ts(my.metric)) returns 160 if my.metric is > 160. If my.metric is < 160, returns the value of my.metric.
max(<expression1>, <expression2>) Returns the higher of the two values in expression1 and expression2. For example: max(160, ts(my.metric)) returns 160 if my.metric is < 160. If my.metric is > 160, returns the value of my.metric.
between(<expression>, <lower>, <upper>) Returns 1 if expression is >= lower and <= upper. Otherwise, returns 0. This function outputs continuous time series.
downsample(<timeWindow>, <expression>) Returns the values in expression that occur in each time window. For example: downsample(30m, ts(my.metric)) returns the values of my.metric every half hour.
align(<timeWindow>,[mean|median|min|max|first|last|sum|count,] <expression>) Returns one value in expression for each time window. For example, if you are collecting data once a minute, but you want data points to be displayed every 30 minutes (summarized by median every 30 minutes), use align(30m, median, ts(my.metric)). See Bucketing with align().
topk(<numberOfTimeSeries>, <expression>) Returns the top numberOfTimeSeries series in expression, based on the most recent data point.
bottomk(<numberOfTimeSeries>, <expression>) Returns the bottom numberOfTimeSeries series in expression, based on the most recent data point.
top(<numberOfTimeSeries>, <expression>) Returns the top numberOfTimeSeries series in expression as 1, based on the most recent data point. Returns all other series as 0. This function outputs continuous time series.
bottom(<numberOfTimeSeries>, <expression>) Returns the bottom numberOfTimeSeries series in expression as 1, based on the most recent data point. Displays all other series as 0. This function outputs continuous time series.
filter(<expression> [, <metric>|source=|tagk=]) Retains only the time series in expression that match the specified metric, source, or point tag. No key is required to filter a time series. filter() is similar to retainSeries(), but does not support matching a source tag.
retainSeries(<expression> [, <metric>|source=|tag=|tagk=]) Retains only the time series in expression that match the specified metric, source, source tag, or point tag. No key is required to retain a time series.
removeSeries(<expression> [, <metric>|source=|tag=|tagk=]) Suppresses any time series in expression that matches the specified metric, source, source tag, or point tag. No key is required to remove a time series.
sample(<numberOfTimeSeries>, <expression>) Returns a non-random sample set of numberOfTimeSeries time series based on expression. Repeated calls display the same sample set as long as the underlying set of time series stays the same.
random(<numberOfTimeSeries>, <expression>) Returns a random set of numberOfTimeSeries time series based on expression. Repeated calls always display different sample sets.
limit(<numberOfTimeSeries>[, <offsetNumber>], <expression>) Returns numberOfTimeSeries time series. Use the optional offsetNumber to specify an index to start with.
hideBefore(<timeWindow>, <expression>) Hides data before a specified time. For example, hideBefore(10m) hides data that’s older than 10 minutes.
hideAfter(<timeWindow>, <expression>) Hides data after a specified time. For example, hideAfter(10m) hides data that’s newer than 10 minutes ago.

Standard Time Functions

Function Definition
rate(<expression>) Returns the per-second change of the time series described by expression. Recommended for counter metrics that report only increasing data values. Automatically handles zero-resets in counters.
deriv(<expression>) Returns the per-second change of the time series described by expression. Appropriate for metrics that report increasing or decreasing data values.
lag(<timeWindow>, <expression>) Returns earlier data values from the time series described by expression, time-shifting the values by timeWindow to enable you to compare a time series with its own past behavior.
lead(<timeWindow>, <expression>) Returns later data values from the time series described by expression, time-shifting the values by timeWindow to enable you to compare a time series with its own subsequent or forecasted behavior.
at(<timeWindow>, <expression>) Returns a data value reported at a particular time by the time series described by expression. The returned value is displayed continuously across the chart, so you can use it as a reference value for comparing against other queries.
year(<timezone>) Returns the year in the specified time zone. Years are returned as 4-digit numbers in the Gregorian calendar.
month(<timezone>) Returns the month of the year in the specified time zone. Months are returned as whole numbers from 1 (January) through 12 (December).
dayOfYear(<timezone>) 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>) 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>) 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>) Returns the hour within the day in the specified time zone. Hours are returned as decimal values from 0.0 to 24.0.
isToday(<timezone>) 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(<expression>) Returns the timestamps associated with the reported data values in the time series described by expression.
time() Returns the epoch seconds representing each point in time.

Moving Window Time Functions

Moving window time functions allow you to calculate continuous aggregation over sliding windows. 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
mavg(<timeWindow>, <expression>) Returns the moving average of each series for the specified time window.
msum(<timeWindow>, <expression>) 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>, <expression>) Returns the moving median of each series for the specified time window.
mvar(<timeWindow>, <expression>) Returns the moving variance of each series for the specified time window.
mcount(<timeWindow>, <expression>) Returns the number of data points reported by each time series over the specified time window.
mmin(<timeWindow>, <expression>) Returns the minimum of each series for the specified time window.
mmax(<timeWindow>, <expression>) Returns the maximum of each series for the specified time window.
mpercentile(<timeWindow>, <percentileValue>, <expression>) Returns the percentile of each series for the specified time window. The percentile value must be greater than 0 and less than 100.
mseriescount(<timeWindow>, <expression> [,<metrics> |sources|sourceTags|pointTags|<pointTagKey>]) Returns the aggregated number of series reporting during the specified time window.
mdiff(<timeWindow>, <expression>) 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>, <expression1>, <expression2> [,inner]) Returns the moving correlation between two expressions for a specified time window.
integrate(<timeWindow>, <expression>) Returns the moving integration for the specified expression for the specified time window.
integral(<expression>) Returns the moving sum over time for the given expression over the time window of the current chart window.
flapping(<timeWindow>, <expression>) Returns the number of times a counter has reset within the specified time window.
any(<timeWindow>, <expression>) Returns 1 if the expression has been non-zero at any time during the specified time window. Otherwise, returns 0.
all(<timeWindow>, <expression>) Returns 1 if the expression has been non-zero at every point in time during the time window. Otherwise, returns 0.

Conditional Functions

Function Definition
if(<conditionalExpression>, <thenExpression> [, <elseExpression>]) Returns points from thenExpression only while conditionalExpression > 0. Otherwise, returns points from elseExpression, if it is specified. conditionalExpression must evaluate to a series of numeric values, and typically includes numeric comparisons or transformations of time series. When both thenExpression and elseExpression return data, if() performs series matching against conditionalExpression.

Example: The query if(ts(my.metric) >= 10, ts(my.metric), ts(another.metric)) returns ts(my.metric) only when its values are >= 10. Whenever ts(my.metric) < 10, the query returns points from ts(another.metric).

When conditionalExpression and at least one of thenExpression or elseExpression is not a constant time series, this function outputs continuous time series.

Rounding Functions

Function Definition
round(<expression>) Returns the nearest integer for each data value in the specified time series.
ceil(<expression>) Returns the ceiling for the specified time series, by rounding any data values with decimals up to the next largest integer.
floor(<expression>) Returns the floor for the specified time series, by rounding any data values with decimals down to the next smallest integer.

Missing Data Functions

Missing data functions allow you to interpolate missing data with points based on other points in a series.

Function Definition
default([<timeWindow>, ]<delayTime> <defaultValue>, <expression>) Fills in gaps in expression with defaultValue (whether that's a constant or an expression). The optional timeWindow parameter fills in the specified period of time after each existing point (for example, 5m for 5 minutes). Without this argument, all gaps are filled in. The optional delayTime parameter specifies the amount of time that must pass without a reported value in order for the default value to be applied.
last([<timeWindow>, ] <expression>) Fills in gaps in expression with the last known value of expression. Use the optional timeWindow parameter to fill in a specified time period after each existing point.
next([<timeWindow>, ] <expression>) Fills in gaps in expression with the next known value of expression. Use the optional timeWindow parameter to fill in a specified time period before the first data point after the missing data.
interpolate(<expression>) Fills in gaps in expression with a continuous linear interpolation of points.

Metadata Functions

Metadata functions help users rename a metric, source, or create a synthetic point tag on a metric. There are three ways to formulate the alias:

  • Node index - Extract a string component based on a zeroBasedNodeIndex. Components are identified by the default delimiter “.” or a delimiter specified in delimiterDefinition.
  • Regular expression replacement - Identify the string using a regular expression and replacement string using a replacement pattern.
  • String substitution - Replace a metric or source in an expression with a replacement string.
Function Definition
aliasMetric(<expression>[,metric|source|{tagk,<pointTagKey>},][zeroBasedNodeIndex[ delimiterDefinition] | "<regexSearchPattern>", "<replacementPattern>" | "<replacementString>")] Extracts a string from an existing metric name, source name, or point tag value and renames the metric in the expression with that string. If you don’t specify the metric|source|{tagk, <pointTagKey>} parameter, it defaults to source.
aliasSource(expression[,metric|source|{tagk,<pointTagKey>},] [zeroBasedNodeIndex[ delimiterDefinition] | "regexSearchPattern", "replacementPattern" | "replacementString")] Replaces one or more source names in a ts() expression with a string extracted from the metric name(s), source name(s), or point tag value(s).
taggify(expression,metric|source|{tagk,<pointTagKey>},<newPointTagKey>, [zeroBasedNodeIndex[ delimiterDefinition] | "regexSearchPattern", "replacementPattern" | "replacementString")] Lets you extract a string from an existing metric name, source name, or point tag value and create a synthetic point tag key value for that query.

Examples

  • Node index: aliasMetric(ts(cpu.loadavg.1m, source), 1) the extracted string is selected by node index. The metric cpu.loadavg.1m has 3 components. Setting zeroBasedNodeIndex to 1 extracts the second component (loadavg).
  • Node index with delimiter: cpu-loadavg-1m sets delimiterDefinition to -.
  • String substitution:
    • Original: max(ts(customer.alerts.active), metrics)
    • Renamed: aliasMetric(${original}, "Total Number Of Alerts"), replaces the metric customer.alerts.active with "Total Number Of Alerts".

Exponential and Trigonometric Functions

Function Definition
sqrt(expression) Returns the square root of expression.
pow(expression, expression[, inner]) Raises expression to the power of expression. Wavefront does not support imaginary numbers, so pow(-1, 0.5) returns no data.
exp(expression) Returns the exponential of expression.
log(expression) Returns the natural log of expression.
log10(expression) Returns the log base 10 of expression.
toDegrees(numRadians), toRadians(numDegrees) Convert radians to degrees, and vice versa.
sin(expression), cos(expression), tan(expression),
asin(expression), acos(expression),
atan(expression), atan2(expression),
sinh(expression), cosh(expression), tanh(expression)
Performs the specified trigonometric function on expression interpreted in radians.

Predictive and Histogram Functions

Function Definition
hw([<historyLength>, <seasonLength>, <samplingRate>, <expression> [<alpha>, <beta>, <gamma>]) Returns a smoothed version of the expression and forecasts its future points using the Holt-Winters triple exponential smoothing algorithm for seasonal data.
hs(<histogram_metric>) Returns a histogram metric, which you can query with certain other query language functions. See Wavefront Histograms for details.

Event Functions

You can use event functions to display events in charts, for example, to inform other users about reasons for an event. Other event functions help you filter events, so that only events you’re interested in are displayed. Some events() functions return synthetic events. These events are displayed by the query, but not stored in Wavefront.

See Basic events() Queries. See Advanced events() Queries for details about the different kinds of events() functions.

Function Definition
events(<filters>) Returns the set of events that match <filters>. See Event Filters for a list of available filters. The returned set of events can be passed as an argument to functions that accept events. When passed to a chart query, displays the events. The chart must contain at least 1 ts() expression for events to display.
count(<events>) Converts <events> into a single time series, where every data point represents the number of events that started at that time minus the number of events that ended at that time. Instantaneous events are represented as a single "0" value: 1 started minus 1 ended (instantaneous events are defined as events having their end time equal to their start time).
ongoing(<events>) Returns a continuous time series representing the number of ongoing events at any given moment within the query time window. See When Does an Event Query Return Events? for some background information.
closed(<events>) Returns events that have ended and instantaneous events that occurred in the past.
until(<events>) Returns synthetic events that start at the beginning of epoch time (Jan 1, 1970) and end where the input events start.
after(<events>) Returns synthetic ongoing events that start the moment the input events end.
since(<events>) Returns synthetic events with the same start time and no end time (converts all input events to ongoing events).
since(timeWindow) Creates a single synthetic event that started timeWindow ago and ended "now". Specify timeWindow in seconds, minutes, hours, days or weeks (e.g., 1s, 1m, 1h, 1d, 1w. Default is minutes.
timespan(startTimestamp, endTimestamp) Creates a single synthetic event with the specified start and end timestamps. A timestamp can be expressed in epoch seconds or using a time expression such as "5 minutes ago". Example: timespan("5 minutes ago", "2 minutes ago").
first(<events>) Returns a single event with the earliest start time.
last(<events>) Returns a single event with the latest start time.
firstEnding(<events>) Returns a single event with the earliest end time.
lastEnding(<events>) Returns a single event with the latest end time.

The following example shows a query you could use to filter the events in your charts.

events(type=alert, name="disk space is low", alertTag=MicroService.App1.*)

See Event Filters for details on filters.

Miscellaneous Functions

Function Definition
collect(<expression1>, <expression2> [, <expression3>, ...]) Returns a single ts() expression that is the combination of two or more ts() expressions.
exists(<expression>) Returns 1 if any time series described by the expression exists, and returns 0 otherwise. A time series exists if it has reported a data value in the last 4 weeks.
abs(<expression>) Returns the absolute value of the time series described by the expression.
random() Returns random values between 0.0 and 1.0. Repeated calls display different random values.
normalize(<expression>) Normalizes each time series described by the expression, so that its values are scaled between 0 and 1.0.
haversine(<lat1>, <long1>, <lat2>,<long2>) Returns the distance between a pair of coordinates.

Discrete Versus Continuous Time Series

Many Wavefront queries operate on and return data as one or more time series. Each time series is a unique sequence of data points that consists of a data value and a timestamp.

  • A discrete time series consists of data points separated by time intervals that are greater than one second. A discrete time series might have:
    • A data-reporting interval that is infrequent (e.g., 1 point per minute) or irregular (e.g., whenever a user logs in)
    • Gaps where values are missing due to reporting interruptions (e.g., intermittent server or network downtime)
  • A continuous time series contains one data point per second. Because Wavefront accepts and stores data at up to 1 second resolution, a continuous time series has a data value corresponding to every moment in time that can be represented on the X-axis of a chart.

For example, the following chart shows a point plot for the results of two queries. The query labeled Discrete returns multiple time series, each consisting of data points that occur 1 minute apart (at 9:30, 9:31, 9:32, and so on). The query labeled Continuous returns the constant value 160 for every second in the chart.

discrete continuous

A discrete time series is still discrete, even if you use a line plot to display it. The following chart shows the same queries, but with the points connected by lines in the display. (By default, gaps larger than 60 seconds would be shown as dotted lines.)

discrete continuous lineplot

Functions that Preserve Discrete Data

Most query language functions that operate on a discrete time series return a new time series that is also discrete.

Some functions operate on an input time series to produce a new series with the same number of data points at exactly the same times, but with values resulting from some calculation. The result time series will have the same intervals and gaps as the original input time series did. For example:

  • The floor() function visits each point in a given time series, rounds the point’s data value down to the nearest integer, and assigns the result of that calculation to a new point with a matching timestamp.

Some functions operate on an input time series to produce a new series that has fewer data points. The points in the result series might have different timestamps, different values, or both, and the series typically has wider intervals and gaps. For example:

  • The align() function groups the input data points into “buckets”, and returns a new series that consists of one data point per bucket.
  • The lowpass() function returns a new series that consists of data points that match just the input points whose values fall below a specified threshold.

Functions that Create Continuous Data

Certain query language functions and expressions return a new time series that is guaranteed to be continuous (have one data point per second).

Some functions and expressions produce a continuous time series in which a constant value is assigned to every possible data point. For example:

  • The expression 160 assigns the value 160 to every data point in a continuous result series.
  • The at() function obtains a value from a past data point in an input time series, and assigns that value to every data point in a continuous result series.

Some functions produce a continuous time series by calculating a value from the timestamp of each data point. For example:

  • The dayOfYear() function produces a time series by correlating every second of a time line with the day of the year it falls on.

Functions that Use Interpolation to Create Continuous Data

Certain functions produce a continuous time series by starting with data points from a discrete time series, and inserting additional points (1 per second) to fill in the intervals and gaps. You see data every second regardless of the reporting interval of the underlying input data.

The process of filling in intervals and gaps is called interpolation. For example:

  • The last() function produces a new time series that consists of the actual, reported data points from the input series, plus points that are added by interpolation between them. Each interpolated point has the same value as the last reported point before it.

Here’s a point plot showing a discrete series (the red dots) and the points (blue dots) produced by applying last(). The points of the discrete series are reported once a minute, and the points between them are all interpolated.

continuous last

Different functions use different techniques to calculate the values of interpolated points. For example:

  • When the last() function inserts a new point with a particular timestamp, the value assigned to that point is taken from the last actual, reported point before it.
  • When the interpolate() function inserts a new point with a particular timestamp, the value assigned to that point is an estimate of what the input series would have reported at that time, based on the values of the actual, reported points on either side.

Note: Interpolation is used for different purposes by different functions. For example:

  • Functions such as last(), interpolate(), and the others summarized below use interpolation to fill in all gaps to produce a result series that is guaranteed to be continuous.
  • Standard aggregation functions such as sum() and avg() use interpolation to fill in specific gaps in an input series before including that series in the aggregation. The result series produced by an aggregation function is normally discrete. See Standard Versus Raw Aggregate Functions.

Summary of Functions that Return Continuous Time Series

The following functions always return continuous time series, even when they operate on an input series that is discrete: