Rule templates reference
COMMERCIAL FEATURE: Access business service monitoring (BSM), including rule templates, in the packaged Sensu Go distribution. For more information, read Get started with commercial features.
NOTE: Business service monitoring (BSM) is in public preview and is subject to change.
Rule templates are the resources that Sensu applies to service components for business service monitoring (BSM). A rule template applies to selections of events defined by a service component’s query. This selection of events is the rule’s input.
The rule template evaluates the selection of events using an ECMAScript 5 (JavaScript) expression specified in the rule template’s eval
object and emits a single event based on this evaluation.
For example, a rule template’s expression might define the thresholds at which Sensu will consider a service component online, degraded, or offline:
- Online until fewer than 70% of the service component’s events have a check status of OK.
- Degraded while 50-69% of the service component’s events have a check status of OK.
- Offline when fewer than 50% of the service component’s events have a check status of OK.
The rule template expression can also create arbitrary events.
Built-in rule template: Aggregate
Sensu includes a built-in rule template, aggregate
, that allows you to treat the results of multiple disparate check executions executed across multiple disparate systems as a single result (event).
This built-in rule template is ready to use with your service components.
Reference the rule template name in the rules.template
field and configure the arguments in the rules.template.arguments
object in your service component resource definitions.
Use the aggregate
rule template for services that can be considered healthy as long as a minimum threshold is satisfied.
For example, you might set the minimum threshold at 10 web servers with an OK status or 70% of processes running with an OK status.
The aggregate
rule template is useful in dynamic environments and environments with some tolerance for failure.
To review the aggregate
resource definition, retrieve it with a GET request to /enterprise/bsm/v1:
curl -X GET \
http://127.0.0.1:8080/api/enterprise/bsm/v1/namespaces/default/rule-templates/aggregate \
-H "Authorization: Key $SENSU_API_KEY"
The response will include the complete aggregate
rule template resource definition in JSON format:
{
"type": "RuleTemplate",
"api_version": "bsm/v1",
"metadata": {
"name": "aggregate"
},
"spec": {
"arguments": {
"properties": {
"critical_count": {
"description": "create an event with a critical status if there the number of critical events is equal to or greater than this count",
"type": "number"
},
"critical_threshold": {
"description": "create an event with a critical status if the percentage of non-zero events is equal to or greater than this threshold",
"type": "number"
},
"metric_handlers": {
"default": {},
"description": "metric handlers to use for produced metrics",
"items": {
"type": "string"
},
"type": "array"
},
"produce_metrics": {
"default": {},
"description": "produce metrics from aggregate data and include them in the produced event",
"type": "boolean"
},
"set_metric_annotations": {
"default": {},
"description": "annotate the produced event with metric annotations",
"type": "boolean"
},
"warning_count": {
"description": "create an event with a warning status if there the number of critical events is equal to or greater than this count",
"type": "number"
},
"warning_threshold": {
"description": "create an event with a warning status if the percentage of non-zero events is equal to or greater than this threshold",
"type": "number"
}
},
"required": null
},
"description": "Monitor a distributed service - aggregate one or more events into a single event. This BSM rule template allows you to treat the results of multiple disparate check executions – executed across multiple disparate systems – as a single event. This template is extremely useful in dynamic environments and/or environments that have a reasonable tolerance for failure. Use this template when a service can be considered healthy as long as a minimum threshold is satisfied (for example, at least 5 healthy web servers? at least 70% of N processes healthy?).",
"eval": "\nif (events && events.length == 0) {\n event.check.output = \"WARNING: No events selected for aggregate\n\";\n event.check.status = 1;\n return event;\n}\n\nevent.annotations[\"io.sensu.bsm.selected_event_count\"] = events.length;\n\npercentOK = sensu.PercentageBySeverity(\"ok\");\n\nif (!!args[\"produce_metrics\"]) {\n var handlers = [];\n\n if (!!args[\"metric_handlers\"]) {\n handlers = args[\"metric_handlers\"].slice();\n }\n\n var ts = Math.floor(new Date().getTime() / 1000);\n\n event.timestamp = ts;\n\n var tags = [\n {\n name: \"service\",\n value: event.entity.name\n },\n {\n name: \"entity\",\n value: event.entity.name\n },\n {\n name: \"check\",\n value: event.check.name\n }\n ];\n\n event.metrics = sensu.NewMetrics({\n handlers: handlers,\n points: [\n {\n name: \"percent_non_zero\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"percent_ok\",\n timestamp: ts,\n value: percentOK,\n tags: tags\n },\n {\n name: \"percent_warning\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"percent_critical\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"percent_unknown\",\n timestamp: ts,\n value: sensu.PercentageBySeverity(\"unknown\"),\n tags: tags\n },\n {\n name: \"count_non_zero\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"non-zero\"),\n tags: tags\n },\n {\n name: \"count_ok\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"ok\"),\n tags: tags\n },\n {\n name: \"count_warning\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"warning\"),\n tags: tags\n },\n {\n name: \"count_critical\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"critical\"),\n tags: tags\n },\n {\n name: \"count_unknown\",\n timestamp: ts,\n value: sensu.CountBySeverity(\"unknown\"),\n tags: tags\n }\n ]\n });\n\n if (!!args[\"set_metric_annotations\"]) {\n var i = 0;\n\n while(i < event.metrics.points.length) {\n event.annotations[\"io.sensu.bsm.selected_event_\" + event.metrics.points[i].name] = event.metrics.points[i].value.toString();\n i++;\n }\n }\n}\n\nif (!!args[\"critical_threshold\"] && percentOK <= args[\"critical_threshold\"]) {\n event.check.output = \"CRITICAL: Less than \" + args[\"critical_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 2;\n return event;\n}\n\nif (!!args[\"warning_threshold\"] && percentOK <= args[\"warning_threshold\"]) {\n event.check.output = \"WARNING: Less than \" + args[\"warning_threshold\"].toString() + \"% of selected events are OK (\" + percentOK.toString() + \"%)\n\";\n event.check.status = 1;\n return event;\n}\n\nif (!!args[\"critical_count\"]) {\n crit = sensu.CountBySeverity(\"critical\");\n\n if (crit >= args[\"critical_count\"]) {\n event.check.output = \"CRITICAL: \" + args[\"critical_count\"].toString() + \" or more selected events are in a critical state (\" + crit.toString() + \")\n\";\n event.check.status = 2;\n return event;\n }\n}\n\nif (!!args[\"warning_count\"]) {\n warn = sensu.CountBySeverity(\"warning\");\n\n if (warn >= args[\"warning_count\"]) {\n event.check.output = \"WARNING: \" + args[\"warning_count\"].toString() + \" or more selected events are in a warning state (\" + warn.toString() + \")\n\";\n event.check.status = 1;\n return event;\n }\n}\n\nevent.check.output = \"Everything looks good (\" + percentOK.toString() + \"% OK)\";\nevent.check.status = 0;\n\nreturn event;\n"
}
}
The configuration for a service component that references the aggregate
rule template might look like this example:
---
type: ServiceComponent
api_version: bsm/v1
metadata:
name: webservers
spec:
services:
- website-services
interval: 60
query:
- type: fieldSelector
value: webserver in event.check.subscriptions
rules:
- template: aggregate
name: webservers_50-70
arguments:
critical_threshold: 70
warning_threshold: 50
handlers:
- slack
{
"type": "ServiceComponent",
"api_version": "bsm/v1",
"metadata": {
"name": "webservers"
},
"spec": {
"services": [
"website-services"
],
"interval": 60,
"query": [
{
"type": "fieldSelector",
"value": "webserver in event.check.subscriptions"
}
],
"rules": [
{
"template": "aggregate",
"name": "webservers_50-70",
"arguments": {
"critical_threshold": 70,
"warning_threshold": 50
}
}
],
"handlers": [
"slack"
]
}
}
Apply rule templates to service components
Rule templates are general, parameterized resources that can apply to one or more service components. To apply a rule template to a specific service component:
- List the rule template name in the service component’s
rules.template
field. - Specify the arguments the rule template requires in the service component’s
rules.template.arguments
object.
Several service components can use the same rule template with different argument values.
For example, a rule template might evaluate one argument, threshold_ok
, against the number of events with OK status, as represented by the following logic:
if numberEventsOK < threshold_ok {
emit warning event
}
You can specify a variety of thresholds as arguments in service component definitions that reference this rule template.
One service component might set a threshold_ok
value at 10; another service component might set the value at 50.
Both service components can make use of the same rule template at the threshold that makes sense for that component.
Service components can reference more than one rule template. Sensu evaluates each rule separately, and each rule produces its own event as output.
Rule template specification
Top-level attributes
api_version | |
---|---|
description | Top-level attribute that specifies the Sensu API group and version. For rule template configuration in this version of Sensu, the api_version should always be bsm/v1 . |
required | Required for rule template configuration in wrapped-json or yaml format. |
type | String |
example |
|
metadata | |
---|---|
description | Top-level collection of information about the rule template, including name , namespace , and created_by as well as custom labels and annotations . |
required | true |
type | Map of key-value pairs |
example |
|
spec | |
---|---|
description | Top-level map that includes the rule template configuration spec attributes. |
required | Required for rule template configuration in wrapped-json or yaml format. |
type | Map of key-value pairs |
example |
|
type | |
---|---|
description | Top-level attribute that specifies the resource type. For rule template configuration, the type should always be RuleTemplate . |
required | Required for rule template configuration in wrapped-json or yaml format. |
type | String |
example |
|
Metadata attributes
annotations | |
---|---|
description | Non-identifying metadata to include with observation event data that you can access with event filters. You can use annotations to add data that’s meaningful to people or external tools that interact with Sensu. In contrast to labels, you cannot use annotations in API response filtering, sensuctl response filtering, or web UI views. |
required | false |
type | Map of key-value pairs. Keys and values can be any valid UTF-8 string. |
default | null |
example |
|
created_by | |
---|---|
description | Username of the Sensu user who created the rule template or last updated the rule template. Sensu automatically populates the created_by field when the rule template is created or updated. |
required | false |
type | String |
example |
|
labels | |
---|---|
description | Custom attributes to include with observation event data that you can use for response and web UI view filtering. If you include labels in your event data, you can filter API responses, sensuctl responses, and web UI views based on them. In other words, labels allow you to create meaningful groupings for your data. Limit labels to metadata you need to use for response filtering. For complex, non-identifying metadata that you will not need to use in response filtering, use annotations rather than labels. |
required | false |
type | Map of key-value pairs. Keys can contain only letters, numbers, and underscores and must start with a letter. Values can be any valid UTF-8 string. |
default | null |
example |
|
name | |
---|---|
description | Name for the rule template that is used internally by Sensu. |
required | true |
type | String |
example |
|
namespace | |
---|---|
description | Sensu RBAC namespace that the rule template belongs to. |
required | true |
type | String |
example |
|
Spec attributes
arguments | |
---|---|
description | The rule template’s arguments using JSON Schema properties. |
required | true |
type | Map of key-value pairs |
example |
|
description | |
---|---|
description | Plain text description of the rule template’s behavior. |
required | true |
type | String |
example |
|
eval | |
---|---|
description | ECMAScript 5 (JavaScript) expression for the rule template to evaluate. |
required | true |
type | String |
example |
|
Arguments attributes
properties | |
---|---|
description | List of properties that define the argument’s behavior. In JSON Schema. |
required | true |
type | Array |
example |
|
required | |
---|---|
description | List of attributes the rule template argument requires. The listed attributes must be configured in the properties object. |
required | false |
type | Array |
example |
|