File: new-devices.html

package info (click to toggle)
cricket 1.0.5-9
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 1,480 kB
  • ctags: 390
  • sloc: perl: 8,287; sh: 920; ansic: 318; makefile: 62; sql: 16
file content (175 lines) | stat: -rw-r--r-- 7,694 bytes parent folder | download | duplicates (8)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
  <head>
    <title>Setting up New Devices in Cricket</title>
  </head>
  <body>
    <h1>Setting up New Devices in Cricket</h1>
    <p>
      Cricket is designed to be flexible enough to be able to monitor
      more than just router interfaces. The sample config tree that
      comes with it will help you learn about its capabilities, but to
      monitor other things, you'll need to write your own branches of
      the config tree.
    </p>
    <p>
      Read this document to learn how to get the most from Cricket, by
      teaching it to gather data from all kinds of sources.
    </p>

    <div>
      <h2>Creating Custom Target Types</h2>
      <p>
        Cricket gives you complete control over the contents and
        layout of your RRD files. This means that if you are going
        to be doing any serious target-type hacking, you need to
        understand the following concepts:
      </p>
      <ul>
        <li>Round Robin Array (RRA)
          <p>
            This is where data is stored in an RRD. There is one
            RRA for each scale of data, for example 5 minute
            samples, 30 minute samples, and 2 hour samples. The
            same data is in each RRA, except it is sampled at a
            different rate. If an RRA can hold 12 samples and it
            is updated every 5 minutes, then it holds data
            spanning back one hour. The 13th sample will
            overwrite the 1st sample.  Detailed information
            about RRD is available from <a
            href="http://www.rrdtool.org/manual/">the RRD Tool
            documentation</a> and from the
      <a href="http://www.rrdtool.org/tutorial">RRD Tool tutorials</a>.
          </p>
        </li>
        <li>Data Source
          <p>
            A data source is one line on a graph, or one column
            of data if you think of the RRD as a tabular listing
            of data. One RRD can have many datasources in it.
            All up them must be updated with new data at once.
            Not all of them need to be graphed at once (see the
            information about datasource "views" below).
          </p>
        </li>
        <li>Target
          <p>
            A device that we are keeping stats on is a target.
            There one RRD file on disk for every target. You can
            think of each target as a leaf on the config tree.
          </p>
        </li>
        <li>Target Type
          <p>
            The type of the target determines what kinds of data
            sources and RRA's makes up the target. When Cricket
            goes to update a target, it uses the target type to
            figure out what data to fetch about the target, and
            how to fetch it.
          </p>
        </li>
        <li>Data Source Source (ds-source)
          <p>
            This is the rather unfortunate name for the
            attribute of a data source that tells Cricket
            precisely where to fetch the data from, and which
            data to fetch. Encoded in the ds-source is the
            retrieval method and a description of the data we
            want.
          </p>
        </li>
      </ul>
      <p>
        Now, with all those terms under your belt, you'll understand
        this statement: Using the datasource, RRA, and targetType
        dictionaries, you can completely control the kind, source,
        and quantity of data you store. The RRA's in the
        sample-config reproduce <a href="http://www.mrtg.org/">MRTG
        2.x's</a> data format precisely, and that configuration has
        proven to work well for most needs. If you are going to be
        using Cricket for the jobs it comes ready to do, you'll
        simply need to copy the sample-config tree and make minor
        changes to the targets it specifies.
      </p>
      <p>
        If you need to customize Cricket to talk to other things,
        then you'll be following the following general steps:
      </p>
      <ol>
        <li>
          Create entries in the datasource dictionary that tell
          Cricket how to fetch your new measurement. If you are
          using SNMP, you'll probably want to add an entry to the
          OID dictionary in the same subtree, to make your
          datasource entry readable. For instance, say we wanted
          to use Cricket to talk via SNMP to an agent running on a
          Unix machine, and fetch the load average. We would add
          the OID for the load average to the OID table, then add
          a new entry (named "load-average") to the datasource
          dictionary that described this new datasource.
        </li>
        <li>
          Create a targetType entry to tell Cricket what
          datasources make up your new target-type. Assuming the
          RRA definitions from the <tt>--default--</tt> entry are
          right, you only need to add set the "ds" tag for this
          entry. For the load average example, we'd put
          "ds=load-average" into a targetType entry named
          "unix-machine".
        </li>
        <li>
          Create a new target who's target-type tag is set to the
          targetType you created in the last step. If you are
          using SNMP to talk to the host, you need to make certain
          the variable snmp-host is set (since it contributes to
          the snmp variable, which in turn is required in SNMP
          ds-sources). You could set the snmp-host tag explicitly
          for every tag, but that would be a pain. Instead, you
          could choose your target names to be hostnames, then use
          the auto-target-name to set snmp-host correctly all the
          time, by adding a line like snmp-host =
          %auto-target-name% to the --default-- entry for that
          sub-tree. If you have a rare case in your system where
          the target name is not the name you want to send SNMP
          packets to, then you could override the default
          snmp-host by setting snmp-host directly for that one
          target.
        </li>
        <li>
          Run the collector on your new subtree, using the
          "-loglevel debug" option. This will tell you exactly
          what Cricket thinks things are set to when it tries to
          fetch your data, as well as what exactly happened when
          it went to fetch the data
        </li>
      </ol>
      <p>
        If you come up with an interesting configuration, please
        share it with the Cricket community by submitting it to the
        <a
        href="http://www.certaintysolutions.com/tech-advice/cricket-contrib/">Cricket contrib site</a> hosted by the nice folks at
        <a href="http://www.gnac.com">GNAC</a>.
      </p>
      <p>
        If you need to add a new kind of data gathering subroutine,
        you'll want to read the code to <tt>snmp.pm</tt> very
        carefully and make a module like it to collect your data.
        It's not too hard, but it might not be worth the effort --
        consider using a simple Perl script to let you fetch the
        data via the <tt>exec</tt> method. See the
        <tt>http-performance</tt> sub-tree for an example of how to
        do this.
      </p>
    </div>

    <p>
      <a href="http://cricket.sourceforge.net">Cricket</a>
      version 1.0.5, released 2004-03-28.
    </p>
    <p>
      Copyright (C) 1998-2000 Jeff Allen. Cricket is released under
      the <a href="gpl.html">GNU General Public License</a>.
    </p>
  </body>
</html>