Skip to content

Message Templates

You can embed dynamic values within your alert messages using message templates. These templates allow you to include relevant data, such as an item's name or metric values, directly in the alert.

return DEBUG, "Memory usage of @item.name to high"

In this example, @item.name acts as a placeholder that will be replaced with the actual name of the item when the message is generated.

Escaping the @ Symbol

If you need to include a literal @ sign in your message that shouldn't be interpreted as the start of a variable, add an exclamation mark (!) immediately after it:

return DEBUG, "Use @! in message."  // Renders as: "Use @ in message."

Escaping the single and double quotes

It is possible to use single quotes in a double quote string, but sometimes you just want a double quote in a double quote string. In this case, you need to write two of them

return DEBUG, "Use ""Double quotes"" in a double quote string."
// Renders as: Use "Double quotes" in a double quote string.

Explicitly Ending a Variable Placeholder

Sometimes, characters immediately following a variable placeholder (like a period) can cause ambiguity. The system might incorrectly try to include that character as part of the variable name, leading to a template error.

return DEBUG, "Failed item: @item.name."

This would produce an error similar to:

template error: ambiguous `.` after `@item.name`; maybe you want to print the dot? use: @item.name!.

To resolve this, explicitly mark the end of the variable placeholder with an exclamation mark (!) before the punctuation:

return DEBUG, "Failed item: @item.name!."  // Renders as: "Failed item: my-item."

Notice that the ! used to terminate the variable does not appear in the final message.

Including a Literal Exclamation Mark After a Variable

If you genuinely want an exclamation mark to appear after a variable in your message, simply add two exclamation marks:

return DEBUG, "Failed item: @item.name!!"  // Renders as: "Failed item: my-item!"

Accessing Previous Item Values

You can reference values from the previous evaluation cycle using the pr`ev keyword. This is useful for comparing current and historical data:

return DEBUG, "Memory usage: @item.usage_memory (Previous: @prev.usage_memory)"
// Example output: "Memory usage: 76853248, Previous value: 63619072"

Formatted Values with fmt.

Raw metric values (like 76853248) might not be user-friendly. For better readability, use the fmt. prefix to display formatted values (e.g., human-readable sizes, percentages):

return DEBUG, "Memory usage: @fmt.item.usage_memory"
// Example output: "Memory usage: 73.29 MiB"

Multiline Messages

Messages are multiline by default. You can define them across multiple lines using a multiline string:

var.message = "
Memory usage: @fmt.item.usage_memory
Previous value: @fmt.prev.usage_memory
"

Note: Any leading or trailing whitespace (like the newline character at the start and end of the example above) will be automatically trimmed from the rendered message.

Listing All Items in a Message

You can iterate through and list all items directly within a message template. This is particularly useful when you want a single alert to provide a comprehensive overview of multiple items, rather than generating separate alerts for each.

It is even possible to list all items in a message. This can be especially useful if you want a single alert, but the message to contain all item.

var.message = "
All items:

#for @pod in @items:
- @pod.name : @pod.status
#end
"

case item.status != "Running":
    return DEBUG, var.message

When this alert is triggered, the var.message template will render a detailed list of items. For example, the output might look like this:

All items:

- forecast-0 : Running
- forecast-1 : Stopped
- hub-0 : Running
- hub-1 : Running
- hub-2 : Running
- hub-3 : Stopped
- notifications-0 : Running
- notifications-1 : Running

Available Message Placeholders

This table provides an overview of the most commonly used placeholders and their respective examples and descriptions.

Placeholder Example output Description
@asset.id 34567 The unique identifier for the asset.
@asset.name myhost.local The name of the asset.
@asset.string.<key> ... The asset property <key> containing a string value.
@asset.strings.<key> [..., ...] The asset property <key> containing a list of string values.
@asset.number.<key> [..., ...] The asset property <key> containing a list of string values.
@check.duration 4.05123 The duration of the current check in seconds (float).
@check.interval 300 The configured check interval in seconds (integer).
@check.local_datetime 2022-07-21 16:45:44+02:00 The timezone-aware local date and time of the current check result.
@check.prev.local_datetime 2022-07-21 16:40:43+02:00 The timezone-aware local date and time of the previous check result.
@check.prev.timestamp 1658253617 The Unix timestamp of the previous check result.
@check.prev.utc_datetime 2022-07-21 14:40:44+00:00 The UTC date and time of the previous check result.
@check.timestamp 1658253918 The Unix timestamp of the current check result.
@check.utc_datetime 2022-07-21 14:45:44+00:00 The UTC date and time of the current check result.
@container.id 12345 The unique identifier for the container.
@container.name Cesbit The name of the container.
@enodo.<metric>.diffps.upper 0.01234 The raw forecasted upper bound value, compared to the previous value per second.
@enodo.<metric>.upper 0.1234 The raw forecasted upper bound value from Enodo.
@fmt.enodo.<metric>.lower 99% The formatted forecasted lower bound value from Enodo.
@fmt.item.<metric> 123 MB The formatted value of the current item's metric (e.g., human-readable).
@fmt.other.<metric> 99% The formatted value of another item's metric.
@fmt.prev.<metric> 99% The formatted value of the item's metric from the previous check.
@hit 0 The number of items currently triggering an alert (0 or more).
@hour 0 The current hour (0-23).
@item.<metric> cpu1 The raw value of the current item's metric.
@minute 0 The current minute (0-59).
@new True True if the item is newly detected, False otherwise.
@other.<metric> 99.14525 The raw value of a metric from another item.
@prev.<metric> 99.14525 The raw value of the item's metric from the previous check result.
@ticks 0 The total number of times this specific alert has been triggered previously (0 or more).
@var.variable ... The value of a user-defined variable (see Variables in Expressions).
@weekday Monday The current day of the week (e.g., Monday, Tuesday).
#for @x in @items: ...#end ... Loops through all items (using raw values) (see Listing All Items in a Message).
#for @x in @fmt.items: ... #end ... Loops through all items, using formatted values within the loop (see Listing All Items in a Message).