Service components reference

COMMERCIAL FEATURE: Access business service monitoring (BSM), including service components, 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.

Service components are resources for defining and managing elements of a business service in business service monitoring. A service entity consists of a number of underlying service components. A service component is a meaningful selection of Sensu events for a business service, such as database monitoring events.

A service component includes event selectors to define the events that the component includes, a service component scheduler (either an interval or cron expression), and references to at least one monitoring rule template with arguments. The monitoring rules are evaluated against aggregate data derived from the service component’s selection of events. Monitoring rules are configured in a separate resource: rule templates.

If you delete a resource (for example, an entity, check, or event) that is part of one or more service components, Sensu will automatically remove the deleted resource from the service components.

Service component example

The example service component below is a dependency of the business service entity website-services. Sensu will execute the component at 60-second intervals for website-services service entities whose events include the webserver subscription. The monitoring rule template for the service component is aggregate.

---
type: ServiceComponent
api_version: bsm/v1
metadata:
  name: webservers
spec:
  handlers:
  - slack
  interval: 60
  query:
  - type: fieldSelector
    value: webserver in event.check.subscriptions
  rules:
  - arguments:
      critical_threshold: 70
      warning_threshold: 50
    name: webservers_50-70
    template: aggregate
  services:
  - website-services
{
  "type": "ServiceComponent",
  "api_version": "bsm/v1",
  "metadata": {
    "name": "webservers"
  },
  "spec": {
    "handlers": [
      "slack"
    ],
    "interval": 60,
    "query": [
      {
        "type": "fieldSelector",
        "value": "webserver in event.check.subscriptions"
      }
    ],
    "rules": [
      {
        "arguments": {
          "critical_threshold": 70,
          "warning_threshold": 50
        },
        "name": "webservers_50-70",
        "template": "aggregate"
      }
    ],
    "services": [
      "website-services"
    ]
  }
}

Service component scheduling

Sensu executes service components on sensu-backend processes in a round-robin fashion and according to a schedule specified by an interval or a cron expression in the component definition. During each execution of the service component, Sensu retrieves the events identified in the component’s query expression and processes these events according to the monitoring rules specified in the service component definition. The rules can emit new events based on the component input.

Service component specification

Top-level attributes

api_version
description Top-level attribute that specifies the Sensu API group and version. For service component configuration in this version of Sensu, the api_version should always be bsm/v1.
required Required for service component configuration in wrapped-json or yaml format.
type String
example 
api_version: bsm/v1
{
  "api_version": "bsm/v1"
}
metadata
description Top-level collection of information about the service component, including name, namespace, and created_by as well as custom labels and annotations.
required true
type Map of key-value pairs
example 
metadata:
  name: webservers
  namespace: default
  created_by: admin
  labels:
    region: us-west-1
  annotations:
    managed_by: ops
{
  "metadata": {
    "name": "webservers",
    "namespace": "default",
    "created_by": "admin",
    "labels": {
      "region": "us-west-1"
    },
    "annotations": {
      "managed_by": "ops"
    }
  }
}
spec
description Top-level map that includes the service component configuration spec attributes.
required Required for service component configuration in wrapped-json or yaml format.
type Map of key-value pairs
example 
spec:
  handlers:
  - slack
  interval: 60
  query:
  - type: fieldSelector
    value: webserver in event.check.subscriptions
  rules:
  - arguments:
      critical_threshold: 70
      warning_threshold: 50
    name: webservers_50-70
    template: aggregate
  services:
  - website-services
{
  "spec": {
    "handlers": [
      "slack"
    ],
    "interval": 60,
    "query": [
      {
        "type": "fieldSelector",
        "value": "webserver in event.check.subscriptions"
      }
    ],
    "rules": [
      {
        "arguments": {
          "critical_threshold": 70,
          "warning_threshold": 50
        },
        "name": "webservers_50-70",
        "template": "aggregate"
      }
    ],
    "services": [
      "website-services"
    ]
  }
}
type
description Top-level attribute that specifies the resource type. For service component configuration, the type should always be ServiceComponent.
required Required for service component configuration in wrapped-json or yaml format.
type String
example 
type: ServiceComponent
{
  "type": "ServiceComponent"
}

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 
annotations:
  managed-by: ops
{
  "annotations": {
    "managed-by": "ops"
  }
}
created_by
description Username of the Sensu user who created or last updated the service component. Sensu automatically populates the created_by field when the service component is created or updated.
required false
type String
example 
created_by: admin
{
  "created_by": "admin"
}
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 
labels:
  region: us-west-1
{
  "labels": {
    "region": "us-west-1"
  }
}
name
description Name for the service component that is used internally by Sensu.
required true
type String
example 
name: webservers
{
  "name": "webservers"
}
namespace
description Sensu RBAC namespace that the service component belongs to.
required true
type String
example 
namespace: default
{
  "namespace": "default"
}

Spec attributes

cron
description When the service component should be executed, using cron syntax or a predefined schedule. Use a prefix of TZ= or CRON_TZ= to set a timezone for the cron attribute.

NOTE: If you’re using YAML to create a service component that uses cron scheduling and the first character of the cron schedule is an asterisk (*), place the entire cron schedule inside single or double quotes (for example, cron: '* * * * *').
required true (unless interval is configured)
type String
example 
cron: 0 0 * * *
{
  "cron": "0 0 * * *"
}
handlers
description List of handlers to use for the events the service component produces. The service component will set the handlers property in events that are produced by rule evaluation. If no handlers are specified in the service component definition, handlers can be set by the monitoring rule itself via template arguments. Handlers specified in the service component definition will override any handlers set by rule evaluation.
required false
type Array
example 
handlers:
  - slack
{
  "handlers": [
    "slack"
  ]
}
interval
description How often the service component should be executed. In seconds. Each service component must have a value for either the interval or the cron attribute, but not both.
required true (unless cron is configured)
type Integer
example 
interval: 60
{
  "interval": 60
}
query
description Query expression that describes the events that each monitoring rule should process for the service component. Read query attributes for details.
required true
type Array
example 
query:
  - type: fieldSelector
    value: webserver in event.check.subscriptions
{
  "query": [
    {
      "type": "fieldSelector",
      "value": "webserver in event.check.subscriptions"
    }
  ]
}
rules
description List of the rule templates and arguments that Sensu should apply for the service component. Sensu evaluates each rule separately, and each rule produces its own event as output. Read rules attributes for details.
required true
type Map of key-value pairs
example 
rules:
- arguments:
    critical_threshold: 70
    warning_threshold: 50
  name: webservers_50-70
  template: aggregate
{
  "rules": [
    {
      "arguments": {
        "critical_threshold": 70,
        "warning_threshold": 50
      },
      "name": "webservers_50-70",
      "template": "aggregate"
    }
  ]
}
services
description List of business service entities that include the service component as a dependency.
required true
type Array
example 
services:
  - website-services
{
  "services": [
    "website-services"
  ]
}

Query attributes

type
description Type of selector to use to identify the events that the service component’s monitoring rule should process: fieldSelector or labelSelector.
required true
type String
example 
type: fieldSelector
{
  "type": "fieldSelector"
}
value
description Selector expression the query will use to identify the events that the service component’s monitoring rule should process.
required true
type String
example 
value: webserver in event.check.subscriptions
{
  "value": "webserver in event.check.subscriptions"
}

Rules attributes

arguments
description The arguments to pass to the rule template for the service component. Argument names and values will vary depending on the arguments configured in the specified rule template.
required false
type Map of key-value pairs
example 
- arguments:
    critical_threshold: 70
    warning_threshold: 50
{
  "arguments": {
    "critical_threshold": 70,
    "warning_threshold": 50
  }
}
name
description Explicit name to use for the rule-specific events generated for the service component. These names help keep events distinct when a service component includes different rules for the same rule template.
required true
type String
example 
name: webservers_50-70
{
  "name": "webservers_50-70"
}
template
description Name of the rule template the service component should use.
required true
type String
example 
template: aggregate
{
  "template": "aggregate"
}