https://github.com/github/backstop
HTTP service for submitting metrics to Graphite
https://github.com/github/backstop
Last synced: 5 months ago
JSON representation
HTTP service for submitting metrics to Graphite
- Host: GitHub
- URL: https://github.com/github/backstop
- Owner: github
- License: other
- Archived: true
- Fork: true (obfuscurity/backstop)
- Created: 2014-05-05T16:27:46.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2014-01-09T16:45:19.000Z (about 12 years ago)
- Last Synced: 2024-09-29T00:21:26.953Z (over 1 year ago)
- Language: Ruby
- Size: 3.82 MB
- Stars: 13
- Watchers: 29
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Backstop
[](http://travis-ci.org/obfuscurity/backstop)
Backstop is a simple endpoint for submitting metrics to Graphite. It accepts JSON data via HTTP POST and proxies the data to one or more Carbon/Graphite listeners.
## Usage
### Collectd Metrics
Backstop supports submission of metrics via the Collectd [write_http](http://collectd.org/wiki/index.php/Plugin:Write_HTTP) output plugin. A sample client configuration:
```
Format "JSON"
User ""
Password ""
```
### GitHub Post-Receive Hooks
Backstop can receive commit data from GitHub [post-receive webhooks](https://help.github.com/articles/post-receive-hooks). Your WebHook URL should consist of the Backstop service URL with the `/github` endpoint. For example, `https://backstop.example.com/github`.
All GitHub commit metrics contain the project name, branch information, author email and commit identifier, and are stored with a value of `1`. These can then be visualized as annotation-style metrics using Graphite's `drawAsInfinite()` function. Sample metric:
```
github.project.refs.heads.master.bob-example-com.10af2cb02eadd4cb1a3e43aa9cae47ef2cd07016 1 1203116237
```
### PagerDuty Incident Webhooks
Backstop can also receive PagerDuty incidents courtesy of Jesse Newland's [pagerduty-incident-webhooks](https://github.com/github/pagerduty-incident-webhooks) project. When deploying `pagerduty-incident-webhooks` make sure to set `PAGERDUTY_WEBHOOK_ENDPOINT` to your Backstop service URL with the `/pagerduty` endpoint. For example, `https://backstop.example.com/pagerduty`.
Metrics will be stored under the `alerts` prefix with a value of `1`. These can then be visualized as annotation-style metrics using Graphite's `drawAsInfinite()` function. Sample metric:
```
alerts.nagios.web1.diskspace 1 1365206103
```
### Custom Metrics
Use the `/publish` endpoint in conjunction with one of the approved `PREFIXES` for submitting metrics to Backstop. In most environments it makes sense to use distinct prefixes for normal (e.g. gauge, counters, etc) metrics vs annotation (event-style) metrics. `PREFIXES` is defined as a comma-delimited list of prefix strings. For example:
```bash
export PREFIXES='test,app1,app2'
```
#### Sending Metrics
Here is a basic example for posting an application metric to the `custom` prefix.
```ruby
RestClient.post("https://backstop.example.com/publish/custom",
[{:metric => key, :value => value, :measure_time => Time.now.to_i}].to_json)
```
#### Sending Annotations
Here is an example for posting a software release announcement to the `note` prefix.
```ruby
RestClient.post("https://backstop.example.com/publish/note",
[{:metric => "foobar.release", :value => "v214", :measure_time => Time.now.to_i}].to_json)
```
#### Using with Hosted Graphite
Graphite hosting service [Hosted Graphite](https://www.hostedgraphite.com) requires metrics to be submitted with an API key prepended to the metric. To use their service, just define the `API_KEY` environment variable.
## Deployment
Backstop supports optional Basic Authentication through Rack::Auth::Basic. Simply set BACKSTOP_AUTH to your colon-delimited credentials (e.g. `user:pass`).
The `CARBON_URLS` variable must be set to one or more valid destinations. Examples:
```
export CARBON_URLS="carbon://10.10.10.10:2003,carbon://10.10.20.10:2003"
```
### Local
The following instructions assume a working Ruby installation with the bundler gem already installed on your system.
```bash
$ git clone https://github.com/obfuscurity/backstop.git
$ cd backstop
$ bundle install
$ export CARBON_URLS=...
$ export PREFIXES=...
$ export BACKSTOP_AUTH=... (optional)
$ foreman start
```
### Heroku
```bash
$ heroku create
$ heroku config:add CARBON_URLS=...
$ heroku config:add PREFIXES=...
$ heroku config:add BACKSTOP_AUTH=... (optional)
$ git push heroku master
```
## License
Backstop is distributed under a 3-clause BSD license.
## Thanks
Thanks to Michael Gorsuch (@gorsuch) for his work on the collectd parser and the "Mitt" application that preceded Backstop.