Upgrading Sensu

Upgrading to the latest version of Sensu Go from 5.0.0 or later

To upgrade to the latest version of Sensu Go from version 5.0.0 or later, first install the latest packages.

Then restart the services.

NOTE: For systems using systemd, run sudo systemctl daemon-reload before restarting the services.

# Restart the Sensu agent
sudo service sensu-agent restart

# Restart the Sensu backend
sudo service sensu-backend restart

You can use the version command to determine the installed version using the sensu-agent, sensu-backend, and sensuctl tools. For example: sensu-backend version.

Migrating to Sensu Go from Sensu Core 1.x

This guide provides general information for migrating your Sensu instance from Sensu Core 1.x to Sensu Go 5.0. For instructions and tools to help you translate your Sensu configuration from Sensu Core 1.x to Sensu Go, see the following resources.

Sensu Go includes important changes to all parts of Sensu: architecture, installation, resource definitions, event data model, check dependencies, filter evaluation, and more. Sensu Go also includes a lot of powerful features to make monitoring easier to build, scale, and offer as a self-service tool to your internal customers.


Sensu is now provided as three packages: sensu-go-backend, sensu-go-agent, and sensu-go-cli (sensuctl). This results in a fundamental change in Sensu terminology from Sensu Core 1.x: the server is now the backend; the client is now the agent. To learn more about new terminology in Sensu Go, see the glossary.


The external RabbitMQ transport and Redis datastore in Sensu Core 1.x have been replaced with an embedded transport and etcd datastore in Sensu Go. The Sensu backend and agent are configured using YAML files or using the sensu-backend or sensu-agent command-line tools, instead of using JSON files. Sensu checks and pipeline elements are now configured via the API or sensuctl tool instead of JSON files. See the backend, agent, and sensuctl reference docs for more information.


“Clients” are now represented within Sensu Go as abstract “entities” that can describe a wider range of system components (network gear, web server, cloud resource, etc.) Entities include “agent entities” (entities running a Sensu agent) and familiar “proxy entities”. See the entity reference and the guide to monitoring external resources for more information.


Standalone checks are no longer supported in Sensu Go, although similar functionality can be achieved using role-based access control, assets, and entity subscriptions. There are also a few changes to check definitions to be aware of. The stdin check attribute is no longer supported in Sensu Go, and Sensu Go no longer tries to run a “default” handler when executing a check without a specified handler. Additionally, round-robin subscriptions and check subdues are not yet available in Sensu Go.

Check hooks are now a resource type in Sensu Go, meaning that hooks can be created, managed, and reused independently of check definitions. You can also execute multiple hooks for any given response code.


All check results are now considered events and are processed by event handlers. You can use the built-in incidents filter to recreate the Sensu Core 1.x behavior in which only check results with a non-zero status are considered events.


Transport handlers are no longer supported by Sensu Go, but you can create similar functionality using a pipe handler that connects to a message bus and injects event data into a queue.


Ruby eval logic has been replaced with JavaScript expressions in Sensu Go, opening up powerful possibilities to filter events based on occurrences and other event attributes. As a result, the built-in occurrences filter in Sensu Core 1.x is not provided in Sensu Go, but you can replicate its functionality using this filter definition. Sensu Go includes three new built-in filters: only-incidents, only-metrics, and allow-silencing. Sensu Go does not yet include a built-in check dependencies filter or a filter-when feature.


The sensu-install tool has been replaced in Sensu Go by assets, shareable, reusable packages that make it easy to deploy Sensu plugins. Sensu Plugins in Ruby can still be installed via sensu-install by installing sensu-plugins-ruby; see the installing plugins guide for more information.

Role-based access control

Role-based access control (RBAC) is a built-in feature of the open-source version of Sensu Go. RBAC allows management and access of users and resources based on namespaces, groups, roles, and bindings. To learn more about setting up RBAC in Sensu Go, see the RBAC reference and the guide to creating a read-only user.


Silencing is now disabled by default in Sensu Go and must be enabled explicitly using the built-in not_silenced filter.

Token substitution

The syntax for using token substitution has changed from using triple colons to using double curly braces.


Sensu Go does not yet support check aggregates.


In addition to the changes to resource definitions, Sensu Go includes a new, versioned API. See the API overview for more information.

Custom attributes

Custom check attributes are no longer supported in Sensu Go. Instead, Sensu Go provides the ability to add custom labels and annotations to entities, checks, assets, hooks, filters, mutators, handlers, and silencing entries. See the metadata attributes section in the reference documentation for more information about using labels and annotations (for example: metadata attributes for entities).