This is the multi-page printable view of this section.
Click here to print.
Return to the regular view of this page.
Alert template fields
List of template fields available in Butler alert messages.
Template fields
Butler uses the Handlebars library for templating work.
Handlebars offers a lot of useful features (nested template fields, evaluation context, template comments) and it’s recommended that you browse through at least the language features section of their getting started guide to get a feeling for what’s possible.
Different Butler monitoring features offer different template fields.
For example, the template fields available for reload alerts are different from the ones available for monitoring Windows services.
1 - Alert template fields for failed/aborted reload tasks
List of template fields available in Butler’s reload failed/aborted alert messages.
Template fields
Butler uses the Handlebars library for templating work.
Handlebars offers a lot of useful features (nested template fields, evaluation context, template comments) and it’s recommended that you browse through at least the language features section of their getting started guide to get a feeling for what’s possible.
Warning
Only some alert destinations support template files, namely
Please see the Concepts and Getting started sections for more information about which alert types support templates.
If a template field is used for an alert type where that field is not supported, the field will simply be blank. No errors will occur.
The following template fields are available in alert messages.
Note that some fields are usually (always?) empty, for example the script log for stopped messages.
This is simply how Sense works - the template fields just forward the information retrieved from the Sense APIs.
Failed
reload |
Stopped
reload |
Field name |
Description |
| ✅ |
✅ |
hostName |
Server on which a reload or other event took place. |
| ✅ |
✅ |
user |
Reload failures: User ID for use doing the reload. Typically sa_scheduler.
Reload stopped: User ID of user stopping the reload. |
| ✅ |
✅ |
taskId |
ID of reload task that failed/was stopped. |
| ✅ |
✅ |
appName |
Name of Sense whose reload failed/was stopped. |
| ✅ |
✅ |
appId |
ID of Sense app whose reload failed/was stopped. |
| ✅ |
✅ |
appOwnerName |
Name of app owner (if this is available in the metadata provided by the Sense server) |
| ✅ |
✅ |
appOwnerUserDirectory |
App owner user’s user directory (if this is available in the metadata provided by the Sense server) |
| ✅ |
✅ |
appOwnerUserId |
App owner user’s user id (if this is available in the metadata provided by the Sense server) |
| ✅ |
✅ |
appOwnerEmail |
App owner email (if this is available in the metadata provided by the Sense server) |
| ✅ |
✅ |
logTimeStamp |
Timestamp as recorded in the Sense logs |
| ✅ |
✅ |
logLevel |
Log level of the Sense log file entry causing the alert |
| ✅ |
✅ |
logMessage |
Log message from the Sense log files |
| ✅ |
✅ |
executingNodeName |
Name of the server where the reload took place |
| ✅ |
✅ |
executionDuration.hours |
executionDuration is a JSON object.
Duration of reload (hours part) |
| ✅ |
✅ |
executionDuration.minutes |
Duration of reload (minutes part) |
| ✅ |
✅ |
executionDuration.seconds |
Duration of reload (seconds part) |
| ✅ |
✅ |
executionStartTime.startTimeUTC |
JSON object.
UTC timestamp for reload start |
| ✅ |
✅ |
executionStartTime.startTimeLocal1 |
Reload start timestamp, format 1 |
| ✅ |
✅ |
executionStartTime.startTimeLocal2 |
Reload start timestamp, format 2 |
| ✅ |
✅ |
executionStartTime.startTimeLocal3 |
Reload start timestamp, format 3 |
| ✅ |
✅ |
executionStartTime.startTimeLocal4 |
Reload start timestamp, format 4 |
| ✅ |
✅ |
executionStartTime.startTimeLocal5 |
Reload start timestamp, format 5 |
| ✅ |
✅ |
executionStopTime.stopTimeUTC |
JSON object.
UTC timestamp for reload end |
| ✅ |
✅ |
executionStopTime.stopTimeLocal1 |
Reload end timestamp, format 1 |
| ✅ |
✅ |
executionStopTime.stopTimeLocal2 |
Reload end timestamp, format 2 |
| ✅ |
✅ |
executionStopTime.stopTimeLocal3 |
Reload end timestamp, format 3 |
| ✅ |
✅ |
executionStopTime.stopTimeLocal4 |
Reload end timestamp, format 4 |
| ✅ |
✅ |
executionStopTime.stopTimeLocal5 |
Reload end timestamp, format 5 |
| ✅ |
✅ |
executionStatusNum |
Final reload task status code |
| ✅ |
✅ |
executionStatusText |
Final reload task status message |
| ✅ |
✅ |
executionDetails[].timestampUTC |
executionDetails is an array of status updates for the reload task, similar to the one found in the QMC’s task view.
UTC timestamp of the task status |
| ✅ |
✅ |
executionDetails[].timestampLocal1 |
Task status timestamp, format 1 |
| ✅ |
✅ |
executionDetails[].timestampLocal2 |
Task status timestamp, format 2 |
| ✅ |
✅ |
executionDetails[].timestampLocal3 |
Task status timestamp, format 3 |
| ✅ |
✅ |
executionDetails[].timestampLocal4 |
Task status timestamp, format 4 |
| ✅ |
✅ |
executionDetails[].timestampLocal5 |
Task status timestamp, format 5 |
| ✅ |
✅ |
executionDetails[].detailsType |
Task status timestamp, format 1 |
| ✅ |
✅ |
executionDetails[].message |
Task status message |
| ✅ |
✅ |
scriptLogHeadCount |
Number of lines extracted from the start of the script log |
| ✅ |
✅ |
scriptLogHead |
The first x lines from the reload’s script log |
| ✅ |
✅ |
scriptLogTail |
Number of lines extracted from the end of the script log |
| ✅ |
✅ |
scriptLogTailCount |
The first y lines from the reload’s script log |
| ✅ |
✅ |
qliksSenseQMC |
Links to QMC, as defined in main config file |
| ✅ |
✅ |
qliksSenseHub |
Links to Hub, as defined in main config file |
2 - Alert template fields for Windows services events
List of template fields available in Butler’s Windows services alert messages.
Email, Slack and Teams
Butler uses the Handlebars library for templating work.
This gives a lot of flexibility in how alert messages are formatted for the destination types that support template fields.
Handlebars offers a lot of useful features (nested template fields, evaluation context, template comments) and it’s recommended that you browse through at least the language features section of their getting started guide to get a feeling for what’s possible.
Warning
Not all alert destinations (MQTT, outgoing webhooks etc) support template fields.
Please see the Getting started sections for more information on how to set up alerts for each destination.
If a template field is used for an alert type where that field is not supported, the field will simply be blank. No errors will occur.
The following alert destinations support template fields:
The following template fields are available in alert messages.
Note that some fields are usually (always?) empty, for example the script log for stopped messages.
This is simply how Sense works - the template fields just forward the information retrieved from the Sense APIs.
| Email |
Slack |
Teams |
Field name |
Description |
| ✅ |
✅ |
✅ |
{{host}} |
The hostname of the server where the service is running |
| ✅ |
✅ |
✅ |
{{serviceStatus}} |
The status of the service, e.g. RUNNING or STOPPED |
| ✅ |
✅ |
✅ |
{{servicePrevStatus}} |
The previous status of the service, e.g. RUNNING or STOPPED |
| ✅ |
✅ |
✅ |
{{serviceName}} |
The name of the service as defined in Windows |
| ✅ |
✅ |
✅ |
{{serviceDisplayName}} |
The display name of the service as defined in Windows. Can sometimes be a bit more human readable than the serviceName. |
| ✅ |
✅ |
✅ |
{{serviceFriendlyName}} |
The display name of the service as defined in the Butler config file. Used to give the service a good name when both serviceName and serviceDisplayName are unsuitable for use in for example Grafana dashboards. |
| ✅ |
✅ |
✅ |
{{serviceStartType}} |
The startup mode of the service, e.g. Automatic or Manual |
| ✅ |
✅ |
✅ |
{{serviceExePath}} |
The path to the executable of the service |
InfluxDB
Window service data will be stored in the InfluxDB database specified in the config file Butler.influxdb.dbName setting.
The latest status of each service will be stored in the butler_windows_services measurement every time Butler checks the status of the service, i.e. not only when the service changes status.
Fields/metrics
The following metrics will be stored in a measurement named win_service_state, for each Windows service:
| Field name |
Description |
| state_num |
A numeric representation of the Windows service’s current state. |
| state_text |
The Windows service’s current state (textual representation). |
| startup_mode_num |
A numeric representation of the Windows service’s startup mode. |
| startup_mode_text |
The Windows service’s startup mode (textual representation). |
Mapping of state_num to state_text:
| state_num |
state_text |
| 1 |
STOPPED |
| 2 |
START_PENDING |
| 3 |
STOP_PENDING |
| 4 |
RUNNING |
| 5 |
CONTINUE_PENDING |
| 6 |
PAUSE_PENDING |
| 7 |
PAUSED |
Mapping of startup_mode_num to startup_mode_text:
| startup_mode_num |
startup_mode_text |
| 0 |
Automatic |
| 1 |
Automatic (delayed start) |
| 2 |
Manual |
| 3 |
Disabled |
The following tags will be attached to all Windows service data stored in InfluxDB:
| Tag name |
Description |
| butler_instance |
The value in Butler.influxDb.instanceTag. Can be used to differentiate several Butler instances running in parallel. |
| host |
Host name where the Windows service is running. Comes from Butler.serviceMonitor.monitor.<host>. |
| service_name |
The name of the Windows service, as defined in Windows. |
| service_display_name |
The display name of the Windows service, as defined in Windows. |
| service_friendly_name |
The friendly name of the Windows service, as defined in the Butler config file Butler.serviceMonitor.monitor.<host>.services.<friendlyName>. |
New Relic
Butler will create New Relic events and/or log entries when a monitored Windows service changes state, for example from RUNNING to STOPPED.
Events
Events sent to New Relic will have these attributes attached:
| Attribute name |
Description |
| eventType |
Always set to qs_serviceStateEvent |
| butler_serviceHost |
The host name where the Windows service is running. Comes from Butler.serviceMonitor.monitor.<host>. |
| butler_serviceName |
The name of the Windows service, as defined in Windows. |
| butler_serviceDisplayName |
The display name of the Windows service, as defined in Windows. |
| butler_serviceStatus |
The status of the Windows service, e.g. RUNNING or STOPPED. |
| … |
Any static and dynamic attributes defined in Butler.incidentTool.newRelic.serviceMonitor.destination.event.attribute. |
| … |
Any static attributes defined in Butler.incidentTool.newRelic.serviceMonitor.sharedSettings.attribute.static. |
Log entries
Log entries sent to New Relic will have these attributes attached:
| Attribute name |
Description |
| logType |
Always set to qs_serviceStateLog |
| butler_serviceHost |
The host name where the Windows service is running. Comes from Butler.serviceMonitor.monitor.<host>. |
| butler_serviceName |
The name of the Windows service, as defined in Windows. |
| butler_serviceDisplayName |
The display name of the Windows service, as defined in Windows. |
| butler_serviceStatus |
The status of the Windows service, e.g. RUNNING or STOPPED. |
| … |
Any static and dynamic attributes defined in Butler.incidentTool.newRelic.serviceMonitor.destination.log.attribute. |
| … |
Any static attributes defined in Butler.incidentTool.newRelic.serviceMonitor.sharedSettings.attribute.static. |
The log message will be one of the following:
- “Windows service on host is RUNNING.”
- “Windows service on host is STOPPED.”
- “Windows service on host is in state START_PENDING.”
- “Windows service on host is in state STOP_PENDING.”
- “Windows service on host is in state CONTINUE_PENDING.”
- “Windows service on host is in state PAUSE_PENDING.”
- “Windows service on host is in state PAUSED.”
MQTT
Similar to how InfluxDB works, Butler will send an MQTT message to the topic specified in Butler.mqttConfig.serviceStatusTopic every time it checks the status of a Windows service, i.e. not only when the service changes status.
Butler will ALSO send an MQTT message to the topics specified in Butler.mqttConfig.serviceRunningTopic and Butler.mqttConfig.serviceStoppedTopic when a Windows service is stopped or started.
Message payload for continuously sent messages is a JSON object with these properties:
| Property name |
Description |
| host |
The host name where the Windows service is running. Comes from Butler.serviceMonitor.monitor.<host>. |
| serviceName |
The name of the Windows service, as defined in Windows. |
| serviceFriendlyName |
The friendly name of the Windows service, as defined in the Butler config file Butler.serviceMonitor.monitor.<host>.services.<friendlyName>. |
| serviceStatus |
The status of the Windows service, e.g. RUNNING or STOPPED. |
| serviceDetails |
The details of the Windows service, e.g. RUNNING or STOPPED. |
Message payload for start/stop messages is a JSON object with these properties:
| Property name |
Description |
| host |
The host name where the Windows service is running. Comes from Butler.serviceMonitor.monitor.<host>. |
| serviceName |
The name of the Windows service, as defined in Windows. |
| serviceFriendlyName |
The friendly name of the Windows service, as defined in the Butler config file Butler.serviceMonitor.monitor.<host>.services.<friendlyName>. |
| serviceStatus |
The status of the Windows service, e.g. RUNNING or STOPPED. |
| serviceDetails |
The details of the Windows service, e.g. RUNNING or STOPPED. |
| prevState |
The previous state of the Windows service, e.g. RUNNING or STOPPED. |
| currState |
The current state of the Windows service, e.g. RUNNING or STOPPED. |
| stateChanged |
true if the Windows service changed state, false if not. |
Outbound webhooks
Outbound webhooks (=http calls) are sent when a Windows service changes state, for example from RUNNING to STOPPED.
The payload for PUT and POST http calls is sent in the message body as a JSON object with these properties:
| Property name |
Description |
| event |
Always set to Windows service monitor |
| host |
The host name where the Windows service is running. Comes from Butler.serviceMonitor.monitor.<host>. |
| serviceStatus |
The status of the Windows service, e.g. RUNNING or STOPPED. |
| serviceName |
The name of the Windows service, as defined in Windows. |
| serviceDisplayName |
The display name of the Windows service, as defined in Windows. |
| serviceStartType |
The startup mode of the service, e.g. Automatic or Manual |
| prevState |
The previous state of the Windows service, e.g. RUNNING or STOPPED. |
| currState |
The current state of the Windows service, e.g. RUNNING or STOPPED. |
| stateChanged |
true if the Windows service changed state, false if not. |
The payload for GET http calls is sent as query parameters with the same properties as above, but with the property names being all lowercase letters.
A typical GET webhook URL would look like this:
https://mywebhookserver.com?event=Windows service monitor&host=MyHost&servicestatus=RUNNING&servicename=MyService&servicedisplayname=MyServiceDisplayName&servicestarttype=Automatic&prevstate=RUNNING&currstate=STOPPED&statechanged=true