Functions

Overview

Functions are predefined procedures that calculate a value or perform a task. Functions are called by name with arguments passed in round brackets and separated by comma. Function names are case-sensitive.

/* Returns true if the create_ms date is a working day. */
to_datetime(create_ms, 'US/Pacific').is_workday()

When invoked in expressions and placeholders, function definitions are replaced with the value returned by the function.

Functions can be referenced in a filter expression, user-defined variables, condition statements and placeholders.

  • Filter Expression:

    lower(tags.location) = 'nur'
    
  • Condition:

    avg() > 80 && db_statistic('avg', '15 minute', 'metric-2')
    
  • Placeholder:

    ${lookup('assets', entity)}
    

Arguments

The parameters passed to the function in round brackets are called arguments.

Functions can accept arguments and return values in one of the following data types:

Notation Name Example
double double number percentile(99.5)
long long number elapsedTime(last_open().command_time)
int integer number round(avg(), 1)
number any number abs(value)
bool boolean formatBytes(avg(), true)
string string startsWith(entity, 'NUR')
[number] collection of numbers randomItem([1, 2, 3])
[string] collection of strings coalesce([tags.location, 'SVL'])
[k: v] key-value map randomKey(['john.doe': 0.8, 'mary.jones': 0.2])
map key-value map addTable(tags, 'html')
object object to_timezone(now, 'US/Pacific')

Optional arguments are annotated with square brackets.

date_format(long time [, string pattern]) string

If the argument can be of different data types, such types are enumerated with | symbol.

db_last(string metric, string entity, string tags | map tags) number

Collection

Name Description
contains Returns true if string on the right is contained in the specified collection.
collection_contains Returns true if the specified collection contains the value.
excludeKeys Returns a copy of the input map without the keys in the input collection.
copyList Copy a list.
copyMap Copy a map.
createMap Create a new map.
compareMaps Compare two maps.
mergeMaps Merge two maps.
flattenJson Converts the string representation of JSON document into a map.
IN Returns true if string on the left is contained in the list of strings on the right.
isEmpty Returns true if the number of elements in the collection is zero.
jsonPathFilter Returns a list of objects matching the JSONPath expression.
jsonToLists Returns a collection of string lists containing field values from the JSON.
jsonToMaps Returns a collection of maps containing keys and values from the JSON.
LIKE Returns true if string on the left matches any pattern in the list on the right.
likeAny Returns true if string matches any element in the string collection.
matches Returns true if one of the elements in collection matches the given pattern.
matchList Returns true if string matches one of the elements in the collection.
size Returns the number of elements in the collection.

Content

Tables

Name Description
addTable for list Prints list of lists as a multi-column table in the specified format.
addTable for map Prints a key-value map as a two-column table in the specified format.
addTable for maps Prints a collection of maps as a multi-column table in the specified format.
addTable for objects Prints a collection of objects as a multi-column table in the specified format.
detailsTable Prints a two-column table consisting of window and command fields in the specified format.
Name Description
addLink Returns the URL with a formatted short name.
getEntityLink Returns the URL to the Entity Editor page for the specified entity.
getChartLink Returns the URL to the default portal for the current metric, entity, and tags.
getOHLCVChartLink Returns the URL to the default OHLCV portal.
getCsvExportLink Returns the URL to the CSV file for the current metric, entity, and tags.
getPortalLink Returns the URL to the portal and entity.
getHtmlExportLink Returns the URL to the Export page for the current metric, entity, and tags.
getPropertyLink Returns the URL to the property table for the given entity and property type.
getRuleLink Returns the URL to the current rule.

Portal

Name Description
addPortal Attaches portal screenshots to email and webhook notifications.
addOHLCVPortal Attaches OHLCV portal screenshots to email and webhook notifications.

Database

Messages

Name Description
db_message_count Returns the number of message records matching the specified parameters.
db_message_last Returns the most recent message record for the specified parameters.
db_messages Returns a list of message records matching the specified parameters.

Properties

Name Description
getPropertyTypes Returns a sorted set of property types for the specified entity.
property Retrieves tag value for the given property search expression.
property_map Returns a map with keys and tags for the given property search expression.
property_maps Returns a list of maps for the given property search expression.
property_values Returns a list of tag values for the given property search expression.
property_compare Compares properties in the previous and the current property command.
property_compare_except Compares properties in the previous and the current property command with name and value filters.

Series

Name Description
db_last Retrieves the most recent value stored in the database for the target series.
db_statistic Returns the value of a statistical function for historical values.
db_statistics Returns descriptive statistics for the specified series.
db_multi_statistics Returns descriptive statistics for multiple series.
db_baseline Returns the expected (baseline) value for same periods in the past.

Related Functions

See value functions.

Forecasts

Name Description
forecast Returns forecast object for the entity, metric, and tags in the current window.
forecast_deviation Returns difference between a number and the interpolated forecast value, divided by the forecast standard deviation.
forecast_score_stdev Returns the standard deviation for forecast values from actual values within the scoring interval.
forecast_stdev Returns forecast standard deviation.
thresholdTime Returns the estimated time when the forecast value is outside of the (min, max) range.

Alert History

Name Description
last_open Retrieves the most recent Alert History record for the current window.

SQL Query

Name Description
executeSqlQuery Returns the result of SQL query as list of rows.
queryToMap Returns the result of SQL query as a map.

Lookup

Name Description
collection Returns an array of strings contained in Named Collection.
entity_label Returns label for the specified entity.
entity_tag Returns value of the specified tag name for the specified entity.
entity_tags Returns entity tags for the specified entity as a map.
getEntities Returns a list of Entity objects matching the given parameters.
getEntity Retrieves an entity object by name.
getEntityCount Returns a count of Entity objects matching the given parameters.
getEntityName Returns normalized (lowercase) entity name for the specified entity.
lookup Returns the value for the specified key from the replacement table.
lookup_row Returns the row object for the specified key from the replacement table of CSV type.
replacementTable Returns the Replacement Table as a key-value map.
get_group_emails Returns the list of email addresses for the members of the specified user group.
subscribers Returns the list of email addresses for topic subscribers.

Date

Name Description
add Returns a DateTime object created by adding an interval.
date_format Converts Unix time in milliseconds or a DateTime object to a string.
DateFormatter Creates a formatter object to convert Unix times in milliseconds or DateTime objects to strings.
IntervalFormatter Creates a formatter object to convert the interval between two dates to a string.
date_parse Parses the input string into a DateTime object.
elapsed_minutes Calculates the number of minutes between the current and specified time.
elapsedTime Calculates the number of milliseconds between the current and specified time.
formatInterval Converts milliseconds interval to a formatted interval.
formatIntervalShort Converts milliseconds interval to a formatted interval consisting of up to the two highest subsequent non-zero time units.
formatSecondOffset Converts UTC offset in seconds to time zone pattern ±hh:mm.
is_weekday Returns true if the DateTime object is a weekday.
is_weekend Returns true if the DateTime object is a weekend day.
is_workday Returns true if the DateTime object is a working day.
is_exceptionday Returns true if the DateTime object is a working weekend or a holiday working day.
milliseconds Parses the date string into Unix time in milliseconds.
now Returns the current time as a DateTime object.
seconds Parses the date string into Unix time in seconds.
to_datetime Returns DateTime object in the server time zone from Unix milliseconds.
to_timezone Returns a new DateTime object modified to the specified time zone.
today Returns the current day at midnight, 00:00:00, as a DateTime object.
tomorrow Returns the following day at midnight, 00:00:00, as a DateTime object.
window_length_count Returns the length of a count-based window.
window_length_time Returns the length of a time-based window in seconds.
windowStartTime Returns time when the first command is received by the window.
yesterday Returns the previous day at midnight, 00:00:00, as a DateTime object.

Formatting

Name Description
convert Divides the number by the unit and formats with one fractional digit.
formatBytes Returns the total number of bytes in human-readable format.
formatNumber Formats number with the specified DecimalFormat using the server locale.
NumberFormatter Creates a formatter object to convert numbers to strings.

Mathematical

Name Description
abs Returns the absolute value of the argument.
cbrt Returns cube root of the argument.
ceil Returns the smallest integer that is greater than or equal to the argument.
exp Returns Euler constant e (2.7) raised to the power of the argument.
floor Returns the largest integer that is less than or equal to the argument.
log Returns the natural logarithm (base e = 2.7) of the argument.
log10 Returns the base 10 logarithm of the argument.
max Returns the greater of two numbers.
min Returns the smallest of two numbers.
pow Returns the first specified number raised to the power of the second number.
round Returns the specified number rounded to the specified precision.
signum Returns the signum function of the argument.
sqrt Returns of the argument.

Random

Name Description
random Returns a uniformly distributed double number.
randomItem Returns a random element from a collection or map.
randomKey Returns a random element from the map of objects.
randomNormal Returns a normally distributed double number.

Window

Name Description
rule_open Checks if there is at least one open window for the specified arguments.
rule_window Returns the first matching Window object for the specified arguments.
rule_windows Returns the collection of Window objects for the specified arguments.

Script

Name Description
scriptOut Executes the predefined script and return its output.

Security

Name Description
userAllowEntity Returns true if the specified user has READ permission for the given entity.
userAllowEntityGroup Returns true if the user has READ permission to the given entity group.
userAllowPortal Returns true if the specified user has permissions to view the given portal.
userHasRole Returns true if the specified user has the specified role.
userInGroup Returns true if the specified user belongs to the specified user group.

Statistical

Scope

Statistical functions are not supported in the filter expression.

Name Description
avg Calculates average value.
avgIf Calculates average of elements matching the specified condition.
count Value count. The function ignores NaN values.
countNaN NaN count. A sum of count and countNaN is equal to the number of samples in the window.
countIf Counts elements matching the specified condition.
delta Calculates difference between last and first values.
diff Calculates difference between last and first values.
first Returns first series value.
intercept Calculates linear regression intercept.
last Returns last value.
max Returns maximum value.
min Returns minimum value.
mean Calculates average value.
median Returns 50% percentile (median).
new_maximum Returns true if last value is greater than any previous value.
new_minimum Returns true if last value is smaller than any previous value.
percentile Calculates n-th percentile.
rate_per_hour Calculates the hourly difference between last and first value input.
rate_per_minute Calculates the difference between last and first value per minute.
rate_per_second Calculates the difference between last and first value per second.
slope Calculates linear regression slope.
slope_per_hour Calculates slope_per_second()/3600.
slope_per_minute Calculates slope_per_second()/60.
slope_per_second Calculates linear regression slope.
median_abs_dev Median absolute deviation.
stdev Standard deviation.
sum Sums all included values.
sumIf Sums elements matching the specified condition.
threshold_linear_time Forecasts the minutes until the value reaches the threshold based on linear extrapolation.
threshold_time Forecasts the minutes until the value reaches the threshold based on extrapolation of the difference between the last and first value.
variance Calculates variance.
wavg Calculates weighted average.
wtavg Calculates weighted time average.

Text

Name Description
abbreviate Truncates string using ellipses to hide extraneous text.
capFirst Capitalizes the first letter in the string.
capitalize Capitalizes the first letter in all words in the string.
coalesce Returns first non-empty string from the collection of strings.
concat Joins the elements of the collection into a single string.
concatLines Joins the elements of the collection into a single string with line breaks \n.
countMatches Counts how many times the substring appears in input string.
endsWith Returns true if string ends with the specified prefix.
htmlDecode Replaces HTML entities in string with their corresponding characters.
indexOf Returns the index of the first occurrence of substring in the target string.
jsonencode Escapes special JSON characters with a backslash.
keepAfter Removes part of string before the first occurrence of the given substring.
keepAfterLast Removes part of string before the last occurrence of the given substring.
keepBefore Removes part of string after the first occurrence of the given substring.
keepBeforeLast Removes part of string after the last occurrence of the given substring.
length Returns the length of string.
list Splits string into an array, discards duplicate items.
locate Returns the index of the first occurrence of substring in the target string.
lower Converts string to lowercase letters.
removeBeginning Removes substring from the beginning of the given string.
removeEnding Removes given substring from the end of the target string.
replace Replaces all occurrences of the 1-st string in the original string with the 2-nd string.
split Splits string into a collection of strings using the specified separator.
startsWith Returns true if string starts with the specified prefix.
trim Removes leading and trailing non-printable characters.
truncate Truncates string to the specified number of characters.
unquote Removes leading and trailing quotation marks from input string.
upper Converts string to uppercase letters.
urlencode Replaces special characters with URL-safe characters using percent-encoding.

Utility

Name Description
cancelAction Cancel the current action based on a condition.
getURLHost Retrieves the host from URL specified in string url.
getURLPath Retrieves the path from URL string.
getURLPort Retrieves the port from URL string.
getURLProtocol Retrieves the protocol from URL string.
getURLQuery Retrieves the query string from URL string.
getURLUserInfo Retrieves the user credential part username:password from URL string.
ifEmpty Returns the second string if the first is either null or an empty string.
printObject Prints the input object as a two-column table in the specified format.
samples Retrieves a map of the samples in the current window
values Retrieves a list of the values of the samples in the current window
timestamps Retrieves a list of the dates of the samples in the current window
toBoolean Converts the input string or number to a boolean value.
toNumber Converts the input object to floating-point number.
toLong Converts the input object to long number.
trim_zero Formats the number to decimal representation without exponent and trailing zeros.
check_range Checks the input number is within the minimum and maximum range.
agent_to_host Extract hostname from ITM agent name.
sendTcpMessage Sends TCP message to a remote server.
sendTcpMessageReply Sends TCP message to a remote server and read a reply.
sendUdpMessage Sends UDP message to a remote server.
sendUdpMessageReply Sends UDP message to a remote server and read a reply.
lock Acquire a named lock to prevent duplicate actions.
unlock Release a named lock that prevents duplicate actions.

Value

Name Description
value Retrieves value for the metric in the same series command.

Web Query

Name Description
queryConfig Executes an HTTP request using a predefined outgoing webhook.
queryGet Executes a GET request to the specified request URL.
queryPost Executes a POST request to the specified request URL.