Event handler functions
StackState Self-hosted v5.1.x
Last updated
StackState v5.1
StackState Self-hosted v5.1.x
Last updated
Event handlers listen to events generated within a view. When the configured event type is generated, the event handler function is run to send an or trigger an action in a system outside of StackState. For example, an event handler function could send an email or make a POST to a webhook URL. A number of default event handler functions are included out of the box with StackState, or you can create your own custom event handler functions.
Advanced StackState users can write their own custom event handler functions that react to state change events or problem events. Event handler functions can use the StackState HTTP script API or a plugin to send an event notification to a system outside of StackState. To add a custom event handler function:
In the StackState UI, go to Settings > Functions > Event Handler Functions.
Click ADD EVENT HANDLER FUNCTION.
Enter the required settings:
Name - A name to identify the event handler function.
Description - Optional. A description of the event handler function. This will be displayed on the page Settings > Functions > Event Handler Functions.
System parameters - predefined parameters that are passed automatically to the event handler function script. For details, see the section on below.
User parameters - parameters that must be entered by the user when an event handler is added to a view. Event handler functions also include the predefined user parameter event. For details, see the section on below.
Supported Event Types - The type of event(s) that the event handler can respond to. For details, see the section on below.
Execution - Event handler functions can be run as either Asynchronous (default) or Synchronous:
Asynchronous - use for Slack, SMS or HTTP webhook event handlers. The function script will have access to all functionality from the StackState script APIs and more functions will be allowed to run in parallel.
Synchronous - required for event handlers that generate email event notifications. The function will use a plugin to send notifications to external systems.
Script - The script run by the function. For details, see the sections below on:
.
.
How to .
Identifier - Optional. A unique identifier (URN) for the event handler function.
Click CREATE to save the event handler function.
The new event handler function will be listed on the page Settings > Functions > Event Handler Functions.
The event handler will be available in the Run event handler drop-down when you that listens to one of the configured Supported Event Types.
An event handler function includes predefined system and user parameters that are passed automatically to the event handler function script.
The view system parameter provides details of the view that the event handler has been added to.
The event user parameter provides the events that the event handler function will listen to.
You can also add your own user parameters, these can then be entered in the Add event handler dialogue when you add an event handler to a view.
One or more of the following events can be selected:
State change of entire view - For functions that will react to a ViewHealthStateChangedEvent. These events are generated when the health state of the entire view changes.
State change of an element - For functions that will react to a HealthStateChangedEvent. These events are generated when an element's own health state changes.
Propagated state change of an element - For functions that will react to a PropagatedHealthStateChangedEvent. These events are generated when the propagated health state of an element changes.
When execution is set to Asynchronous, the event handler function will run as an asynchronous function.
The Slack event handler function shipped with StackState will run as an asynchronous function. This allows the event notifications sent to Slack to include extensive details about the event that triggered it, such as links to relevant data and a possible root cause. You could also use the HTTP script API to send an SMS or webhook post.
The properties described below can be retrieved from the default view and event parameters in an event handler function with asynchronous execution.
View properties return details of the view that the event handler is configured for. Note that parameter name view or scope can be used, or an alias.
view.name - returns the view name.
view.description - returns the view description.
view.query - returns an STQL query of the view.
view.identifier - returns the globally unique URN value that identifies the view.
Event properties return details of a received event and vary for the different event types:
Health state change events:
Problem events:
The properties listed below return details of a HealthStateChangedEvent in functions with asynchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event.triggeredTimestamp - returns the time (epoch in ms) at which the state change occurred.
event.causeId - returns the UUID of the event that triggered the health state change.
event.newState - returns the current state of the element.
event.oldState - returns the previous state of the element.
event.stackElement - returns the node ID of the element that has changed its state.
The properties listed below return details of a ViewHealthStateChangedEvent in functions with asynchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event.triggeredTimestamp - returns the time (epoch in ms) at which the state change occurred.
event.causeId - returns the UUID of the event that triggered the health state change.
event.newState - returns the current state of the element.
event.oldState - returns the previous state of the element.
event.viewHealthState - returns the node ID of the health state object for the view that changed its state.
The properties listed below return details of a PropagatedHealthStateChangedEvent in functions with asynchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event.triggeredTimestamp - returns the time (epoch in ms) at which the state change occurred.
event.causeId - returns the UUID of the event that triggered the health state change.
event.stateChanges -returns the chain of elements through which the health state change propagated.
The properties listed below return details of a ProblemCreatedEvent in functions with asynchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event._type - returns the event type (ProblemCreatedEvent).
event.triggeredTimestamp - returns the time (epoch in ms) at which the event was generated.
event.identifier - returns the unique event identifier.
event.problemId - returns the (node) ID of the problem.
event.rootCause - returns the node ID of the root cause component.
event.nodes - returns the list of node IDs of all the components that were related to the problem when it was created.
The properties listed below return details of a ProblemUpdatedEvent in functions with asynchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event._type - returns the event type (ProblemUpdatedEvent).
event.triggeredTimestamp - returns the time (epoch in ms) at which the event was generated.
event.identifier - returns the unique event identifier.
event.problemId - returns the (node) ID of the problem.
event.rootCause - returns the node ID of the root cause component.
event.nodes - returns the list of node IDs of all the components that were related to the problem after it was updated.
The properties listed below return details of a ProblemSubsumedEvent in functions with asynchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event._type - returns the event type (ProblemSubsumedEvent).
event.triggeredTimestamp - returns the time (epoch in ms) at which the event was generated.
event.identifier - returns the unique event identifier.
event.problemId - returns the (node) ID of the problem.
event.rootCause - returns the node ID of the root cause component.
event.superProblemIds - returns the list of problem IDs that now contain the subsumed problem.
event.nodes - returns the list of node IDs of all the components that were related to the problem before it was subsumed.
The properties listed below return details of a ProblemResolvedEvent in functions with asynchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event._type - returns the event type (ProblemResolvedEvent).
event.triggeredTimestamp - returns the time (epoch in ms) at which the event was generated.
event.identifier - returns the unique event identifier.
event.problemId - returns the (node) ID of the problem.
event.rootCause - returns the node ID of the root cause component.
event.nodes - returns the list of node IDs of all the components that were related to the problem before it was resolved.
When execution is set to Synchronous, the event handler function will run as a synchronous function.
Event handler functions developed prior to StackState v4.2 and email event handler functions run as synchronous functions. Compared to asynchronous functions, synchronous functions are limited in both the capability of what they can achieve and the number of functions that can run in parallel.
The properties described below can be retrieved from the default synchronous event handler function parameters.
View properties return details of the view the event handler is in. Note that parameter name view or scope can be used, or an alias.
view.getName - returns the name of the view.
view.getDescription - returns the view description.
view.getQuery - returns an STQL query of the view.
view.getIdentifier - returns the globally unique URN value that identifies the view.
Event properties return details of a received event and vary for the different event types:
Health state change events:
Problem events:
The properties listed below return details of a HealthStateChangedEvent in functions with synchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event.getTriggeredTimestamp - returns the time (epoch in ms) at which the state change occurred.
event.getCauseId - returns the UUID of the event that triggered the health state change.
event.getNewStateRef - returns the current state of the element.
event.getOldStateRef - returns the previous state of the element.
The properties listed below return details of a ViewHealthStateChangedEvent in functions with synchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event.getTriggeredTimestamp - returns the time (epoch in ms) at which the state change occurred.
event.getCauseId - returns the UUID of the event that triggered the health state change.
event.getNewStateRef - returns the current state of the element.
event.getOldStateRef - returns the previous state of the element.
The properties listed below return details of a PropagatedHealthStateChangedEvent in functions with synchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event.getTriggeredTimestamp - returns the time (epoch in ms) at which the state change occurred.
event.getCauseId - returns the UUID of the event that triggered the health state change.
event.getStateChanges -returns the chain of elements through which the health state change propagated.
The properties listed below return details of a ProblemCreated event in functions with synchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event._type - returns the event type (ProblemCreated).
event.triggeredTimestamp - returns the time (epoch in ms) at which the event was generated.
event.identifier - returns the unique event identifier.
event.problemId - returns the (node) ID of the problem.
event.rootCauseNodeId - returns the node ID of the root cause component.
event.nodes - returns the list of node IDs of all the components that were related to the problem when it was created.
The properties listed below return details of a ProblemUpdated event in functions with synchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event._type - returns the event type (ProblemUpdated).
event.triggeredTimestamp - returns the time (epoch in ms) at which the event was generated.
event.identifier - returns the unique event identifier.
event.problemId - returns the (node) ID of the problem.
event.rootCauseNodeId - returns the node ID of the root cause component.
event.nodes - returns the list of node IDs of all the components that were related to the problem after it was updated.
The properties listed below return details of a ProblemSubsumed event in functions with synchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event._type - returns the event type (ProblemSubsumed).
event.triggeredTimestamp - returns the time (epoch in ms) at which the event was generated.
event.identifier - returns the unique event identifier.
event.problemId - returns the (node) ID of the problem.
event.rootCauseNodeId - returns the node ID of the root cause component.
event.superProblemIds - returns the list of problem IDs that now contain the subsumed problem.
event.nodes - returns the list of node IDs of all the components that were related to the problem before it was subsumed.
The properties listed below return details of a ProblemResolved event in functions with synchronous execution. Note that the default parameter name isevent, this can be modified if you choose.
event._type - returns the event type (ProblemResolved).
event.triggeredTimestamp - returns the time (epoch in ms) at which the event was generated.
event.identifier - returns the unique event identifier.
event.problemId - returns the (node) ID of the problem.
event.rootCauseNodeId - returns the node ID of the root cause component.
event.nodes - returns the list of node IDs of all the components that were related to the problem before it was resolved.
Synchronous event handler functions use plugins to send notifications to external systems. The following plugins are available for use in custom event handler functions:
HTTP webhook
Sends an HTTP POST request with the specified content to a URL. webhookPlugin.sendMessage(url, "json")
SMS
Sends an SMS using MessageBird with the specified token. smsPlugin.sendSMSMessage(token, "to", "message")
For details of the properties that can be retrieved from the default view and event parameters, see and below.
One or more supported event types can be added for each event handler function. The supported event types determine which event handler functions can be selected for each trigger event type when you to a view. For example, an event handler function with no supported event types won't be included in the Run event handler list of the Add event handler dialogue for any trigger event type.
Problem changed events - For functions that will react to ProblemCreated, ProblemUpdated, ProblemSubsumed or ProblemResolved. These events are generated for changes to in the view.
You can add logging statements to an event handler function for debug purposes, for example, with log.info("message"). Logs will appear in stackstate.log. Read how to .
An asynchronous event handler function has access to the . This allows the function to make an HTTP request with a custom header using the and gives access to the whole topology/telemetry.
Synchronous functions will be deprecated in a future release of StackState. It's advised to choose the type when writing a new event handler function.
Synchronous event handler functions use plugins to interact with external systems, see below for further details.
Sends an email using the . emailPlugin.sendEmail(to, subject, "body")
