Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 128 lines (83 sloc) 6.687 kb
3b00e36 José de Paula E. Júnior Added license and README.md
authored
1 HoardD, send ALL metrics to graphite!
2 =====================================
3
4 What is HoardD
5 ---------------
6
7 HoardD is a [node.js](http://nodejs.org/)/[coffee-script](http://coffeescript.org/) tool to send metrics to [Graphite](http://graphite.wikidot.com/). The objective here is to send specifically server data like disk stats, network, cpu, that can later be used for graphs using Graphite default web application or [Graphiti](http://dev.paperlesspost.com/blog/2011/12/16/introducing-graphiti-an-alternate-frontend-for-graphite/).
8
9 Data is collected using a series of *scripts* written in coffee-script (js too but at the moment it only reads the files ended with .coffee). Writing new metrics is easy as creating a new coffee script and pushing it to the server pending queue.
10
11 There are other projects that do the same: [collectd](http://collectd.org/) has some plugins to send data to graphite and [diamond-gmond](https://github.com/freemed/diamond-gmond) is a python daemon that does exactly the same as this one (I only got to know diamond after I was 90% done on the first version of HoardD).
12
13 Install, configure and run it
14 ---------------------------------
15
8f9bc95 José de Paula E. Júnior New readme changes to accomodate js scripts
authored
16 Configuration is done using the a `json` file. The package includes a default config that you probably can use after changing the hostname for your graphite/carbon node. HoardD was meant to be used with runit and similar tools so no daemonizing is done and all the logging is written on stdout (use `--debug` if you want detailed info on what is happening.) By default scripts sample the data each 10 seconds, and then sends the data to graphite each 6 samples are collected, effectively making one connection each 60 seconds.
3b00e36 José de Paula E. Júnior Added license and README.md
authored
17
18 Also, HoardD was made to be used with chef (or any other configuration management system) so while I know that configuring the FQDN on the config JSON is annoying, it was meant to be automatically filled by a template. If you are managing lots of servers and configs by hand in 2012 you are doing it wrong.
19
5904ec7 José de Paula E. Júnior Minor alteration on the README.md
authored
20 The master branch will be updated only to working versions (i.e: I will *try* not to break it), so you can probably just do a clone/fetch/pull from it on new versions.
21
3ec13ec José de Paula E. Júnior Instructions on configuration for scripts
authored
22 ### Scripts and specific configuration
23
24 The MySQL script is an example of how to configure specific scripts. It contains a `mysql.json` file that is read by the script when it starts. Just make sure to:
25
8f9bc95 José de Paula E. Júnior New readme changes to accomodate js scripts
authored
26 * Keep the configs with the same name as the plugin (like, `mysql.coffee` and `mysql.json`)
3ec13ec José de Paula E. Júnior Instructions on configuration for scripts
authored
27 * Put/link the configuration on the script path (together with the scripts)
28
29 For real, you can do whatever you want on your scripts, but it's better to make it easier for other people to configure/understand, so let's stick to a default.
30
3b00e36 José de Paula E. Júnior Added license and README.md
authored
31 Retentions, sample interval and counter metrics
32 ------------------------------------------------
33
34 ### Retentions and sample interval
35
36 Something mus be said about those things if you never used graphite. The first is the relation between the retentions configured on `storage-schemas.conf` and HoardD `sampleInterval` setting. On my tests results were more accurate if you make the retention time for the smaller retention the same as the sample interval. Results can be strange and even data can be lost in case of non-matching values. So, for the default sample interval of 10 seconds you need something like
37
38 ```cfg
39 retentions = 10s:60m,1m:24h,15m:5y
40 ```
41
42 ### Counter metrics
43
5904ec7 José de Paula E. Júnior Minor alteration on the README.md
authored
44 Counter metrics are ever increasing counters, like the ones used on `/proc/net/interfaces`, if you want to get a per second graphic (like Kb/s in the interfaces speed case) you need to apply Graphite functions: `derivative` and `scale`.
3b00e36 José de Paula E. Júnior Added license and README.md
authored
45
5904ec7 José de Paula E. Júnior Minor alteration on the README.md
authored
46 `derivative` will make the graphs show the difference between 2 samples of data instead of an ever increasing counter, so if your counter increased from 1000 to 1100 between 2 samples the graph will show 100, not 1100. Now this is between 2 samples, and your samples are each 10 seconds so Graphite makes an average of it. If you need the graph on a per-second basis you must apply the `scale` function that will multiply that value by a ratio. If you need the graph in per seconds you then must multiply the value by 1/10 = 0.1.
3b00e36 José de Paula E. Júnior Added license and README.md
authored
47
48 **TL;DR**: use `derivative` to make the graph show differences between two samples and `scale` to make it show per second. The scale is always 1/*data retention value* of the graph.
49
3ec13ec José de Paula E. Júnior Instructions on configuration for scripts
authored
50 For example, for network speed:
51
52 ```
53 scale(derivative(hoard.host.interfaces.eth0.txBytes),0.1)
54 ```
55
3b00e36 José de Paula E. Júnior Added license and README.md
authored
56 Writing new scripts
57 --------------------
58
8f9bc95 José de Paula E. Júnior New readme changes to accomodate js scripts
authored
59 To add new scripts just drop the `.coffee` or `.js` file on `scriptPath` and restart HoardD (making it detect new scripts without restarting is on TODO).
3b00e36 José de Paula E. Júnior Added license and README.md
authored
60
61 Writing new scripts should be easy:
62
63 * Change the variables
64 * Write what you need to do on the `run` function
65 * Use `obj.push_metric <metric name> <value>`
66
67 `obj` is an Object that is passed as the argument for each script and gives you some tools
68
69 * `push_metric` to add metrics to the pending array to be sent to graphite
70 * `cli` has all the methods from the [cli](https://github.com/chriso/cli) module (use it for logging)
71 * `fqdn` the server FQDN configured on the JSON config file for you to use on metrics
72
8f9bc95 José de Paula E. Júnior New readme changes to accomodate js scripts
authored
73 Code speaks better than words in some case, this is the `load_average.coffee` script:
3b00e36 José de Paula E. Júnior Added license and README.md
authored
74
75 ```coffeescript
8f9bc95 José de Paula E. Júnior New readme changes to accomodate js scripts
authored
76 Fs = require 'fs'
77 Path = require 'path'
3b00e36 José de Paula E. Júnior Added license and README.md
authored
78
79 module.exports = (server) ->
80 run = () ->
8f9bc95 José de Paula E. Júnior New readme changes to accomodate js scripts
authored
81 metricPrefix = "#{server.fqdn}.load_average"
82 server.cli.debug "Running load average script"
83
84 # Read from /proc
85 procfile = '/proc/loadavg'
86 if Path.existsSync procfile
87 data = Fs.readFileSync(procfile, 'utf-8')
88 [one, five, fifteen] = data.split(' ', 3)
89 server.push_metric "#{metricPrefix}.short", one
90 server.push_metric "#{metricPrefix}.medium", five
91 server.push_metric "#{metricPrefix}.long", fifteen
92 ```
93
94 And this is the `uptime.js` script:
95
96 ```javascript
97 var Os;
3b00e36 José de Paula E. Júnior Added license and README.md
authored
98
8f9bc95 José de Paula E. Júnior New readme changes to accomodate js scripts
authored
99 Os = require('os');
100
101 module.exports = function(server) {
102 var run;
103
104 run = function() {
105 var metricPrefix, uptime;
106 metricPrefix = server.fqdn + ".uptime";
107 server.cli.debug("Running uptime script");
108
109 // Node os object makes this easy
110 uptime = Os.uptime();
111 server.push_metric(metricPrefix, uptime);
112 }
113 return run;
114 }
3b00e36 José de Paula E. Júnior Added license and README.md
authored
115 ```
116
117 Take a look at the code of the other scripts and you will see that there's nothing genius going on there.
118
119 If you write something cool, make sure to send me a patch, push-request, anything! The tool is as good as the scripts available for it really.
120
121 License and author
122 ------------------
123
124 HoardD is licensed under the MIT License but please, send back your changes :). A copy of the license is included on the LICENSE file.
8f9bc95 José de Paula E. Júnior New readme changes to accomodate js scripts
authored
125
126 You can read announcements and news on http://coredump.io
3b00e36 José de Paula E. Júnior Added license and README.md
authored
127
Something went wrong with that request. Please try again.