Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 195 lines (140 sloc) 8.03 kb
5f3ec82 @webframp Prune README in prep for changes
webframp authored
1 # Graphite Cookbook
9475e9f @dje initial graphite cookbook
dje authored
2
5f3ec82 @webframp Prune README in prep for changes
webframp authored
3 [![Build Status](https://travis-ci.org/hw-cookbooks/graphite.png?branch=teh-futur)](https://travis-ci.org/hw-cookbooks/graphite)
4 [![Code Climate](https://codeclimate.com/github/hw-cookbooks/graphite.png)](https://codeclimate.com/github/hw-cookbooks/graphite)
5
6 ## Description
7
0cc9393 @gwaldo Pointing the link in the readme to current docs
gwaldo authored
8 Library cookbook for installation and configuration of [Graphite](http://graphite.readthedocs.org) via Chef
a55245b @dje link to Graphite
dje authored
9
e247c2c @webframp Update urls to graphite docs, closes #103
webframp authored
10 Consult the Graphite documentation for more information:
11
12 - http://graphite.readthedocs.org/en/latest/
13 - http://graphite.wikidot.com/
c0977d9 @webframp README: spelling, minor fixes
webframp authored
14 - https://github.com/graphite-project
e247c2c @webframp Update urls to graphite docs, closes #103
webframp authored
15
5f3ec82 @webframp Prune README in prep for changes
webframp authored
16 ## Platforms
9475e9f @dje initial graphite cookbook
dje authored
17
c0977d9 @webframp README: spelling, minor fixes
webframp authored
18 * Ubuntu
f264b4f @webframp RHEL works now, update supported platforms
webframp authored
19 * Debian
52776c6 @tas50 Readme improvements
tas50 authored
20 * RHEL and derivatives (Centos, Amazon Linux, Oracle Linux, Scientific Linux)
21 * Fedora
a55245b @dje link to Graphite
dje authored
22
fb4bb71 @webframp list attributes and recipes in readme
webframp authored
23 ## Attributes
24 See
25 [default attributes](https://github.com/hw-cookbooks/graphite/blob/master/attributes/default.rb#L48)
26 for platform specific packages installed.
c524d76 @zuazo added whisper-clean-this-node.sh for helping on whisper database cleanin...
zuazo authored
27
fb4bb71 @webframp list attributes and recipes in readme
webframp authored
28 - `node['graphite']['version']` - package version to install, defaults to '0.9.12'
29 - `node['graphite']['twisted_version']` - twisted version to pin to,
30 defaults to '13.1'
31 - `node['graphite']['django_version']` - django version to use,
32 defaults to '1.5.5'
33 - `node['graphite']['user']` - graphite user, 'graphite'
34 - `node['graphite']['group']` - graphite group, 'graphite'
35 - `node['graphite']['base_dir']` - default base dir, '/opt/graphite'
36 - `node['graphite']['doc_root']` - doc root for graphite-web, '/opt/graphite/webapp'
37 - `node['graphite']['storage_dir'] ` - storage dir, '/opt/graphite/storage'
38 - `node['graphite']['install_type']` - 'package' or 'source'. Setting
39 this to source will use latest github master branch
40 - `default['graphite']['package_names']` - package name hash, indexed
41 by 'install_type' attribute.
42 - `default['graphite']['graph_templates']` - graphite template config hash
92c4a90 @webframp Add attribute for managing the django time zone setting
webframp authored
43
fb4bb71 @webframp list attributes and recipes in readme
webframp authored
44 ### Adjusting package source location
9475e9f @dje initial graphite cookbook
dje authored
45
fb4bb71 @webframp list attributes and recipes in readme
webframp authored
46 You can override the
47 `node['graphite']['package_names'][#{name}]['source']` attribute,
48 where `#{name}` is one of `whisper`, `carbon` or `graphite_web`, to
49 set a custom install path. By default a source install will use the
50 github master branch.
51
52 ## Recipes
53 ### default
caae682 @webframp README: improve recipe section for web, uwsgi
webframp authored
54
fb4bb71 @webframp list attributes and recipes in readme
webframp authored
55 No-op, assuming cookbook inclusion in a custom wrapper.
56
57 ### packages
caae682 @webframp README: improve recipe section for web, uwsgi
webframp authored
58
fb4bb71 @webframp list attributes and recipes in readme
webframp authored
59 Just install all packages, carbon and web
60
61 ### carbon
caae682 @webframp README: improve recipe section for web, uwsgi
webframp authored
62
fb4bb71 @webframp list attributes and recipes in readme
webframp authored
63 Install all carbon packages, setup the graphite user, storage paths
64 and write the carbon configuration. Does not start any services.
7b9bf61 @webframp bump version and fix readme
webframp authored
65
caae682 @webframp README: improve recipe section for web, uwsgi
webframp authored
66 ### web
67
68 Set up just about everything for graphite web, except configure it and
69 start the service. Use the `graphite_web_config` resource and the
70 `uwsgi` recipe for those two things.
71
72 Some of this weirdness may not really be needed, so send us a PR if
73 you fix it before us. For example, I'd love some way to remove that
74 execute block for selinux and there's probably a better way to manage
75 all those files and directories.
76
77 ### uwsgi
78
79 Start a uwsgi runit service for graphite-web. That's it.
80
81 ### Various internal recipes
82
83 View the code for additional stub recipes that perform smaller pieces
84 of functionality such as setup the user or install specific packages,
85 the all begin with an underscore `_`.
86
87 It's like a treasure hunt.
7b9bf61 @webframp bump version and fix readme
webframp authored
88
5f3ec82 @webframp Prune README in prep for changes
webframp authored
89 ## Custom Resources
36e2179 @dje Document graphite/ganglia integration just a bit.
dje authored
90
6f70d81 @webframp README: basic documentation for new resources
webframp authored
91 ### Carbon daemons
92 Management for the various
93 [Carbon](https://github.com/graphite-project/carbon) services which
94 receive your metrics and write them to disk.
95
96 * `graphite_service`: sets up a carbon service with runit, essentially
97 a glorified `runit_service`. Carbon configuration should be defined
98 first with one of the `graphite_carbon_*` resources. Multiple
99 daemons can be run by using multiple resources with names such as
100 `cache:a`, `cache:b`, etc..
101 * `graphite_carbon_aggregator`: data driven resource for carbon-aggregator configuration
102 * `graphite_carbon_cache`: data driven resource for carbon-cache configuration
103 * `graphite_carbon_relay`: data driven resource for carbon-cache configuration
104
105 ### Storage
106 [Whisper](https://github.com/graphite-project/whisper) is
107 pretty much a requirement right now, so these resources assume whisper
108 libraries should be installed. Feel free to implement something else in
109 your own wrapper if you live on the edge and prefer [Ceres](https://github.com/graphite-project/ceres).
110
111 * `graphite_storage`: makes a directory intended for graphite storage,
112 installs whisper
113 * `graphite_storage_schema`: data driven resource for storage schema
114
115 ### Graphite Web
116 Write the configuration file for [Graphite Web](https://github.com/graphite-project/graphite-web)
117
118 * `graphite_web_config`: data driven python config file writer for
119 graphite web. Assumes the whole file is managed, typically this is
120 the path to local_settings.py. Custom python code can be placed in
121 the optional 'dynamic template', by default a file named
122 'local_settings_dynamic.py' that is optimistically loaded if
123 present.
124
125 Yes it's [writing python via ruby](https://github.com/hw-cookbooks/graphite/blob/master/libraries/chef_graphite_python.rb#L14).
126
206440b @webframp Update readme section on Graphite Web resource
webframp authored
127 A runit service definition is provided to [start a uwsgi process](https://github.com/hw-cookbooks/graphite/blob/master/example/graphite_example/recipes/single_node.rb#L105), but note that choice of web server for proxying to the application server is left up to you. No more hard Apache dependency!
128
6f70d81 @webframp README: basic documentation for new resources
webframp authored
129 ### Accumulators
130 Due to the graphite config file format, the data driven resources use
131 an accumulator pattern to find the appropriate resources in the run
132 context and extract provided configuration data. You should never need
133 to use these directly, but you're welcome to go crazy.
134
135 * `graphite_carbon_conf_accumulator`: lookup named carbon resources in
136 run context and gather config
137 * `graphite_storage_conf_accumulator`: lookup named storage schema
138 resources in run context and gather config
139
140 If you look at the
141 [example cookbook recipe](https://github.com/hw-cookbooks/graphite/blob/master/example/graphite_example/recipes/single_node.rb#L6)
142 you probably notice that many of the resources simply take a single `config`
143 attribute, which is basically a hash of the configuration to be written.
144
145 This can come from attributes in a wrapper cookbook or via data bags
146 if you like. Be as creative as you can tolerate.
147
0fde6f2 @webframp README: credit where due for kisoku
webframp authored
148 Accumulator pattern came from excellent work by [Mathieu Sauve-Frankel](https://github.com/kisoku/chef-accumulator)
149
91d6615 @webframp move usage section down in readme
webframp authored
150 ## Usage
151
152 It's a library cookbook, intended to be used in your custom wrapper
153 cookbook to behave as needed. It's the building materials, not the
154 house.
155
a69ba60 @webframp README: add note in usage section about webservers
webframp authored
156 We have purposefully left out web server configuration to remove the
157 dependency, so you're free to use whatever works in your environment.
158 This avoids the need for this cookbook to keep up to date with
159 configuration that isn't really graphite specific.
160
91d6615 @webframp move usage section down in readme
webframp authored
161 For example usage consult the reference cookbook [example](https://github.com/hw-cookbooks/graphite/tree/master/example/graphite_example/recipes)
162
163 Feel free to ask us questions anytime on irc: #heavywater on freenode
164
165 ## Examples
166
167 You can find example usage in the graphite_example cookbook that is included in the [git repository](https://github.com/hw-cookbooks/graphite/blob/master/example/graphite_example/recipes/single_node.rb).
168
6f70d81 @webframp README: basic documentation for new resources
webframp authored
169 ## Data Bags
170
171 Sure, use em if you like. Even encrypt them.
ab34df0 @kleewho Added info about Amazon Web Services compatiblity
kleewho authored
172
a66cd4f @webframp pull in and fixup note about Amazon
webframp authored
173 ## Amazon Web Services
ab34df0 @kleewho Added info about Amazon Web Services compatiblity
kleewho authored
174
a66cd4f @webframp pull in and fixup note about Amazon
webframp authored
175 Due to the old version of Chef used on Amazon Web Services in order to
6f70d81 @webframp README: basic documentation for new resources
webframp authored
176 successfully run this cookbook you may need to add the
a66cd4f @webframp pull in and fixup note about Amazon
webframp authored
177 [`delayed_evaluator`](http://community.opscode.com/cookbooks/delayed_evaluator)
178 recipe to your run list before the `graphite` recipe.
85b5629 @webframp Add contributing section and example cb link
webframp authored
179
180 ## Development / Contributing
181
182 * Source hosted at [GitHub][repo]
183 * Report issues/questions/feature requests on [GitHub Issues][issues]
184
185 Pull requests are very welcome! Make sure your patches are well tested.
186 Ideally create a topic branch for every separate change you make. For
187 example:
188
189 1. Fork the repo
190 2. Create your feature branch (`git checkout -b my-new-feature`)
191 3. Write some tests, see [ChefSpec](https://github.com/sethvargo/chefspec)
7b9bf61 @webframp bump version and fix readme
webframp authored
192 4. Commit your awesome changes (`git commit -am 'Added some feature'`)
85b5629 @webframp Add contributing section and example cb link
webframp authored
193 4. Push to the branch (`git push origin my-new-feature`)
c0977d9 @webframp README: spelling, minor fixes
webframp authored
194 5. Create a new Pull Request and tell us about it your changes.
Something went wrong with that request. Please try again.