Open source monitoring tool for ephemeral infrastructure & distributed applications.
Clone or download
Failed to load latest commit information.
.circleci Add the make call to build bits+packages back to CircleCI config. (#2189 Oct 19, 2018
.github Add documentation section to PR template. (#1665) Jun 11, 2018
agent fmt.Errorf cleanup (#2185) Oct 17, 2018
asset fmt.Errorf cleanup (#2185) Oct 17, 2018
backend fmt.Errorf cleanup (#2185) Oct 17, 2018
benchmark/cmd Remove KeepaliveTimeout from entities (#2045) Sep 12, 2018
build/ci Issue 2121-Post build/test logs as artifacts to S3 (#2134) Oct 2, 2018
cli Issue 2011-Validate Go code style formatting (#2129) Sep 27, 2018
cmd fmt.Errorf cleanup (#2185) Oct 17, 2018
command Mock out command execution (#2115) Oct 9, 2018
dashboard [Web UI] Drop in replacement for Apollo's Query component (#2150) Oct 10, 2018
docker-scripts kill and in docker image Jul 31, 2017
examples hides its output (#1277) Apr 10, 2018
graphql [GraphQL] Gracefully handle failed type assertions (#1650) Jul 18, 2018
handler Add errcheck to the linter. Dec 7, 2017
licenses Remove handlers package (#2100) Sep 25, 2018
packaging Deprecated --custom-attributes in the sensu-agent command, changed to… Sep 21, 2018
rpc Close extension grpc client conns after execution. (#1996) Aug 29, 2018
scripts Remove the Error store & type (#2168) Oct 12, 2018
system Use default hostname (#1648) Jun 6, 2018
testing Remove the Error store & type (#2168) Oct 12, 2018
transport Optimize dynamic unmarshaling (#1327) Apr 18, 2018
types fmt.Errorf cleanup (#2185) Oct 17, 2018
util fmt.Errorf cleanup (#2185) Oct 17, 2018
vendor Be case-insensitive when dealing with env. vars (#2098) Sep 27, 2018
version Do not use build tags for the edition (#1880) Jul 30, 2018
.appveyor.yml Mock out command execution (#2115) Oct 9, 2018
.editorconfig add some test types Jan 11, 2018
.gitattributes Add union option when merging Feb 8, 2018
.gitignore etcd authentication (#2070) Sep 20, 2018
.kitchen.yml update log location for sysvinit, bump build iteraiton Sep 5, 2017 Refactor agent to use boltdb-based asset manager (#2132) Oct 16, 2018 Clarify the fork/clone procedure. (#2059) Sep 17, 2018
DCO [dco] added dco file, auto-fill-mode wrap readme content Dec 8, 2017
Dockerfile Dockerfile: add etcdctl (#1939) Aug 9, 2018
Dockerfile.packaging Fix the manual packaging process (#1231) Mar 27, 2018
Dockerfile.rhel Address RHEL certification issues (#1959) Sep 11, 2018
Dockerfile.rhel_atomic Address RHEL certification issues (#1959) Sep 11, 2018
Dockerfile.testagent Add dashboard, bash to docker images May 8, 2017 fix name (#1053) Feb 21, 2018
Gopkg.lock Be case-insensitive when dealing with env. vars (#2098) Sep 27, 2018
Gopkg.toml Be case-insensitive when dealing with env. vars (#2098) Sep 27, 2018
LICENSE [license] removed .txt from license file, github convention Sep 28, 2017
Makefile Wipe all artifacts when clean task is invoked (#1560) May 18, 2018 Corrects the check field total_state-change json tag to total_state_c… Aug 13, 2018
Vagrantfile Upgrade Go to 1.10. (#1070) Feb 23, 2018 Add windows/386 support to (#2001) Aug 22, 2018 reimplement package building with Makefiles Aug 30, 2017
build.ps1 Mock out command execution (#2115) Oct 9, 2018 Mock out command execution (#2115) Oct 9, 2018 codecov setup Apr 25, 2017
docker-compose.yaml etcd authentication (#2070) Sep 20, 2018
gcs-service-account.json.enc re-encrypt gcs-service-account.json using (#1229) Mar 26, 2018

Sensu 2.0

TravisCI: TravisCI Build Status

CircleCI: CircleCI Build Status

Sensu is an open source monitoring tool for ephemeral infrastructure and distributed applications. It is an agent based monitoring system with built-in auto-discovery, making it very well-suited for cloud environments. Sensu uses service checks to monitor service health and collect telemetry data. It also has a number of well defined APIs for configuration, external data input, and to provide access to Sensu's data. Sensu is extremely extensible and is commonly referred to as "the monitoring router".

To learn more about Sensu, please visit the website.

What is Sensu 2.0?

Sensu 2.0 is a complete rewrite of Sensu in Go, with new capabilities and reduced operational overhead. It eliminates several sources of friction for new and experienced Sensu users.


Sensu 2.0 installer packages are available for a number of computing platforms (e.g. Debian/Ubuntu, RHEL/Centos, etc), but the easiest way to get started is with the official Docker image, sensu/sensu.

Please note the following installation steps to get Sensu up and running on your local workstation with Docker.

NOTE: the following instructions are based on Docker Community Edition (CE), though they may be easily adapted for other container platforms. Please download and install Docker CE before proceeding.

  1. Start the Sensu 2.0 Backend process

    $ docker run -d --name sensu-backend \
    -p 2380:2380 -p 3000:3000 -p 8080:8080 -p 8081:8081 \
    sensu/sensu:2.0.0-beta.3 sensu-backend start
  2. Start the Sensu 2.0 Agent process

    $ docker run -d --name sensu-agent --link sensu-backend \
    sensu/sensu:2.0.0-beta.3 sensu-agent start \
    --backend-url ws://sensu-backend:8081 \
    --subscriptions workstation,docker
  3. Download and install the Sensu 2.0 CLI tool

    On macOS

    $ latest=$(curl -s
    $ curl -LO$latest/darwin/amd64/sensuctl
    $ chmod +x sensuctl
    $ sudo mv sensuctl /usr/local/bin/

    On Debian/Ubuntu Linux

    $ curl -s \ \
    | sudo bash
    $ sudo apt-get install sensu-cli

    On RHEL/CentOS Linux

    $ curl -s \ \
    | sudo bash
    $ sudo yum install sensu-cli
  4. Configure the Sensu 2.0 CLI tool

    $ sensuctl configure
    ? Sensu Backend URL:
    ? Username: admin
    ? Password: P@ssw0rd!
    ? Organization: default
    ? Environment: default
    ? Preferred output format: tabular
  5. List Sensu 2.0 Entities

    $ sensuctl entity list

Congratulations! You now have a local Sensu 2.0 deployment!

To learn more about Sensu 2.0 and what you can do with it, please check out the official project documentation.

Getting Started

Now that you have a local Sensu 2.0 deployment up and running, it's time to configure your first Sensu monitoring check! Sensu checks are commands (or scripts) that allow you to monitor server resources, services, and application health, as well as collect & analyze metrics.

  1. Register a Sensu 2.0 Asset for the check executable

    $ sensuctl asset create check-plugins \
    --url \
    --sha512 4e6f621ebe652d3b0ba5d4dead8ddb2901ea03f846a1cb2e39ddb71b8d0daa83b54742671f179913ed6c350fc32446a22501339f60b8d4e0cdb6ade5ee77af16
  2. Create a check to monitor Google via ICMP from your workstation

    $ sensuctl check create google \
    --runtime-assets check-plugins \
    --command "check-ping -h -P 80" \
    --subscriptions workstation --interval 10 --timeout 5


To make a good faith effort to ensure the criteria of the MIT License are met, Sensu Inc. requires the Developer Certificate of Origin (DCO) process to be followed.

For guidelines on how to contribute to this project and more information on the DCO, please see


Sensu is written in Go, and targets the latest stable release of the Go compiler. To work on Sensu, you will need the latest release of Go.

Go installation instructions



We are using the version proto3 of the protocol buffers language. Here are some useful resources:

To learn more about protocol buffers

The proto3 language guide


Install the protobuf compiler since we don't use the one that golang uses.

brew install protobuf

Otherwise, see the for non-C++ users instructions here.

Quick Start

Once you make a change to any *.proto file within the types package, you will need to regenerate the associated *.pb.go file. To do so, simply run go generate on the package.


Sensu uses golang/dep for managing its dependencies. You will need to install the latest stable version of dep in order to install Sensu's dependencies.

Dep releases


Running the following will pull all required dependencies, including static analysis and linter tools.

./ deps

Later, if you would like to add a dependency, run:

dep ensure -add

If you would like to update a dependency, run:

dep ensure -update

When you would like to remove a dependency, remove the it from Gopkg.toml and then run:

dep prune

Further Reading



The simplest way to the build Sensu is with the sensu-go-build image. The image contains all the required tools to build the agent, backend and sensuctl.

docker pull sensu/sensu-go-build
docker run -it -e GOOS=darwin -v `pwd`:/go/src/ --entrypoint='/go/src/' sensu/sensu-go-build

If you would like to build for different platforms and architectures use GOOS and GOARCH env variables. See Optional environment variables for more.

When complete your binaries will be present in the target directory.


First ensure that you have the required tools installed to build the programs.

  • Ensure that you have the Go tools installed and your environment configured. If not follow the official Install the Go tools guide.
  • When building the Sensu backend you will need NodeJS and Yarn installed so that the web UI may be included in the binary. Follow Installing Node.js and Yarn Installation for installation instructions for your platform.

Once all the tools are installed you are now ready to use the build script. To build the Sensu backend, agent and sensuctl, run:

./ build

Each product can built separately, with one of the following:

./ build_agent
./ build_backend
./ build_cli

By default the web UI is built along side and bundled into the backend, as this can be a time intensive process, we provide an escape hatch. Use the dev tag to avoid building the web UI.

./ build_backend -tags dev


Install dependencies:

./ deps

Run test suites:

./ ci

Run end-to-end tests:

./ e2e

To run a specific test:

./ e2e -run TestRBAC

To prevent tests from running in parallel:

./ e2e -parallel 1