Message Templates and Variables

Security Requirements and Controls

  • Create actions permission

  • Update actions permission

LogScale's message templates enable customized notifications across multiple action types including Email, OpsGenie, PagerDuty, Slack, VictorOps, and Webhooks through a simple search/replace model using placeholders. The system supports various placeholders for fields, timestamps, IDs, and query details, with the ability to format messages using HTML tags for enhanced readability in supported clients.

LogScale uses message templates to create the messages sent by actions. They currently apply to Action Type: Email, Action Type: OpsGenie, Action Type: PagerDuty, Action Type: Slack, Action Type: VictorOps (Splunk On-Call) and Action Type: Webhooks. The template engine is a simple "search/replace" model, where the {_} marked placeholders are replaced with context-aware variables.

The following table provides an explanation of the placeholders:

Placeholders Description
{field:FIELD_NAME} Extracts the value of FIELD_NAME from the field in the first event from the trigger. Put field names with spaces in double quotes, {field:"My Field"}.
{field_raw:FIELD_NAME} Extracts the value of FIELD_NAME from the field in the first event from the trigger without JSON escaping it. Put field names with spaces in double quotes, {field_raw:"My Field"}.
{name}, {alert_name} The user-made name of the trigger.
{description}, {alert_description} A user-made description of the trigger.
{triggered_timestamp}, {alert_triggered_timestamp}

Vary based on trigger type:

  • Legacy and Aggregate alerts: the end time of the search interval at which the alert was triggered

  • Filter Alerts: the @ingesttimestamp of the event on which the alert was triggered

  • Scheduled searches: the planned execution time

Time is formatted as ISO 8601.

{id}, {alert_id} The ID of the trigger.
{action_id}, {alert_notifier_id} The ID of the Action used to deliver this message.
{action_invocation_id} Unique ID for the invocation of the action, which can be correlated with the activity logs.
{event_count} The number of events from the trigger.
{url} A URL to open LogScale with the trigger's query.
{query_result_summary} {events_str} Events encoded as a string.
{query_string} The query of the trigger.
{query_start_s} The actual query start time as Unix Time in seconds with 3 decimals.
{query_end_s}

The actual query end time as Unix Time in seconds with 3 decimals.

{query_time_start} The specified query start time (such as 10m).
{query_time_end} The specified query end time (such as now ).
{query_time_interval} The specified time interval for the trigger's query (such as 10m -> now).
{query_start_ms} The actual query start time as Unix Time in milliseconds.
{query_end_ms} The actual query end time as Unix Time in milliseconds.
{query_start_datetime} The actual query start time formatted as ISO 8601.
{query_end_datetime} The actual query end time formatted as ISO 8601.
{warnings} Any warnings that were generated by the query.
{repo_name} The name of the repository in which the query was executed.
{events} Events encoded as a JSON array of event objects.
{events_html} Events encoded as an HTML table inside <table> tags. All fields from all events are shown as columns. The columns are ordered by the order the fields are encountered, starting with the fields from the first event. If you want fewer fields, in Standard Alerts or Scheduled Search queries you can remove them using functions such as table(), select() or drop(). You can also specify the order of the fields using table() or select() functions. in Filter Alert queries you cannot use table()); @id and @ingesttimestamp fields cannot be removed.
{schedule} The cron schedule which the triggering search was executed according to. Only applicable when triggered by Scheduled searches.
{time_zone} The time zone that the triggering search is performed within. Only applicable when triggered by Scheduled searches.
{trigger_type} Can either be Standard Alert, Filter Alert, or Scheduled Search depending on which triggered the action.

Some placeholders such as {alert_id} and {id} evaluate to the same value.

Note

For placeholders which evaluate to some formatted version of the query result, like {query_result_summary}, {events_str}, {events} and {events_html}, you will by default receive a maximum of 200 events. This maximum is also applied to {event_count}. If you want a larger part of the query result in your message, you can append your query with | tail(x), where x is the number of events you wish to receive. You can also use {url} to include a link to run the search in LogScale, where it is possible to view the full query result.

It is also possible to use these placeholders in the name and description fields of your trigger. This is useful if you want to use the same action for multiple triggers, and you want different templates for the different triggers. As an example, you can use different {field:FIELD_NAME} placeholders in the name for the triggers to extract the value of different fields, and then use {name}/{alert_name} in the action to get the trigger names with the placeholders replaced.

You can also use this feature to save yourself from having to write near-identical triggers if you use an action where you cannot specify the message template, which currently apply to the actions Action Type: OpsGenie, Action Type: PagerDuty and Action Type: VictorOps (Splunk On-Call). These actions all use the trigger name as part of the message. Also, the default email subject and email template for the Action Type: Email action uses the trigger name.

Note

The {field:FIELD_NAME} placeholder will only extract the value of the field from the first event from the trigger.

Formatting Messages

Messages can be formatted within the message template using HTML tags. This is especially helpful when building email messages where clients are capable of receiving and displaying HTML content in its formatted form.

Without using HTML, messages can be displayed as a single line of information. For example, the template: 

Summary: LogScale inbound robust alert ticket demo

Full alert description:
    Timestamp: {triggered_timestamp}
    Repository: {repo_name}
    Alert name: {name}
    Description: {description}
    Alert link: {url}

Even though the source material has newlines, in an email client this may be displayed as a single line: 

Summary: LogScale inbound robust alert ticket demo  Full alert description:     Timestamp: {triggered_timestamp}     Repository: {repo_name}     Alert name: {name}     Description: {description}     Alert link: {url}

To convert to HTML, set the Message body template to the following HTML alternative: 

<html>
<body>
<h2>Summary: LogScale inbound robust alert ticket demo </h3>
<h3>Full alert description: </h3>
<p>
Timestamp: {triggered_timestamp} <br>
Repository: {repo_name} <br>
Alert name: {name} <br>
Description: {description} <br>
Alert link: <a href="{url}">LogScale Alert Link</a> <br>
</p>
</body>
</html>

The paragraph and manual line breaks that use <br> will be honored.

The use of <br> as a manual line break will work in most message templates.