Pro Puppet (51 page)
Authors: Jeffrey McCune James Turnbull
Thetagmailreport uses these same tags to generate email reports. The tags assigned to your resources are added to the log results and then Puppet generates emails based on matching particular tags with particular email addresses. This matching occurs in a configuration file calledtagmail.conf. By default, thetagmail.conffile is located in$confdirdirectory, usually/etc/puppet. This is controlled by thetagmapconfiguration option in thepuppet.conffile.
[master]
tagmap = $confdir/tagmail.conf
Thetagmail.conffile contains a list of tags and email addresses separated by colons. Multiple tags and email addresses can be specified by separating them with commas. You can see an example of this file in
Listing 9-2
.
Listing 9-2.
A sample tagmail.conf file
all: [email protected]
mail, www: [email protected]
db, !mail: [email protected],[email protected]
The first tag in
Listing 10-2
,all, is a special tag that tells Puppet to send all reports to the specified email address.
Tip
There is a special tag callederr. Specifying this tag will make the report return all error messages generated during a configuration run.
The second set of tags specifies that Puppet should send all reports tagged with the tagsmailandwwwto the email address
[email protected]
. The last tags tell Puppet to send reports for all log entries with thedbtag but not themailtag to both the
[email protected]
and
[email protected]
email addresses. You can see that themailtag has been negated using the!symbol.
One of the more useful built-in report processors is therrdgraphtype, which takes advantage of Tobias Oetiker's RRD graphing libraries. Therrdgraphreport processor generates RRD files, graphs and some HTML files to display those graphs. It is a very quick and easy way of implementing graphs of your Puppet configuration activities.
In order to make use of this report processor we'll first need to install the RRDTools and the Ruby bindings for RRD. We can install RRDTools via package on most platforms and distributions. The Ruby bindings, unfortunately, are less well-supported on a lot of platforms. They can be installed from source, or some distributions do have packages available. There are also suitablerrdtool-rubyRPMs that should work on most RPM-based distributions like Red Hat, CentOS, and Mandriva versions available at Dag Wieer's repository at
http://dag.wieers.com/rpm/packages/rrdtool/
. There is also a development package for Gentoo calledruby-rrdthat provides the required bindings that you should be able to install viaemerge.
You can see a list of the required package for Debian/Ubuntu, Fedora, and Red Hat platforms in
Table 9-1
.
Table 9-1.
Package names for rrdtools
| OS | Packages | ||
| Debian/Ubuntu | rrdtool | librrd2 | librrd2-dev |
| Fedora | rrdtool | rrdtool-ruby | |
| Red Hat | rrdtool | rrdtool-ruby |
Note
Your package manager may prompt you to install additional packages when installing RRDTool.
You can also install the RRD Ruby bindings via one of two gems,RubyRRDtoolorlibrrd:
$ sudo gem install RubyRRDtool
$ sudo gem install librrd
Both gems should work to produce the appropriate RRD graphs.
Lastly, if there is no Ruby bindings package for your platform, you can install the bindings via source. Download the latest bindings package from Rubyforge, unpack it and change into the resulting directory. At the time of writing, the latest version was 0.6.0:
$ wget http://rubyforge.org/frs/download.php/13992/RubyRRDtool-0.6.0.tgz
$ tar -zxf RubyRRDtool-0.6.0.tgz
$ cd RubyRRDtool-0.6.0
$ ruby extconf.rb
$ make
$ sudo make install
To customize RRD support, you can also change some configuration options in thepuppet.confconfiguration file:
[master]
rrddir = $vardir/rrd
rrdinternval = $runinterval
Therrddirdirectory specifies the default location for the generated RRD files. It defaults to$vardir/rrd,which is usually/var/lib/puppet/rrd. Therrdintervalspecifies how often RRD should expect to receive data. This defaults to$runinterval,so as to match how often agents report back to the master.
Underneath the$vardir/rrddirectory, Puppet will create a directory for each agent that reports to the master. Graphs (and the associated HTML files to display them) will be generated in that directory. A graph will be generated for each metric that Puppet collects. You can then serve this directory out using your web server and display the graphs.
The http report processor sends Puppet reports to a HTTP URL and port. The Puppet reports are sent as a YAML dump in the form of a HTTP Post. You can control the destination with thereporturlconfiguration option in thepuppet.confconfiguration file on the master:
[master]
reporturl = http://localhost:3000/reports
Here the report destination is set to its default, which assumes that you are sending reports to Puppet Dashboard.
You are not limited to the provided report processors. Puppet also allows you to create your own report processors. There are two methods for doing this. The first method is to use the existing store reports, which are YAML files, and write an external report processor to make use of this information, for example graphing it or storing it in an external database. This is also how the report importation process works within Puppet Dashboard. These external report processors can easily be written in Ruby to take advantage of Ruby's ability to de-serialize the YAML files and make use of the resulting objects. You can use any tool that supports the importation of third-party YAML data.
The second method involves writing your own report processor and adding it to Puppet. Unlike plug-ins for facts, functions, types and providers, Puppet doesn't have an automatic way to distribute custom reports.
Note
We show how to distribute other forms of custom code, like facts, in
Chapter 10
.
Instead the report processors are stored in thelib/puppet/reportsdirectory. For example, on an Ubuntu Puppet master we'd add our custom report processor to the/usr/local/lib/site_ruby/1.8/puppet/reportsdirectory with the existing report processors. We would then specify the new report in the reports configuration option.
The existing report processors make excellent templates for new processors. In
Listing 10-3
you can see the Ruby code for thehttpreport processor.
Listing 9-3.
The http report processor
require 'puppet'
require 'net/http'
require 'uri'
Puppet::Reports.register_report(:http) do
desc <<-DESC
Send report information via HTTP to the `reporturl`. Each host sends
its report as a YAML dump and this sends this YAML to a client via HTTP POST.
The YAML is the `report` parameter of the request."
DESC
def process
url = URI.parse(Puppet[:reporturl])
req = Net::HTTP::Post.new(url.path)
req.body = self.to_yaml
req.content_type = "application/x-yaml"
Net::HTTP.new(url.host, url.port).start {|http|
http.request(req)
}
end
end
As you can see from this example, it is very easy to create your own report processor.
Tip
Other ideas for Puppet report processors include RSS feeds for new reports, IRC, XMPP or instant messaging, or SMS notifications of new reports. You could also parse particular events in reports or collate metrics for use in other kinds of performance management systems.
First, you need to require Puppet itself:require ‘puppet'. Then you simply specify thePuppet::Reports.register_reportmethod and the name of the new report processor you are creating. You can see a simple example of a report processor in
Listing 9-4
.
Listing 9-4.
A custom summary report
require 'puppet'
Puppet::Reports.register_report(:summary) do
desc <<-DESC
Send summary report information to the report directory."
DESC
def process
client = self.host
summary = self.summary
dir = File.join(Puppet[:reportdir], client)
client = self.host
file = "summary.txt"
destination = File.join(dir, file)
File.open(destination,"w") do |f|
f.write(summary)
end
end
end
In this report processor, we've defined a method calledprocessto hold our report's core logic. We've extracted some information from our report: the host, using theself.hostmethod, and a summary of the changes, using thesummarymethod. You also have access to the report's logs and metrics using theself.logsandself.metricsmethods.
We also wrote our summary report out to a directory named after the Puppet agent host located underneath the reports directory, which we specified using the value of thereportdirconfiguration option.
We would then add our report name to Puppet in thepuppet.confconfiguration file:
