Template functions

This document contains the various template functions that can be used in the ingester configuration (manifest.yaml).

toFloat

This function is used to convert the passed in int64 value to a float64 value.

Example Usage

${toFloat 56}

renders as 56.0.

minus

This function is used to subtract a int64 value from another.

Example Usage

${minus 34 20}

renders as 14.

minusf

Similar to minus this used to subtract 2 float64 values.

Example Usage

${minusf 34 20}

renders as 14.0.

add

This function is used to add two int64 values.

Example Usage

${add 34 8}

renders as 42

httpGet

This function is used to call a HTTP URL.

Example Usage

${httpGet "https://httpbin.org/ip"}

renders as true

Why

This function was written because some systems that we integrate with requires a webhook validation step before that system can send alerts through the webhook. For example, AWS Cloudwatch sends a JSON payload when the user configures it with squadcast. This initial payload is not an alert event, rather this payload contains an SubscriptionConfirmation URL which had to be called. Once this is called, AWS will start sending any alerts if any.

Checkout AWS Configuration for more info.

concat

This function used to add/concatenate two strings.

Example Usage

${concat "Hello" " World!"}

renders as Hello World!

trim

This function is used to trim the spaces from the start and end of the passed string.

Example Usage

${trim "  Lots of me    "}

renders as Lots of me

unsnake

This function is used to replace all the underscores (_) wirh a single space each from the passed string.

Example Usage

${unsnake "hiss_hiss_hiss"}

renders as hiss hiss hiss

capitalize

This function capitalizes the first letter of the passed string.

Example Usage

${capitalize "hello World!!"}

renders as Hello World!!

toLower

This function is used to convert the passed string to lower case.

Example Usage

${toLower "DON'T SHOUT!!"}

renders as don't shout!!

jsonParse

This function is used to parse the passed JSON string and return the Go's notation of the JSON object.

If the passed string contains a JSON Object at the root level, then a map[string]interface{} is returned. If array is at the root level, []interface{} is returned. This inturn can be used inside the template as well.

Example Usage

${jsonParse "{\"name\" : \"John Doe\"}"}

Generally this is used as value with with the subsequent templates can be formed. This should not be rendered directly else will yield unfavourable/unreadable results.

Why

AWS Cloudwatch sends JSON object as a serialized string in it's alerts instead of a nested JSON Object. So we have to parse that string to get the field values inside the JSON string.

Checkout AWS Cloudwatch configuration and Sample AWS Cloudwatch payload for more.

toJSON

This function is used to convert the passed template variable into the JSON representation.

Example Usage

This function is only used internally to get the array selector from the incoming payload as a Go variable. This is not used in any of the alert source configurations so far.

${toJSON $ages}

Assuming $ages is a variable which contains a map of names to ages, this renders as:

{"John":28,"Eve":30,"Mary":27}

toYAML

This function is used to convert the passed template variable into the YAML representation.

Example Usage

This function is used to display nested JSON data since YAML makes it more readable

${toYAML $stats}

Assuming $stats is the following JSON

{"name":"john", "details": {"height": 176,"weight": 65}}

the output of toYAML:

name: john
details:
  height: 176
  weight: 65

toInt

This function is used convert the passed string to int64 (Base 10). If the passed string cannot be parsed into integer, then 0 is returned.

Example Usage

${toInt "121231"}

renders as 121231. It is same for rendering the string and the int version. This is mostly used to perform calculations like minus, add etc.,

typeOf

This is a debug function which is used to print the type of the passed variable. It returns 0 no matter what.

Example Usage

${typeOf 45}

renders as 0 but Type of 45 is int will be printed in the stdout of ingester. This is merely a debug helper function. Should not be used for production alert source configurations.

str

This function is used to sprint any passed arguments.

Example Usage

${str $ages}

Assuming similar example as toJSON, this will render as map[John:28 Eve:30 Mary:27]. This should be used only for debugging purposes.

strf

This function is similar to sprintf where the arguments are formatted into a string based on a passed format.

Example Usage

${strf "%X" 30}

renders as 1E.

ftoi

This function is used to convert the passed float64 to int64.

Example Usage

${ftoi 45.0}

renders as 45. When a JSON data is unmarshalled using a generic data type interface{}, the underlying type becomes map[string]interface{} / []interface{}. And the string values are stored as string, true/false as booleans, numbers as float64 even though it might have been an int64. Go prints the float64 representation as exponential format like 2.124987e6 which when converted to int64 gets formatted right.

showIf

This function is used to render a line with a variable, only if the passed variable is not nil.

Example Usage

${ showIf "Agent" $root.agent_name -}

(assuming $root.agent_name is falcon)

This renders the string

Agent: falcon

if the passed payload has a field named agent_name. If the passed payload doesn't have a agent_name, then this line not rendered. Be sure add a - in the end of the template closer, to remove any empty lines in the rendered content.

timestampToString

This function is used to convert unix timestamp to RFC1123 format.

Example Usage

${timestampToString $root.data.item.last_activated_timestamp}

renders as Mon, 01 Jun 2020 16:42:03 IST.

convertTimestamp

This function is used to convert timestamp from one format to another.

Example Usage

${convertTimestamp "2021-07-30T12:56:23Z05:30" "2006-01-02T15:04:05Z07:00" "Mon, 02 Jan 2006 15:04:05 -0700"}

renders as Fri, 30 Jul 2021 12:56:23 +0530.

html2markdown

This function is used to convert html to markdown.

Example Usage

${$d := html2markdown "<h1>Html to markdown</h1>"}

renders as #Html to markdown.

reNamedMatches

This function is used to extract out the named matches from a string using a regex.

Example Usage

${with $matches := (reNamedMatches "^(?P<user>[a-z]+)@.*$" "[email protected]")}
Username: ${$matches.user}
${end}

yields :

User: example

reverse

This function is used to reverse the passed arbitrary array ([]interface{}).

Example Usage

Say the payload is

{
  "matches" : ["John", "Eve", "Bob"]
}

the following template

${with $rev := (reverse $root.matches)}
 + ${$rev}
${end}

should yield

+ Bob
+ Eve
+ John

divide

This function is used to 2 floats and yield a float. (all float64s)

Example Usage

${divide 840 2}

toJSONIndent

This function is similar to toJSON, but adds an indentation spaces (4 spaces) at every level to the JSON output.

Example Usage

Say the $pl variable in the template is a Go map.

"instance-id" : "i-1239hd9"
"state" : "running"

${toJSONIndent $pl}

should yield

{
    "instance-id": "i-1239hd9",
    "state": "running"
}

dehtml

This template function is used to convert the HTML escape sequence in a string and return the resulting string. This is used in Kapacitor alert source definition where the alert details are sent in a HTML escaped JSON string (for some reason).

Example Usage

Say $h is a variable that contains a HTML escaped string, with the following content:

{"Name":"mem"}

${dehtml $h}

should yield

{"Name":"mem"}

join

This template function is used to join string values with a passed string as the seperator.

Example Usage

Say $hosts has the following value. (in JSON)

[
  "ingester-586d87769c-bh26t",
  "ingester-586d87769c-n22bh",
  "ingester-586d87769c-tfdd6",
  "ingester-586d87769c-tkkjb"
]

${join $hosts ", "}

should yield

ingester-586d87769c-bh26t, ingester-586d87769c-n22bh, ingester-586d87769c-tfdd6, ingester-586d87769c-tkkjb

replace

This template function is used to replace a specific string from the input string with another string.

Example Usage

${replace "Banana" "na" "s"}

should yield Bass

urlQueryEscape

This template function is used to escape a passed in string so that it can be used in the query part of the string.

Example Usage

${urlQueryEscape "This is a testing query value"}

should yield This+is+a+testing+query+value

emptyStringIfNil

This template function returns an empty string if a nil value is passed. This is used as a null alternative when the payloads can contain null values, as handling empty string is safer than null.

Example Usage

Consider this payload

{
  "name" : "Bob"
}

${emptyStringIfNil $root.age}

will yield "" (nothing will be rendered).

hasPrefix

This template function is used to check if the passed string contains the prefix passed.

Example Usage

Consider this payload

{
  "name" : "Bob Saget"
}

${hasPrefix $root.name "Bob"}

will yield true.

${hasPrefix $root.name "John"}

will yield false.

reReplace

This template function is used to replace the substrings of the parent string which matches the passed regular expression with the replacement string.

Example Usage

${reReplace "Banana" "n." "l"}

will yield Ball.

repeat

This template function is used to repeat a specific string n times.

Example Usage

${repeat "Na" 5}

will yield NaNaNaNaNa.

split

This template function is used to split a string into multiple substrings by the passed separator string.

Example Usage

${split "Banana" "n"}

will yield an Array [Ba,a,a].

trimPrefix

This template function is used to trim any prefix from the original string.

Example Usage

${trimPrefix "Banana" "Ba"}

will yield nana.