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

VMware Aria Operations for Applications (formerly known as Tanzu Observability by Wavefront) includes the Wavefront Query Language, which 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:
  • A ts() function, which returns all points that match a metric name, filtered by source names, source tags, and point tags. (Alert metrics are filtered by alert tags.) 
    ts(<metricName> [and|or [not] <metricName2>] ...
  [,|and|or [not] source="<sourceName>"] ...
  [and|or [not] tag="<sourceTag>"] ...
  [and|or [not] <pointTagKey>="<pointTagValue>"] ... )
    Example: ts(~sample.disk.bytes.written, source="app-1" or source="app-2" and env="dev")
  • A constant, which returns a constant value for each data point. Specify as a number or use SI prefixes (k, M, G, T, P, E, Z, Y) to scale by multiples of 1000. Examples:
    5.01
    40
    1M (or 1000000)
    7.2k (or 7200)
  • An operator expression that combines tsExpressions and constants:
    (ts(disk.space.total) - ts(disk.space.used)) * 2
  • A query function that returns time series from other input time series:
    msum(10m, ts(~sample.requests.latency, source="app-14"))
  • A query function that returns time series by converting input data of another type:
    avg(hs(users.settings.numberOfApiTokens.m))
<hsExpression> Describes one or more histogram series. A histogram series is a sequence of histogram distributions that the service 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:
  • An hs() function, which returns all distributions that match a histogram metric name, filtered by source names, source tags, and point tags. 
    hs(<hsMetricName> [and|or [not] <hsMetricName2>] ...
  [,|and|or [not] source="<sourceName>"] ...
  [and|or [not] tag="<sourceTag>"] ...
  [and|or [not] <pointTagKey>="<pointTagValue>"] ... )
    Example: hs(users.settings.numberOfApiTokens.m, source="host1" and customer="qa")
  • A query function that returns histogram series from other input histogram series:
    align(10m, hs(users.settings.numberOfApiTokens.m))
<eventsExpression> Describes a set of events. An eventsExpression may be one of the following:
  • An events() function, which returns all events that match the specified event filters. 
    events(<filterName>="<filterValue>"
  [,|and|or [not] <filter2Name>="<filter2Value>"] ... )
    Example: events(type="alert", name="disk space is low", alertTag="App1.*")
  • A query function that returns a set of events from an input event set:
    closed(events(type="alert", name="disk space is low", alertTag="App1.*"))
  • An events operator expression that combines eventsExpressions:
    events(type="maintenanceWindow") intersect events(name="test")
<tracesExpression> Describes a set of traces. A tracesExpression may be one of the following:
  • A traces() function, which returns all traces that contain at least one span that represents the specified operation and matches the specified span filters. 
    traces("<fullOperationName>"
  [,|and|or [ not] <filterName>="<filterValue>"] ... )

traces(<spansExpression>)
    Example: traces("beachshirts.styling.makeShirts", source="app-1")
  • A query function that returns a list of traces by filtering an input list of traces:
    lowpass(12ms, traces("beachshirts.styling.makeShirts"))
<spansExpression> Describes a set of spans. A spansExpression may be one of the following:
  • A spans() function, which returns all spans that represent the specified operation and that match the specified span filters. 
    spans("<fullOperationName>"
  [,|and|or [ not] <filterName>="<filterValue>"] ... )
    Example: spans("beachshirts.styling.makeShirts", source="app-1")
  • A query function that returns a list of spans by filtering an input list of spans:
    lowpass(12ms, spans("beachshirts.styling.makeShirts"))
Note: You cannot use a spansExpression by itself as a top-level query. Instead, you always use a spansExpression as a parameter to a traces() function.
 click for top of page

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 or partial regex to match multiple names or values.

  • Rules for valid names are here: Data Format.
  • Enclose a metric, source, or tag name, or a tag value, in double quotes if it is also a reserved word in the product, 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
/(cpu\.load\.metric|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="app-1*"
source="app-10" or source="app-20"
source=/(app-10|app-20)/
<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"
tag=/(appServer|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. Use double quotes around both key and value.
Examples: 
region="us-west-2a"
region="us-west*"
region="us-west-2a" or region="us-west-2b"
<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:
  • Use = to specify a filter that is set to a particular value. Example: 
    source="appServer15"   // include only data from a source called appServer15
  • Use != to specify a filter that is set to any value except the specified value. Example 
    source!="appServer15"  // include data from any source except appServer15
  • Use ?= to get everything that has mytagvalue or doesn't have myTagKey. Example: 
    myTagKey?="mytagvalue" // everything that has mytagvalue or doesn't have myTagKey
Note: See Organizing with Tags for information on the supported types of tags and how to use them.
<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). We calculate 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.
 click for top of page

Partial Regex, Wildcards, Aliases, and Variables

You can:

  • Use partial regex to specify patterns that need to be matched when building a query.
  • Use wildcards as shortcuts for specifying multiple names or values.
  • Use query line variables, aliases, and dashboard variables as shortcuts for building queries out of other expressions or predefined strings.
  • Combine wildcards, aliases, query line variables, and dashboard variables in the same query line.
Term Definition
partial regex Filter metrics, sources, source tags, or point tag values using a subset of regular expressions. You wrap regular expressions in / / characters. For example, /<regular_expression>/.

The list of supported regular expression characters and quantifiers: 
.     : any character (but newline)
*     : previous character or group, repeated 0 or more times
+     : previous character or group, repeated 1 or more times
?     : previous character or group, repeated 0 or 1 times
[xyz] : any character contained within the brackets
[a-z] : characters between a and z. Specify a range of characters using a hyphen
^     : a character not in the range: a-z [^a-z]
\     : prevents interpretation of the special character that follows
|     : or
(  )  : start/end of group
Examples:
  • Get data that match ~wavefront.alert.active or ~wavefront.alert.active_info and has the source tag data: 
    ts(/~wavefront\.alert\.(active|active_info)/, tag=data)
  • Get data that match build.version or build. and has the source tag data: 
    ts(/build\.(version)?/, tag=data)
  • Get data of all the sources that follow the given pattern, e.g., app-0, app-12, app-30, and more: 
    ts(~sample.cpu.usage.percentage, source=/app-[0-9]+/)
  • Get data from the metrics that have request.latency as the common prefix and has the tag env=prod: 
    ts(/request\.latency.*/, env=prod)
wildcard Matches strings or components in a name or a value.
  • Use a "*" character to indicate where to match strings. No other wildcard characters are supported.
Examples:
  • ~sample.cpu.usage.* matches metric names ~sample.cpu.usage.user.percentage and ~sample.cpu.usage.percentage.
  • tracing.derived.beachshirts.*.duration.micros.m matches histogram duration metric names for all operations of all services of the beachshirts application.
  • httpstatus.api.* and ("*.POST.*" or "*.PUT.*") matches httpstatus.api metrics for POST or PUT operations.
  • source="app-1*" matches all sources starting with "app-1", such as app-10, app-11, app-12, app-110, and so on.
  • region="*" matches the time series that have the region point tag with any value and filter out any time series without a region point tag.
  • not region="*" finds any time series that do not have the region point tag.
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.
  • Use as to define an alias within a query: <tsExpression> as <aliasName>
  • Use $ to reference the alias in the same query: $aliasName
  • But omit the $ prefix when using aliases in a join() query: aliasName
Examples: 
if(ts(requests.latency, source="app-1*") 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:
  • Best practice: Use alias names that are three characters or longer.
  • Don't use a reserved word as an alias name. For example, don't use:
    • The name of any WQL function. For example, sum is not valid.
    • An SI prefix. For example: p, h, k, M, G, T, P, E, Z, Y are not valid.
    • An Allen's interval algebra operator. For example: m, mi, o, s, d, f are not valid.
  • Alias names are case-sensitive. For example, Sum is valid.
  • Put any numeric characters at the end of the alias name. For example, test123 is valid, but 1test and test4test are not valid.
query line variable Let's use one query line refer to another for the same chart. The referenced query line must be named and must contain a complete tsExpression.
  • Use the chart UI to name a query: myQuery
  • Use this syntax to reference the named query in another query: ${myQuery}
Example. Suppose you assign a name to a long or complex query: 
latency       ts(requests.latency, source="app-1*" 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.
  • Use the dashboard UI to define a dashboard variable: myDashVar
  • Use this syntax to refer to the dashboard variable in a query: ${myDashVar}
Example. Suppose a dashboard variable az has the value "tag=az-3 or tag=az-4". You can use the dashboard variable as follows: 
ts(requests.latency, ${az})
This is equivalent to typing in: 
ts(requests.latency, tag="az-3" or tag="az-4")
Note: A dashboard variable can expand to any text string, unlike query line variables and aliases, which must be complete tsExpressions.
 click for top of page

Time-Series Operators

All operations between tsExpressions are subject to the matching processes described in Series Matching​. The result is always interpolated.

  • Boolean operators - Combine tsExpressions, 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. The query engine 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.

    In addition, we support the pow() and mod() functions, which support power of and modulo arithmetic operations.

  • 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 WQL 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.*" for any sources that start with -eq.

    For additional examples, see Use AND, OR, and NOT Operators

 click for top of page

Aggregation Functions

Aggregation functions are a way to combine (aggregate) multiple time series into a single result series. When data points do not line up, the two types of aggregation functions handle them 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 point-tag values. For example, if you have an env point tag with values dev and prod, you can return one series for all points that come from dev and another for all points that come from prod.
Function Definition
sum(<tsExpression>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[, metrics|sources| sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources|sourceTags|pointTags|<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>
[,metrics|sources| sourceTags|pointTags|<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.
 click for top of page

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.
align(<timeWindow>,[mean|median|min|max|first|last|sum|count,] <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>,
[mean|median|min|max|sum|count|last, [<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>,
[mean|median|min|max|sum|count, [<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>,
[mean|median|min|max|sum|count|last, [<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>,
[mean|median|min|max|sum|count, [<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>
[and|or [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>
[and|or [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>
[and|or [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> [and|or [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 non-random 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.
 click for top of page

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 per-second 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 per-second 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, time-shifting 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, time-shifting 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 4-digit 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 28-31.
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 timeZone. The values returned are integer only and are in the range 0-23.
minute(<timezone> [,<tsExpression>]) Returns the minute of the hour for the timestamp specified by timeZone. The values returned are integer only and are in the range 0-59.
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.
 click for top of page

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> [,metrics|sources|sourceTags|pointTags|<pointTagKey>]) Returns the number of unique values over the specified time window.
mslope(<timeWindow>, <tsExpression>) Returns the per-second 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> [,metrics|sources|sourceTags|pointTags|<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 non-zero at any time during the specified time window. Otherwise, returns 0.
all(<timeWindow>, <tsExpression>) Returns 1 if the expression has been non-zero at every point in time during the time window. Otherwise, returns 0.
 click for top of page

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 is obsolete or nonexistent.
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.
.orElse(<tsExpression>) You can use the .orElse() operator to force the query to return a default value even if the time series is obsolete or nonexistent. You can enter a constant value wrapped in brackets, such as orElse(5). You can also enter a timeseries for chained .orElse() statements, for example .orElse(ts('my.metric')).
 click for top of page

Conditional Function

The if() conditional function returns data values from time series based on a specified condition.

Function Definition
if(<condition-tsExpression>,
<then-tsExpression>
[, <else-tsExpression>])		 Returns points from then-tsExpression only while condition-tsExpression > 0. Otherwise, returns points from else-tsExpression, if it is specified.
condition-tsExpression must evaluate to a series of numeric values, and typically includes numeric comparisons or transformations of time series.
rawif(<condition-tsExpression>,
<then-tsExpression>
[, <else-tsExpression>])		 Returns points from then-tsExpression only while condition-tsExpression > 0. Otherwise, returns points from else-tsExpression, if it is specified.
condition-tsExpression must evaluate to a series of numeric values, and typically includes numeric comparisons or transformations of time series.
The results are computed from real reported data values only, with no interpolated values.
 click for top of page

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.
 click for top of page

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(<base-tsExpression>, <exponent-tsExpression>[, 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.
log2(<tsExpression>) Returns the log base 2 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(<y-expression>, <x-expression>),
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.
 click for top of page

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 WQL join() function is modeled after the SQL JOIN operation, and supports inner joins, left outer joins, right outer joins, and full outer joins.

 click for top of page

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 from cpu-loadavg-1m.
  • 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>, [metric|source|{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>, [metric|source|{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>, metric|source|{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.
 click for top of page

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(metric|source|<pointTagKey>, <tsExpression>) Returns the length of in the specified metadata string.
isEmpty(metric|source|<pointTagKey>, <tsExpression>) Returns true if the specified metadata string is an empty string. Otherwise, returns false.
isBlank(metric|source|<pointTagKey>, <tsExpression>) Returns true if the specified metadata string is a blank character (" "). Otherwise, returns false.
toLowerCase(metric|source|<pointTagKey>, <tsExpression>) Converts all uppercase characters to lowercase in the specified metadata string.
toUpperCase(metric|source|<pointTagKey>, <tsExpression>) Converts all lowercase characters to uppercase in the specified metadata string.
trim(metric|source|<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(metric|source|<pointTagKey>, <tsExpression>) Removes both leading and trailing white spaces from the specified metadata string.
stripLeading(metric|source|<pointTagKey>, <tsExpression>) Removes leading white spaces from the specified metadata string.
stripTrailing(metric|source|<pointTagKey>, <tsExpression>) Removes trailing white spaces from the specified metadata string.
equals(metric|source|<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(metric|source|<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(metric|source|<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 "us-west-1".
startsWith(metric|source|<pointTagKey>, "<string>", <tsExpression>) Returns true if the specified metadata string starts with the given string. Otherwise, returns false.
endsWith(metric|source|<pointTagKey>, "<string>", <tsExpression>) Returns true if the specified metadata string ends with the given string. Otherwise, returns false.
indexOf(metric|source|<pointTagKey>, "<subString>", <tsExpression>) Finds the first occurrence of the specified substring in the metadata string and returns the starting position of that occurrence.
lastIndexOf(metric|source|<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(metric|source|<pointTagKey>, "<string>", <tsExpression>) Concatenates the specified string by adding it to the end of the specified metadata string.
contains(metric|source|<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(metric|source|<pointTagKey>, <integer>, <tsExpression>) Returns the character at the specified position in the specified metadata string.
substring(metric|source|<pointTagKey>, [<integer>]|[<integer1>, <integer2>], <tsExpression>) Returns a substring that is extracted the specified metadata string.
repeat(metric|source|<pointTagKey>, <integer>, <tsExpression>) Repeats the specified metadata string a specified number of times.
 click for top of page

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 Holt-Winters double exponential smoothing algorithm. Optionally, supports the Holt-Winters 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.
 click for top of page

Miscellaneous Time-Series 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.
  • If there are no data points, returns 1.
  • Otherwise, returns 0.
exists(<tsExpression>) Returns 1 if any time series described by the expression exists. Otherwise, returns 0. A time series exists if it has recently reported a data value, so that it hasn't become obsolete.
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 the query engine to use conservative targets for scheduling workloads. That means we limit thread use and asynchronous operations.
removeDimension(<tsExpression>, <pointTag1>, <pointTag2>, ... <pointTagN>) Allows you to explicitly state which dimensions you want to remove from the query output.
retainDimension(<tsExpression>, <pointTag1>, <pointTag2>, ... <pointTagN>) Allows you to explicitly state which dimensions you want to see in the query output.
 click for top of page

Histogram Functions

You use histogram query functions to access the histogram distributions that were computed from a metric. See 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> [and|or [not] <hsMetricName2>] ...
[,|and|or [not] source="<sourceName>"] ...
[and|or [not] tag="<sourceTag>"] ...
[and|or [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 time-series chart, this function displays the median values of the distributions in the matched histogram series.
merge(<hsExpression>
[, metrics|sources|sourceTags|pointTags|<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 time-series 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 time-series 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 a 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>, [,metrics|sources|sourceTags|pointTags|<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> [,metrics|sources|sourceTags|pointTags|<pointTagKey> ]) Returns a cumulative histogram that comes, for example, from Prometheus or Telegraf. You can then use functions such as percentile to visualize the histogram in charts and dashboards.
cumulativePercentile(<percentage>, <tsExpression>) Calculates the percentile value directly that comes from a Prometheus cumulative histogram. Returns the percentage percentile from the histogram distribution described by the <tsExpression>.
frequencyHisto([timeWindow], [<bucketName>, ] <tsExpression> [,metrics|sources|sourceTags|pointTags|<pointTagKey> ]) Converts a histogram coming from Google Cloud Platform(GCP) to our histogram format. When GCP Detailed Histogram Metrics is enabled, we additionally ingest bucket counts for GCP distributions, with metric namegcp.<metric>.bucket. Enabling this increases ingestion rate and cost.
 click for top of page

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.

Event to Event
Function		 Definition
events(<filterName>="<filterValue>"
[,|and|or [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 time-series 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.
 click for top of page

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>"
[,|and|or [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.
 click for top of page

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.

Function Definition
spans("<fullOperationName>"
[,|and|or [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.
 click for top of page

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.
 click for top of page
query language