# 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.

# Links

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.

# 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

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.