README
¶
Table of Contents
- Overview
- Installation and Usage
- Checks
- Dependencies
- Comparison to Other Software
- Contributing and Getting Help
- License
Overview
This readme documents the current (development) version of distributive.
Distributive is a tool for running distributed health checks in datacenters. It was designed with Consul in mind, but is stack agnostic. It is simple to configure (with JSON checklists) and easy to deploy and run. It has no dependencies, and can be shipped as a speedy 1.3MB (yes, megabytes!) binary.
Usually, some external server will ask the host to execute this program, reading a checklist from a JSON file, and will record this program's exit code and standard out. Distributive's output includes information about which checks in a checklist failed, and how so.
The exit code meanings are defined as Consul, Kubernetes, Sensu, and Nagios recognize them.
- Exit code 0 - Checklist is passing
- Exit code 1 - Checklist is warning
- Any other code - Checklist is failing
As of right now, only exit codes 0 and 1 are used, even if a checklist fails.
Installation and Usage
Installation/Building
To install the development version (potentially unstable):
- Clone this repo:
git clone https://github.com/CiscoCloud/distributive - Get dependencies with
go get .(or used versioned dependencies with godep godep). - (Optional) Test with
go test -short ./... - Build a binary with
go build . - Follow the "Usage" instructions below
The Dockerfile demonstrates how to build it from scratch (without golang installed, etc.).
We also provide premade RPM packages on Bintray for versioned releases. You can view the RPM source and build RPM snapshots at distributive-rpm.
Distributive currently only supports Linux.
Usage
The default behavior is to run any checks specified via -f, -u, -s,
or -d options, or all checks in /etc/distributive.d/ if no location is
specified.
$ distributive --help
[...]
USAGE:
Distributive [global options] command [command options] [arguments...]
VERSION:
0.1.3
GLOBAL OPTIONS:
--verbosity "warn" info | debug | fatal | error | panic | warn
--file, -f Read a checklist from a file
--url, -u Read a checklist from a URL
--directory, -d "/etc/distributive.d/" Read all of the checklists in this directory
--stdin, -s Read data piped from stdin as a checklist
--help, -h show help
--version, -v print the version
Examples:
$ /path/to/distributive --verbosity="warn" -f ./samples/filesystem.json
$ distributive --f="/etc/distributive/samples/network.json" --verbosity=debug
$ ./distributive -u "http://pastebin.com/raw.php?i=5c1BAxcX"
$ /distributive --verbosity="info"
$ /path/to/distributive -d "/etc/distributive.d/" # same as default behavior
$ cat samples/filesystem.json | ./distributive -d "" -s=true --verbosity=fatal
Supported Frameworks
Distributive attempts to be as framework-agnostic as possible. It is known to work well with Consul, Kubernetes, Sensu and Nagios, which have similar design in how they detect passing and failing checks. There is documentation on how to use Distributive with Consul on our Github wiki.
Checks
For the impatient, examples of every single implemented check are available in
the samples/ directory, sorted by category. There is extensive documentation
for each check available on our Github wiki.
If you'd like to see how Distributive is used in production environments, take a look at the RPM source, which includes checks used in Microservices-Infrastructure.
Dependencies
Distributive itself has no dependencies; it is compiled as a statically linked standalone Go binary. Some checks, however, rely on output from specific packages. These dependencies are outlined for each check on our Github wiki.
Comparison to Other Software
Distributive was created with the idea of pushing responsibility to the nodes, It was also designed around the idea of constantly changing infrastructure, with servers being added and destroyed constantly, changing IP addresses, and even changing roles. Integration with Consul provides even greater flexibility.
Serverspec
Serverspec runs on a single control server, and requires each check to be in a directory matching the hostname of the machine to run it on. Distributive was designed for dynamic systems with changing IPs, which can report into Consul, Sensu, or another framework as soon as they are ready, and require little or no centralized configuration. Additionally, Distributive attempts to rely as little as possible on external tools/commands, using mostly just the Go standard library.
Nagios
Nagios is an end-to-end monitoring, security, and notification framework. It provides many services not included in Distributive, and solves a very different problem. Distributive is simple, lightweight, and easy to configure, and doesn't provide its own scheduling, dashboard, etc. It is designed to be used within frameworks such as Sensu and Consul. Luckily, Distributive conforms to [Nagios exit code specifications] nagios, and can be used just like any other plugin. Its advantage over other plugins is that it is small, fast, and has no dependencies.
Contributing and Getting Help
Contributing
Thank you for your interest in contributing! To get started, please check out our wiki.
Getting Help
All comments, questions, and contributions are always welcome. We strive to provide expedient and detailed support for anyone using our software. Please submit any requests via our Github Issues Page, where someone will see it and get to work promptly.
License
Copyright © 2015 Cisco Systems, Inc.
Licensed under the Apache License, Version 2.0 (the "License").
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Documentation
¶
Overview ¶
Distributive is a tool for running distributed health checks in server clusters. It was designed with Consul in mind, but is platform agnostic. The idea is that the checks are run locally, but executed by a central server that records and logs their output. This model distributes responsibility to each node, instead of one central server, and allows for more types of checks.
This file covers the panic logging mechanism for distributive
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Godeps
|
|
|
_workspace/src/github.com/Sirupsen/logrus
Package logrus is a structured logger for Go, completely API compatible with the standard library logger.
|
Package logrus is a structured logger for Go, completely API compatible with the standard library logger. |
|
_workspace/src/github.com/codegangsta/cli
Package cli provides a minimal framework for creating and organizing command line Go applications.
|
Package cli provides a minimal framework for creating and organizing command line Go applications. |
|
_workspace/src/github.com/fsouza/go-dockerclient
Package docker provides a client for the Docker remote API.
|
Package docker provides a client for the Docker remote API. |
|
_workspace/src/github.com/fsouza/go-dockerclient/external/github.com/docker/docker/pkg/parsers
Package parsers provides helper functions to parse and validate different type of string.
|
Package parsers provides helper functions to parse and validate different type of string. |
|
_workspace/src/github.com/fsouza/go-dockerclient/external/github.com/docker/docker/pkg/pools
Package pools provides a collection of pools which provide various data types with buffers.
|
Package pools provides a collection of pools which provide various data types with buffers. |
|
_workspace/src/github.com/fsouza/go-dockerclient/external/github.com/docker/docker/pkg/ulimit
Package ulimit provides structure and helper function to parse and represent resource limits (Rlimit and Ulimit, its human friendly version).
|
Package ulimit provides structure and helper function to parse and represent resource limits (Rlimit and Ulimit, its human friendly version). |
|
_workspace/src/github.com/fsouza/go-dockerclient/external/github.com/docker/docker/pkg/units
Package units provides helper function to parse and print size and time units in human-readable format.
|
Package units provides helper function to parse and print size and time units in human-readable format. |
|
_workspace/src/github.com/fsouza/go-dockerclient/external/github.com/gorilla/context
Package context stores values shared during a request lifetime.
|
Package context stores values shared during a request lifetime. |
|
_workspace/src/github.com/fsouza/go-dockerclient/external/github.com/gorilla/mux
Package gorilla/mux implements a request router and dispatcher.
|
Package gorilla/mux implements a request router and dispatcher. |
|
_workspace/src/github.com/fsouza/go-dockerclient/testing
Package testing provides a fake implementation of the Docker API, useful for testing purpose.
|
Package testing provides a fake implementation of the Docker API, useful for testing purpose. |
|
_workspace/src/github.com/mitchellh/osext
Extensions to the standard "os" package.
|
Extensions to the standard "os" package. |
|
_workspace/src/github.com/mitchellh/panicwrap
The panicwrap package provides functions for capturing and handling panics in your application.
|
The panicwrap package provides functions for capturing and handling panics in your application. |
|
_workspace/src/golang.org/x/crypto/sha3
Package sha3 implements the SHA-3 fixed-output-length hash functions and the SHAKE variable-output-length hash functions defined by FIPS-202.
|
Package sha3 implements the SHA-3 fixed-output-length hash functions and the SHAKE variable-output-length hash functions defined by FIPS-202. |
|
dockerstatus provides a few functions for getting very simple data out of Docker, mostly for use in simple status checks.
|
dockerstatus provides a few functions for getting very simple data out of Docker, mostly for use in simple status checks. |
|
fsstatus provides utility functions for querying several aspects of the filesystem, especially as pertains to monitoring.
|
fsstatus provides utility functions for querying several aspects of the filesystem, especially as pertains to monitoring. |
|
memstatus provides functions that provide information about both RAM and swap on the host.
|
memstatus provides functions that provide information about both RAM and swap on the host. |
|
netstatus provides utility functions for querying several aspects of the network/host, especially as pertains to monitoring.
|
netstatus provides utility functions for querying several aspects of the network/host, especially as pertains to monitoring. |
|
fsstatus provides utility functions for querying several aspects of systemd's status, especially as pertains to monitoring.
|
fsstatus provides utility functions for querying several aspects of systemd's status, especially as pertains to monitoring. |
|
Package tabular simplifies the reading of tabular data.
|
Package tabular simplifies the reading of tabular data. |
|
usrstatus provides utility functions for querying several aspects of Unix users and groups, especially as pertains to monitoring.
|
usrstatus provides utility functions for querying several aspects of Unix users and groups, especially as pertains to monitoring. |