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 - Client managed Qlik Sense Enterprise on Windows
List of template fields available in alert messages for client-managed Qlik Sense Enterprise on Windows.
1.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
Email
Teams
Slack
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, but it can still be tricky to debug if you’re not aware of this.
The following template fields are available in alert messages.
Note that some fields are sometimes (often, even) 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
Successful 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.
✅
✅
✅
taskName
Name of reload task.
✅
✅
✅
appId
ID of Sense app.
✅
✅
✅
appName
Name of app.
✅
✅
✅
appDescription
Description of app.
✅
✅
✅
appFileSize
Size of app file (on disk).
✅
✅
✅
appLastSuccessfulReload
Date of last successful reload.
✅
✅
✅
appLastModifiedDate
Date/time of last modification of app.
✅
✅
✅
appLastModifiedByUserName
User who last modified the app.
✅
✅
✅
appPublishTime
Date/time when app was published.
✅
✅
✅
appPublished
Is the app published? (true/false)
✅
✅
✅
appStreamName
Name of stream where app is published.
✅
✅
✅
appCustomProperties
Custom properties that are present on the app.
✅
✅
✅
appTags
Tags that are present on the app.
✅
✅
✅
appUrl
URL to the app.
✅
✅
✅
taskCustomProperties
Custom properties that are present on the reload task.
✅
✅
✅
taskTags
Tags that are present on the reload task.
✅
✅
✅
taskIsPartialReload
Does the reload task perform a partial reload? (true/false)
✅
✅
✅
taskMaxRetries
Maximum number of retries for the reload task.
✅
✅
✅
taskModifiedByUsername
User who last modified the reload task.
✅
✅
✅
taskModifiedDate
Date when the reload task was last modified.
✅
✅
✅
taskSessionTimeout
Session timeout for the reload task, i.e how long the reload task will run before it is cancelled.
✅
✅
✅
taskNextExecution
Next scheduled execution of the reload task.
✅
✅
✅
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
✅
✅
✅
scriptLogSize
Size of the reload’s script log (characters)
✅
✅
✅
scriptLogSizeRows
Size of the reload’s script log (rows)
✅
✅
✅
scriptLogSizeCharacters
Size of the reload’s script log (characters)
✅
✅
✅
scriptLogHeadCount
Number of lines extracted from the start of the script log
✅
✅
✅
scriptLogTailCount
The first y lines from the reload’s 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
✅
✅
✅
qliksSenseQMC
Links to QMC, as defined in main config file
✅
✅
✅
qliksSenseHub
Links to Hub, as defined in main config file
✅
✅
✅
genericUrls
Links to other systems, as defined in main config file
1.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
Tags
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
2 - Qlik Sense Cloud
List of template fields available in alert messages for Qlik Sense Cloud.
2.1 - Alert template fields for failed app reloads
List of template fields available in Butler’s failed app reload 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.
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, but it can still be tricky to debug if you’re not aware of this.
The following template fields are available in alert messages.
Failed app reload
Field name
Description
✅
tenantId
ID of the tenant where the reload took place.
✅
tenantComment
Comment for the tenant, as entered in Qlik Cloud.
✅
tenantUrl
URL to the tenant.
✅
userId
ID of the user who triggered the reload.
✅
userName
Name of the user who triggered the reload.
✅
appId
ID of Sense app.
✅
appName
Name of app.
✅
appDescription
Description of app.
✅
appUrl
URL to the app.
✅
appHasSectionAccess
Does the app have section access? (true/false)
✅
appIsPublished
Is the app published? (true/false)
✅
appPublishTime
Date/time when app was published.
✅
appThumbnail
URL to the app thumbnail.
✅
appOwnerName
Name of app owner.
✅
appOwnerUserId
App owner user’s user id.
✅
appOwnerPicture
URL to the app owner’s profile picture.
✅
appOwnerEmail
App owner email.
✅
reloadTrigger
What triggered the reload? Manually, scheduled etc.
✅
source
Source of the reload. Usually com.qlik/engine
✅
eventType
Type of QS Cloud event. For example com.qlik.v1.app.reload.finished
✅
eventTypeVersion
Version of the event type.
✅
endedWithMemoryConstraint
Did the reload end due to a memory constraint? (true/false)
✅
isDirectQueryMode
Is the app in Direct Query mode? (true/false)
✅
isPartialReload
Was the reload a partial reload? (true/false)
✅
isSessionApp
Is the app a session app? (true/false)
✅
isSkipStore
Should storing (to disk) the reloaded app be skipped? (true/false)
✅
reloadId
ID of the reload.
✅
rowLimit
Row limit for the reload.
✅
statements[]
Array of statements from the engine.
✅
status
Status of the reload. For example error.
✅
usageDuration
Duration of the reload.
✅
peakMemoryBytes
Peak memory usage during the reload.
✅
sizeMemoryBytes
Memory usage during the reload.
✅
appFileSize
Size of app file (on disk).
✅
errorCode
Error code for the reload. For example "EngineReloadScriptError".
✅
errorMessage
Error message for the reload. For example "error in app script or datasource".
✅
logMessage
Log message from the Sense log files. Example: "ReloadID: 670e1df04cf4e529c035c902\r\nStarted loading data\r\n(A detailed script progress log can be downloaded when the reload is finished)\r\nCharacters << AUTOGENERATE(26) 26 Lines fetched\r\nASCII << AUTOGENERATE(255) 191 Lines fetched\r\nTransactions << AUTOGENERATE(1000) 2,027 Lines fetched\r\n\r\nData has not been loaded. Please correct the error and try loading again.\r\nThe following error occurred:\r\nUnknown statement: ThisFailsForSure...\r\n \r\nThe engine error code: EDC_ERROR:11002\r\nThe error occurred here:\r\nThisFailsForSure...\r\n \r\n"
✅
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
✅
executionStatusText
Final reload task status message, for example FAILED.
✅
scriptLogSize
Size of the reload’s script log (characters)
✅
scriptLogSizeRows
Size of the reload’s script log (rows)
✅
scriptLogSizeCharacters
Size of the reload’s script log (characters)
✅
scriptLogHeadCount
Number of lines extracted from the start of the script log
✅
scriptLogTailCount
The first y lines from the reload’s 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
✅
qliksSenseQMC
Links to QMC, as defined in main config file
✅
qliksSenseHub
Links to Hub, as defined in main config file
✅
genericUrls
Links to other systems, as defined in main config file