| 1 |
<?xml version="1.0" ?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml"> |
| 4 |
<head> |
| 5 |
<title>Ganglia Monitoring Daemon v3.7.2 Configuration</title> |
| 6 |
<meta http-equiv="content-type" content="text/html; charset=utf-8" /> |
| 7 |
<link rev="made" href="mailto:root@localhost" /> |
| 8 |
</head> |
| 9 |
|
| 10 |
<body style="background-color: white"> |
| 11 |
<table border="0" width="100%" cellspacing="0" cellpadding="3"> |
| 12 |
<tr><td class="block" style="background-color: #cccccc" valign="middle"> |
| 13 |
<big><strong><span class="block"> Ganglia Monitoring Daemon v3.7.2 Configuration</span></strong></big> |
| 14 |
</td></tr> |
| 15 |
</table> |
| 16 |
|
| 17 |
|
| 18 |
<!-- INDEX BEGIN --> |
| 19 |
<div name="index"> |
| 20 |
<p><a name="__index__"></a></p> |
| 21 |
|
| 22 |
<ul> |
| 23 |
|
| 24 |
<li><a href="#name">NAME</a></li> |
| 25 |
<li><a href="#description">DESCRIPTION</a></li> |
| 26 |
<li><a href="#sections_and_attributes">SECTIONS AND ATTRIBUTES</a></li> |
| 27 |
<ul> |
| 28 |
|
| 29 |
<li><a href="#cluster">cluster</a></li> |
| 30 |
<li><a href="#host">host</a></li> |
| 31 |
<li><a href="#globals">globals</a></li> |
| 32 |
<li><a href="#udp_send_channel">udp_send_channel</a></li> |
| 33 |
<li><a href="#udp_recv_channel">udp_recv_channel</a></li> |
| 34 |
<li><a href="#tcp_accept_channel">tcp_accept_channel</a></li> |
| 35 |
<li><a href="#collection_group">collection_group</a></li> |
| 36 |
<li><a href="#modules">Modules</a></li> |
| 37 |
<li><a href="#sflow">sFlow</a></li> |
| 38 |
<li><a href="#include">Include</a></li> |
| 39 |
</ul> |
| 40 |
|
| 41 |
<li><a href="#access_control">ACCESS CONTROL</a></li> |
| 42 |
<li><a href="#example">EXAMPLE</a></li> |
| 43 |
<li><a href="#see_also">SEE ALSO</a></li> |
| 44 |
<li><a href="#notes">NOTES</a></li> |
| 45 |
<li><a href="#copyright">COPYRIGHT</a></li> |
| 46 |
</ul> |
| 47 |
|
| 48 |
<hr name="index" /> |
| 49 |
</div> |
| 50 |
<!-- INDEX END --> |
| 51 |
|
| 52 |
<p> |
| 53 |
</p> |
| 54 |
<hr /> |
| 55 |
<h1><a name="name">NAME</a></h1> |
| 56 |
<p><strong>gmond.conf</strong> - configuration file for ganglia monitoring |
| 57 |
daemon (gmond)</p> |
| 58 |
<p> |
| 59 |
</p> |
| 60 |
<hr /> |
| 61 |
<h1><a name="description">DESCRIPTION</a></h1> |
| 62 |
<p>The gmond.conf file is used to configure the ganglia |
| 63 |
monitoring daemon (gmond) which is part of the <strong>Ganglia |
| 64 |
Distributed Monitoring System</strong>.</p> |
| 65 |
<p> |
| 66 |
</p> |
| 67 |
<hr /> |
| 68 |
<h1><a name="sections_and_attributes">SECTIONS AND ATTRIBUTES</a></h1> |
| 69 |
<p>All sections and attributes are case-insensitive. For example, |
| 70 |
<strong>name</strong> or <strong>NAME</strong> or <strong>Name</strong> or <strong>NaMe</strong> are all equivalent.</p> |
| 71 |
<p>Some sections can be included in the configuration file multiple |
| 72 |
times and some sections are singular. For example, you can |
| 73 |
have only one <strong>cluster</strong> section to define the attributes of |
| 74 |
the cluster being monitored; however, you can have multiple |
| 75 |
<strong>udp_recv_channel</strong> sections to allow gmond to receive message |
| 76 |
on multiple UDP channels.</p> |
| 77 |
<p> |
| 78 |
</p> |
| 79 |
<h2><a name="cluster">cluster</a></h2> |
| 80 |
<p>There should only be one <strong>cluster</strong> section defined. This |
| 81 |
section controls how gmond reports the attributes of the |
| 82 |
cluster that it is part of.</p> |
| 83 |
<p>The <strong>cluster</strong> section has four attributes: <strong>name</strong>, |
| 84 |
<strong>owner</strong>, <strong>latlong</strong> and <strong>url</strong>.</p> |
| 85 |
<p>For example,</p> |
| 86 |
<pre> |
| 87 |
cluster { |
| 88 |
name = "Millennium Cluster" |
| 89 |
owner = "UC Berkeley CS Dept." |
| 90 |
latlong = "N37.37 W122.23" |
| 91 |
url = "<a href="http://www.millennium.berkeley.edu/"">http://www.millennium.berkeley.edu/"</a>; |
| 92 |
}</pre> |
| 93 |
<p>The <strong>name</strong> attributes specifies the name of the cluster of |
| 94 |
machines. The <strong>owner</strong> tag specifies the administrators of |
| 95 |
the cluster. The pair <strong>name</strong>/<strong>owner</strong> should be unique |
| 96 |
to all clusters in the world.</p> |
| 97 |
<p>The <strong>latlong</strong> attribute is the latitude and longitude GPS |
| 98 |
coordinates of this cluster on earth. Specified to 1 mile |
| 99 |
accuracy with two decimal places per axis in decimal.</p> |
| 100 |
<p>The <strong>url</strong> for more information on the <strong>cluster</strong>. |
| 101 |
Intended to give purpose, owner, administration, and account details |
| 102 |
for this cluster.</p> |
| 103 |
<p>There directives directly control the XML output of gmond. For |
| 104 |
example, the cluster configuration example above would translate |
| 105 |
into the following XML.</p> |
| 106 |
<pre> |
| 107 |
<CLUSTER NAME="Millennium Cluster" OWNER="UC Berkeley CS Dept." |
| 108 |
LATLONG="N37.37 W122.23" URL="<a href="http://www.millennium.berkeley.edu/">http://www.millennium.berkeley.edu/</a>"> |
| 109 |
... |
| 110 |
</CLUSTER></pre> |
| 111 |
<p> |
| 112 |
</p> |
| 113 |
<h2><a name="host">host</a></h2> |
| 114 |
<p>The <strong>host</strong> section provides information about the host running this |
| 115 |
instance of <strong>gmond</strong>. Currently only the <strong>location</strong> string attribute is |
| 116 |
supported. Example:</p> |
| 117 |
<pre> |
| 118 |
host { |
| 119 |
location = "1,2,3" |
| 120 |
}</pre> |
| 121 |
<p>The numbers represent Rack, Rank and Plane respectively.</p> |
| 122 |
<p> |
| 123 |
</p> |
| 124 |
<h2><a name="globals">globals</a></h2> |
| 125 |
<p>The <strong>globals</strong> section controls general characteristics of gmond |
| 126 |
such as whether is should daemonize, what user it should run as, |
| 127 |
whether is should send/receive date and such. The <strong>globals</strong> |
| 128 |
section has the following attributes: <strong>daemonize</strong>, <strong>setuid</strong>, <strong>user</strong>, |
| 129 |
<strong>debug_level</strong>, <strong>mute</strong>, <strong>deaf</strong>, <strong>allow_extra_data</strong>, <strong>host_dmax</strong>, |
| 130 |
<strong>host_tmax</strong>, <strong>cleanup_threshold</strong>, <strong>gexec</strong>, <strong>send_metadata_interval</strong> |
| 131 |
and <strong>module_dir</strong>.</p> |
| 132 |
<p>For example,</p> |
| 133 |
<pre> |
| 134 |
globals { |
| 135 |
daemonize = true |
| 136 |
setuid = true |
| 137 |
user = nobody |
| 138 |
host_dmax = 3600 |
| 139 |
host_tmax = 40 |
| 140 |
}</pre> |
| 141 |
<p>The <strong>daemonize</strong> attribute is a boolean. When true, <strong>gmond</strong> will |
| 142 |
daemonize. When false, <strong>gmond</strong> will run in the foreground.</p> |
| 143 |
<p>The <strong>setuid</strong> attribute is a boolean. When true, <strong>gmond</strong> will |
| 144 |
set its effective UID to the uid of the user specified by the <strong>user</strong> |
| 145 |
attribute. When false, <strong>gmond</strong> will not change its effective user.</p> |
| 146 |
<p>The <strong>debug_level</strong> is an integer value. When set to zero (0), <strong>gmond</strong> |
| 147 |
will run normally. A <strong>debug_level</strong> greater than zero will result in |
| 148 |
<strong>gmond</strong> running in the foreground and outputting debugging information. |
| 149 |
The higher the <strong>debug_level</strong> the more verbose the output.</p> |
| 150 |
<p>The <strong>mute</strong> attribute is a boolean. When true, <strong>gmond</strong> will not |
| 151 |
send data regardless of any other configuration directives.</p> |
| 152 |
<p>The <strong>deaf</strong> attribute is a boolean. When true, <strong>gmond</strong> will not |
| 153 |
receive data regardless of any other configuration directives.</p> |
| 154 |
<p>The <strong>allow_extra_data</strong> attribute is a boolean. When false, <strong>gmond</strong> will |
| 155 |
not send out the EXTRA_ELEMENT and EXTRA_DATA parts of the XML. This might |
| 156 |
be useful if you are using your own frontend to the metric data and will |
| 157 |
like to save some bandwith.</p> |
| 158 |
<p>The <strong>host_dmax</strong> value is an integer with units in seconds. When set |
| 159 |
to zero (0), <strong>gmond</strong> will never delete a host from its list even when |
| 160 |
a remote host has stopped reporting. If <strong>host_dmax</strong> is set to a |
| 161 |
positive number then <strong>gmond</strong> will flush a host after it has not heard |
| 162 |
from it for <strong>host_dmax</strong> seconds. By the way, dmax means "delete max".</p> |
| 163 |
<p>The <strong>host_tmax</strong> value is an integer with units in seconds. This value |
| 164 |
represents the maximum amount of time that <strong>gmond</strong> should wait between |
| 165 |
updates from a host. As messages may get lost in the network, <strong>gmond</strong> |
| 166 |
will consider the host as being down if it has not received any messages |
| 167 |
from it after 4 times this value. For example, if <strong>host_tmax</strong> is set |
| 168 |
to 20, the host will appear as down after 80 seconds with no messages |
| 169 |
from it. By the way, tmax means "timeout max".</p> |
| 170 |
<p>The <strong>cleanup_threshold</strong> is the minimum amount of time before gmond |
| 171 |
will cleanup any hosts or metrics where <strong>tn</strong> > <strong>dmax</strong> a.k.a. expired |
| 172 |
data.</p> |
| 173 |
<p>The <strong>gexec</strong> boolean allows you to specify whether gmond will announce |
| 174 |
the hosts availability to run gexec jobs. <strong>Note</strong>: this requires |
| 175 |
that <strong>gexecd</strong> is running on the host and the proper keys have been |
| 176 |
installed.</p> |
| 177 |
<p>The <strong>send_metadata_interval</strong> establishes an interval in which gmond |
| 178 |
will send or resend the metadata packets that describe each enabled |
| 179 |
metric. This directive by default is set to 0 which means that gmond will |
| 180 |
only send the metadata packets at startup and upon request from other |
| 181 |
gmond nodes running remotely. If a new machine running gmond is added |
| 182 |
to a cluster, it needs to announce itself and inform all other nodes of the |
| 183 |
metrics that it currently supports. In multicast mode, this isn't a problem |
| 184 |
because any node can request the metadata of all other nodes in the cluster. |
| 185 |
However in unicast mode, a resend interval must be established. The interval |
| 186 |
value is the minimum number of seconds between resends.</p> |
| 187 |
<p>The <strong>override_hostname</strong> and <strong>override_ip</strong> parameters allow an arbitrary |
| 188 |
hostname and/or IP (hostname can be optionally specified without IP) to |
| 189 |
use when identifying metrics coming from this host.</p> |
| 190 |
<p>The <strong>module_dir</strong> is an optional parameter indicating the directory where |
| 191 |
the DSO modules are to be located. If absent, the value to use is set at |
| 192 |
configure time with the --with-moduledir option which will default if omitted |
| 193 |
to the a subdirectory named "ganglia" in the directory where libganglia will |
| 194 |
be installed.</p> |
| 195 |
<p>For example, in a 32-bit Intel compatible Linux host that is usually:</p> |
| 196 |
<pre> |
| 197 |
/usr/lib/ganglia</pre> |
| 198 |
<p> |
| 199 |
</p> |
| 200 |
<h2><a name="udp_send_channel">udp_send_channel</a></h2> |
| 201 |
<p>You can define as many <strong>udp_send_channel</strong> sections as you like within |
| 202 |
the limitations of memory and file descriptors. If <strong>gmond</strong> is configured |
| 203 |
as <strong>mute</strong> this section will be ignored.</p> |
| 204 |
<p>The <strong>udp_send_channel</strong> has a total of seven attributes: <strong>mcast_join</strong>, |
| 205 |
<strong>mcast_if</strong>, <strong>host</strong>, <strong>port</strong>, <strong>ttl</strong>, <strong>bind</strong> and <strong>bind_hostname</strong>. |
| 206 |
<strong>bind</strong> and <strong>bind_hostname</strong> are mutually exclusive.</p> |
| 207 |
<p>For example, the 2.5.x version gmond would send on the following single channel |
| 208 |
by default...</p> |
| 209 |
<pre> |
| 210 |
udp_send_channel { |
| 211 |
mcast_join = 239.2.11.71 |
| 212 |
port = 8649 |
| 213 |
}</pre> |
| 214 |
<p>The <strong>mcast_join</strong> and <strong>mcast_if</strong> attributes are optional. When specified |
| 215 |
<strong>gmond</strong> will create the UDP socket and join the <strong>mcast_join</strong> multicast group |
| 216 |
and send data out the interface specified by <strong>mcast_if</strong>.</p> |
| 217 |
<p>You can use the <strong>bind</strong> attribute to bind to a particular local address to |
| 218 |
be used as the source for the multicast packets sent or let gmond resolve the |
| 219 |
default hostname if <strong>bind_hostname</strong> = yes.</p> |
| 220 |
<p>If only a <strong>host</strong> and <strong>port</strong> are specified then <strong>gmond</strong> will send unicast UDP |
| 221 |
messages to the hosts specified.</p> |
| 222 |
<p>You could specify multiple unicast hosts for redundancy as <strong>gmond</strong> will send |
| 223 |
UDP messages to all UDP channels.</p> |
| 224 |
<p>Be careful though not to mix multicast and unicast attributes in the same |
| 225 |
udp_send_channel definition.</p> |
| 226 |
<p>For example...</p> |
| 227 |
<pre> |
| 228 |
udp_send_channel { |
| 229 |
host = host.foo.com |
| 230 |
port = 2389 |
| 231 |
} |
| 232 |
udp_send_channel { |
| 233 |
host = 192.168.3.4 |
| 234 |
port = 2344 |
| 235 |
}</pre> |
| 236 |
<p>would configure gmond to send messages to two hosts. The <strong>host</strong> specification |
| 237 |
can be an IPv4/IPv6 address or a resolvable hostname.</p> |
| 238 |
<p>The <strong>ttl</strong> attribute lets you modify the Time-To-Live (TTL) of outgoing messages |
| 239 |
(unicast or multicast).</p> |
| 240 |
<p> |
| 241 |
</p> |
| 242 |
<h2><a name="udp_recv_channel">udp_recv_channel</a></h2> |
| 243 |
<p>You can specify as many <strong>udp_recv_channel</strong> sections as you like within the |
| 244 |
limits of memory and file descriptors. If <strong>gmond</strong> is configured <strong>deaf</strong> |
| 245 |
this attribute will be ignored.</p> |
| 246 |
<p>The <strong>udp_recv_channel</strong> section has following attributes: |
| 247 |
<strong>mcast_join</strong>, <strong>bind</strong>, <strong>port</strong>, <strong>mcast_if</strong>, <strong>family</strong>, <strong>retry_bind</strong> |
| 248 |
and <strong>buffer</strong>. |
| 249 |
The <strong>udp_recv_channel</strong> can also have an <strong>acl</strong> definition (see |
| 250 |
ACCESS CONTROL LISTS below).</p> |
| 251 |
<p>For example, the 2.5.x gmond ran with a single udp receive channel...</p> |
| 252 |
<pre> |
| 253 |
udp_recv_channel { |
| 254 |
mcast_join = 239.2.11.71 |
| 255 |
bind = 239.2.11.71 |
| 256 |
port = 8649 |
| 257 |
}</pre> |
| 258 |
<p>The <strong>mcast_join</strong> and <strong>mcast_if</strong> should only be used if you want to |
| 259 |
have this UDP channel receive multicast packets the multicast |
| 260 |
group <strong>mcast_join</strong> on interface <strong>mcast_if</strong>. If you do not specify |
| 261 |
multicast attributes then <strong>gmond</strong> will simply create a UDP server |
| 262 |
on the specified <strong>port</strong>.</p> |
| 263 |
<p>You can use the <strong>bind</strong> attribute to bind to a particular local address.</p> |
| 264 |
<p>The family address is set to <strong>inet4</strong> by default. If you want to bind |
| 265 |
the port to an <strong>inet6</strong> port, you need to specify that in the family |
| 266 |
attribute. Ganglia will not allow IPV6=>IPV4 mapping (for portability |
| 267 |
and security reasons). If you want to listen on both <strong>inet4</strong> and |
| 268 |
<strong>inet6</strong> for a particular port, explicitly state it with the following:</p> |
| 269 |
<pre> |
| 270 |
udp_recv_channel { |
| 271 |
port = 8666 |
| 272 |
family = inet4 |
| 273 |
} |
| 274 |
udp_recv_channel { |
| 275 |
port = 8666 |
| 276 |
family = inet6 |
| 277 |
}</pre> |
| 278 |
<p>If you specify a bind address, the family of that address takes precedence. |
| 279 |
f your IPv6 stack doesn't support IPV6_V6ONLY, a warning will be issued |
| 280 |
but gmond will continue working (this should rarely happen).</p> |
| 281 |
<p>Multicast Note: for multicast, specifying a <strong>bind</strong> address with the same |
| 282 |
value used for <strong>mcast_join</strong> will prevent unicast UDP messages to the same |
| 283 |
<strong>port</strong> from being processed.</p> |
| 284 |
<p>The sFlow protocol (see <a href="http://www.sflow.org)">http://www.sflow.org)</a> can be used to collect |
| 285 |
a standard set of performance metrics from servers. For servers that |
| 286 |
don't include embedded sFlow agents, an open source sFlow agent is available |
| 287 |
on SourceForge (see <a href="http://host-sflow.sourceforge.net).">http://host-sflow.sourceforge.net).</a></p> |
| 288 |
<p>To configure <strong>gmond</strong> to receive sFlow datagrams, simply |
| 289 |
add a <strong>udp_recv_channel</strong> with the <strong>port</strong> set to 6343 (the IANA registered |
| 290 |
port for sFlow):</p> |
| 291 |
<pre> |
| 292 |
udp_recv_channel { |
| 293 |
port = 6343 |
| 294 |
}</pre> |
| 295 |
<p>Note: sFlow is unicast protocol, so don't include <strong>mcast_join</strong> join. |
| 296 |
Note: To use some other port for sFlow, set it here and then specify the port |
| 297 |
in an <strong>sflow</strong> section (see below).</p> |
| 298 |
<p><strong>gmond</strong> will fail to run if it can't bind to all defined |
| 299 |
<strong>udp_recv_channel</strong>s. Sometimes, on machines configured by DHCP, |
| 300 |
for example, the <strong>gmond</strong> daemon starts before a network address is |
| 301 |
assigned to the interface. Consequently, the bind fails and the |
| 302 |
<strong>gmond</strong> daemon does not run. To assist in this situation, the |
| 303 |
boolean parameter <strong>retry_bind</strong> can be set to the value <strong>true</strong> |
| 304 |
and then the daemon will not abort on failure, it will enter a |
| 305 |
loop and repeat the bind attempt every 60 seconds:</p> |
| 306 |
<pre> |
| 307 |
udp_recv_channel { |
| 308 |
port = 6343 |
| 309 |
retry_bind = true |
| 310 |
}</pre> |
| 311 |
<p>If you have a large system with lots of metrics, you might experience |
| 312 |
UDP drops. This happens when <strong>gmond</strong> is not able to process the UDP |
| 313 |
fast enough from the network. In this case you might consider changing |
| 314 |
your setup into a more distributed setup using aggregator <strong>gmond</strong> hosts. |
| 315 |
Alternatively you can choose to create a bigger receive <strong>buffer</strong>:</p> |
| 316 |
<pre> |
| 317 |
udp_recv_channel { |
| 318 |
port = 6343 |
| 319 |
buffer = 10485760 |
| 320 |
} |
| 321 |
B<buffer> is specified in bytes, i.e.: 10485760 will allow 10MB UDP |
| 322 |
to be buffered in memory.</pre> |
| 323 |
<p>Note: increasing buffer size will increase memory usage by <strong>gmond</strong></p> |
| 324 |
<p> |
| 325 |
</p> |
| 326 |
<h2><a name="tcp_accept_channel">tcp_accept_channel</a></h2> |
| 327 |
<p>You can specify as many <strong>tcp_accept_channel</strong> sections as you like |
| 328 |
within the limitations of memory and file descriptors. If <strong>gmond</strong> |
| 329 |
is configured to be <strong>mute</strong>, then these sections are ignored.</p> |
| 330 |
<p>The <strong>tcp_accept_channel</strong> has the following attributes: <strong>bind</strong>, <strong>port</strong>, |
| 331 |
<strong>interface</strong>, <strong>family</strong> and <strong>timeout</strong>. A <strong>tcp_accept_channel</strong> may also have |
| 332 |
an <strong>acl</strong> section specified (see ACCESS CONTROL LISTS below).</p> |
| 333 |
<p>For example, 2.5.x gmond would accept connections on a single TCP |
| 334 |
channel.</p> |
| 335 |
<pre> |
| 336 |
tcp_accept_channel { |
| 337 |
port = 8649 |
| 338 |
}</pre> |
| 339 |
<p>The <strong>bind</strong> address is optional and allows you to specify which |
| 340 |
local address <strong>gmond</strong> will bind to for this channel.</p> |
| 341 |
<p>The <strong>port</strong> is an integer than specifies which port to answer |
| 342 |
requests for data.</p> |
| 343 |
<p>The <strong>family</strong> address is set to <strong>inet4</strong> by default. If you want to bind |
| 344 |
the port to an <strong>inet6</strong> port, you need to specify that in the family |
| 345 |
attribute. Ganglia will not allow IPV6=>IPV4 mapping (for portability |
| 346 |
and security reasons). If you want to listen on both <strong>inet4</strong> and |
| 347 |
<strong>inet6</strong> for a particular port, explicitly state it with the following:</p> |
| 348 |
<pre> |
| 349 |
tcp_accept_channel { |
| 350 |
port = 8666 |
| 351 |
family = inet4 |
| 352 |
} |
| 353 |
tcp_accept_channel { |
| 354 |
port = 8666 |
| 355 |
family = inet6 |
| 356 |
}</pre> |
| 357 |
<p>If you specify a bind address, the family of that address takes precedence. |
| 358 |
If your IPv6 stack doesn't support IPV6_V6ONLY, a warning will be issued |
| 359 |
but gmond will continue working (this should rarely happen).</p> |
| 360 |
<p>The <strong>timeout</strong> attribute allows you to specify how many microseconds to block |
| 361 |
before closing a connection to a client. The default is set to -1 (blocking |
| 362 |
IO) and will never abort a connection regardless of how slow the client is |
| 363 |
in fetching the report data.</p> |
| 364 |
<p>The <strong>interface</strong> is not implemented at this time (use <strong>bind</strong>).</p> |
| 365 |
<p> |
| 366 |
</p> |
| 367 |
<h2><a name="collection_group">collection_group</a></h2> |
| 368 |
<p>You can specify as many <strong>collection_group</strong> section as you like |
| 369 |
within the limitations of memory. A <strong>collection_group</strong> has |
| 370 |
the following attributes: <strong>collect_once</strong>, <strong>collect_every</strong> |
| 371 |
and <strong>time_threshold</strong>. A <strong>collection_group</strong> must also contain one |
| 372 |
or more <strong>metric</strong> sections.</p> |
| 373 |
<p>The <strong>metric</strong> section has the following attributes: (one of <strong>name</strong> |
| 374 |
or <strong>name_match</strong>; <strong>name_match</strong> is only permitted if pcre support is |
| 375 |
compiled in), <strong>value_threshold</strong> and <strong>title</strong>. For a list of |
| 376 |
available metric names, run the following command:</p> |
| 377 |
<pre> |
| 378 |
% gmond -m</pre> |
| 379 |
<p>Here is an example of a collection group for a static metric...</p> |
| 380 |
<pre> |
| 381 |
collection_group { |
| 382 |
collect_once = yes |
| 383 |
time_threshold = 1800 |
| 384 |
metric { |
| 385 |
name = "cpu_num" |
| 386 |
title = "Number of CPUs" |
| 387 |
} |
| 388 |
}</pre> |
| 389 |
<p>This <strong>collection_group</strong> entry would cause gmond to collect the |
| 390 |
<strong>cpu_num</strong> metric once at startup (since the number of CPUs will not |
| 391 |
change between reboots). The metric <strong>cpu_num</strong> would be send |
| 392 |
every 1/2 hour (1800 seconds). The default value for the <strong>time_threshold</strong> |
| 393 |
is 3600 seconds if no <strong>time_threshold</strong> is specified.</p> |
| 394 |
<p>The <strong>time_threshold</strong> is the maximum amount of time that can pass before |
| 395 |
gmond sends all <strong>metric</strong>s specified in the <strong>collection_group</strong> to all |
| 396 |
configured <strong>udp_send_channel</strong>s. A <strong>metric</strong> may be sent before this |
| 397 |
<strong>time_threshold</strong> is met if during collection the value surpasses the |
| 398 |
<strong>value_threshold</strong> (explained below).</p> |
| 399 |
<p>Here is an example of a collection group for a volatile metric...</p> |
| 400 |
<pre> |
| 401 |
collection_group { |
| 402 |
collect_every = 60 |
| 403 |
time_threshold = 300 |
| 404 |
metric { |
| 405 |
name = "cpu_user" |
| 406 |
value_threshold = 5.0 |
| 407 |
title = "CPU User" |
| 408 |
} |
| 409 |
metric { |
| 410 |
name = "cpu_idle" |
| 411 |
value_threshold = 10.0 |
| 412 |
title = "CPU Idle" |
| 413 |
} |
| 414 |
}</pre> |
| 415 |
<p>This collection group would collect the <strong>cpu_user</strong> and <strong>cpu_idle</strong> metrics |
| 416 |
every 60 seconds (specified in <strong>collect_every</strong>). If <strong>cpu_user</strong> varies by |
| 417 |
5.0% or <strong>cpu_idle</strong> varies by 10.0%, then the entire <strong>collection_group</strong> |
| 418 |
is sent. If no <strong>value_threshold</strong> is triggered within <strong>time_threshold</strong> |
| 419 |
seconds (in this case 300), the entire <strong>collection_group</strong> is sent.</p> |
| 420 |
<p>Each time the metric value is collected the new value is compared with |
| 421 |
the old value collected. If the difference between the last value and |
| 422 |
the current value is greater than the <strong>value_threshold</strong>, the entire |
| 423 |
collection group is send to the <strong>udp_send_channel</strong>s defined.</p> |
| 424 |
<p>It's important to note that all metrics in a collection group are sent |
| 425 |
even when only a single <strong>value_threshold</strong> is surpassed.</p> |
| 426 |
<p>In addition a user friendly title can be substituted for the metric name |
| 427 |
by including a <strong>title</strong> within the <strong>metric</strong> section.</p> |
| 428 |
<p>By using the <strong>name_match</strong> parameter instead of <strong>name</strong>, it is possible |
| 429 |
to use a single definition to configure multiple metrics that match a |
| 430 |
regular expression. The perl compatible regular expression (pcre) syntax |
| 431 |
is used. This approach is particularly useful for a series of metrics |
| 432 |
that may vary in number between reboots (e.g. metric names that |
| 433 |
are generated for each individual NIC or CPU core).</p> |
| 434 |
<p>Here is an example of using the <strong>name_match</strong> directive to enable |
| 435 |
the multicpu metrics:</p> |
| 436 |
<pre> |
| 437 |
metric { |
| 438 |
name_match = "multicpu_([a-z]+)([0-9]+)" |
| 439 |
value_threshold = 1.0 |
| 440 |
title = "CPU-\\2 \\1" |
| 441 |
}</pre> |
| 442 |
<p>Note that in the example above, there are two matches: the alphabetical |
| 443 |
match matches the variations of the metric name (e.g. <strong>idle</strong>, <strong>system</strong>) |
| 444 |
while the numeric match matches the CPU core number. The second thing |
| 445 |
to note is the use of substitutions within the argument to <strong>title</strong>.</p> |
| 446 |
<p>If both <strong>name</strong> and <strong>name_match</strong> are specified, then <strong>name</strong> is ignored.</p> |
| 447 |
<p> |
| 448 |
</p> |
| 449 |
<h2><a name="modules">Modules</a></h2> |
| 450 |
<p>A <strong>modules</strong> section contains the parameters that are necessary to load a |
| 451 |
metric module. A metric module is a dynamically loadable module that |
| 452 |
extends the available metrics that gmond is able to collect. Each <strong>modules</strong> |
| 453 |
section contains at least one <strong>module</strong> section. Within a <strong>module</strong> section |
| 454 |
are the directives <strong>name</strong>, <strong>language</strong>, <strong>enabled</strong>, <strong>path</strong> and <strong>params</strong>. |
| 455 |
The module <strong>name</strong> is the name of the module as determined by the module |
| 456 |
structure if the module was developed in C/C++. Alternatively, the |
| 457 |
<strong>name</strong> can be the name of the source file if the module has been |
| 458 |
implemented in a interpreted language such as python. A <strong>language</strong> |
| 459 |
designation must be specified as a string value for each module. The |
| 460 |
<strong>language</strong> directive must correspond to the source code language in |
| 461 |
which the module was implemented (ex. language = "python"). If a |
| 462 |
<strong>language</strong> directive does not exist for the module, the assumed |
| 463 |
language will be "C/C++". The <strong>enabled</strong> directive allows a metric module |
| 464 |
to be easily enabled or disabled through the configuration file. If the |
| 465 |
<strong>enabled</strong> directive is not included in the module configuration, the |
| 466 |
enabled state will default to "yes". One thing to note is that if a |
| 467 |
module has been disabled yet the metric which that module implements |
| 468 |
is still listed as part of a collection group, gmond will produce a |
| 469 |
warning message. However gmond will continue to function normally |
| 470 |
by simply ignoring the metric. The <strong>path</strong> is the path from which |
| 471 |
gmond is expected to load the module (C/C++ compiled dynamically |
| 472 |
loadable module only). The <strong>params</strong> directive can be used to pass |
| 473 |
a single string parameter directly to the module initialization |
| 474 |
function (C/C++ module only). Multiple parameters can be passed to |
| 475 |
the module's initialization function by including one or more |
| 476 |
<strong>param</strong> sections. Each <strong>param</strong> section must be named and contain |
| 477 |
a <strong>value</strong> directive. Once a module has been loaded, the additional |
| 478 |
metrics can be discovered by invoking <strong>gmond -m</strong>.</p> |
| 479 |
<pre> |
| 480 |
modules { |
| 481 |
module { |
| 482 |
name = "example_module" |
| 483 |
language = "C/C++" |
| 484 |
enabled = yes |
| 485 |
path = "modexample.so" |
| 486 |
params = "An extra raw parameter" |
| 487 |
param RandomMax { |
| 488 |
value = 75 |
| 489 |
} |
| 490 |
param ConstantValue { |
| 491 |
value = 25 |
| 492 |
} |
| 493 |
} |
| 494 |
}</pre> |
| 495 |
<p> |
| 496 |
</p> |
| 497 |
<h2><a name="sflow">sFlow</a></h2> |
| 498 |
<p>The <strong>sflow</strong> group is optional and has the following optional |
| 499 |
attributes: <strong>udp_port</strong>, <strong>accept_vm_metrics</strong>, <strong>accept_http_metrics</strong>, |
| 500 |
<strong>accept_memcache_metrics</strong>, <strong>accept_jvm_metrics</strong>, |
| 501 |
<strong>multiple_http_instances</strong>,<strong>multiple_memcache_instances</strong>, |
| 502 |
<strong>multiple_jvm_instances</strong>. By default, a |
| 503 |
<strong>udp_recv_channel</strong> on port 6343 (the IANA registered port for |
| 504 |
sFlow) is all that is required to accept and process sFlow |
| 505 |
datagrams. To receive sFlow on some other port requires both |
| 506 |
a <strong>udp_recv_channel</strong> for the other port and a <strong>udp_port</strong> |
| 507 |
setting here. For example:</p> |
| 508 |
<pre> |
| 509 |
udp_recv_channel { |
| 510 |
port = 7343 |
| 511 |
}</pre> |
| 512 |
<pre> |
| 513 |
sflow { |
| 514 |
udp_port = 7343 |
| 515 |
}</pre> |
| 516 |
<p>An sFlow agent running on a hypervisor may also be sending |
| 517 |
metrics for its local virtual machines. By default these |
| 518 |
metrics are ignored, but the <strong>accept_vm_metrics</strong> flag can |
| 519 |
be used to accept those metrics too, and prefix them with |
| 520 |
an identifier for each virtual machine.</p> |
| 521 |
<pre> |
| 522 |
sflow { |
| 523 |
accept_vm_metrics = yes |
| 524 |
}</pre> |
| 525 |
<p>The sFlow feed may also contain metrics sent from HTTP or memcached |
| 526 |
servers, or from Java VMs. Extra options can be used to ignore |
| 527 |
or accept these metrics, and to indicate that there may be multiple |
| 528 |
instances per host. For example:</p> |
| 529 |
<pre> |
| 530 |
sflow { |
| 531 |
accept_http_metrics = yes |
| 532 |
multiple_http_instances = yes |
| 533 |
}</pre> |
| 534 |
<p>will allow the HTTP metrics, and also mark them with a distinguishing |
| 535 |
identifier so that each instance can be trended separately. (If multiple |
| 536 |
instances are reporting and this flag is not set, the results are likely |
| 537 |
to be garbled.)</p> |
| 538 |
<p> |
| 539 |
</p> |
| 540 |
<h2><a name="include">Include</a></h2> |
| 541 |
<p>This directive allows the user to include additional configuration files |
| 542 |
rather than having to add all gmond configuration directives to the |
| 543 |
gmond.conf file. The following example includes any file with the extension |
| 544 |
of .conf contained in the directory conf.d as if the contents of the included |
| 545 |
configuration files were part of the original gmond.conf file. This allows |
| 546 |
the user to modularize their configuration file. One usage example might |
| 547 |
be to load individual metric modules by including module specific .conf files.</p> |
| 548 |
<p>include ('/etc/ganglia/conf.d/*.conf')</p> |
| 549 |
<p> |
| 550 |
</p> |
| 551 |
<hr /> |
| 552 |
<h1><a name="access_control">ACCESS CONTROL</a></h1> |
| 553 |
<p>The <strong>udp_recv_channel</strong> and <strong>tcp_accept_channel</strong> directives |
| 554 |
can contain an Access Control List (ACL). This ACL allows you to specify |
| 555 |
exactly which hosts gmond process data from.</p> |
| 556 |
<p>An example of an <strong>acl</strong> entry looks like</p> |
| 557 |
<pre> |
| 558 |
acl { |
| 559 |
default = "deny" |
| 560 |
access { |
| 561 |
ip = 192.168.0.4 |
| 562 |
mask = 32 |
| 563 |
action = "allow" |
| 564 |
} |
| 565 |
}</pre> |
| 566 |
<p>This ACL will by default reject all traffic that is not specifically from |
| 567 |
host 192.168.0.4 (the mask size for an IPv4 address is 32, the mask size |
| 568 |
for an IPv6 address is 128 to represent a single host).</p> |
| 569 |
<p>Here is another example</p> |
| 570 |
<pre> |
| 571 |
acl { |
| 572 |
default = "allow" |
| 573 |
access { |
| 574 |
ip = 192.168.0.0 |
| 575 |
mask = 24 |
| 576 |
action = "deny" |
| 577 |
} |
| 578 |
access { |
| 579 |
ip = ::ff:1.2.3.0 |
| 580 |
mask = 120 |
| 581 |
action = "deny" |
| 582 |
} |
| 583 |
}</pre> |
| 584 |
<p>This ACL will by default allow all traffic unless it comes from the |
| 585 |
two subnets specified with action = "deny".</p> |
| 586 |
<p> |
| 587 |
</p> |
| 588 |
<hr /> |
| 589 |
<h1><a name="example">EXAMPLE</a></h1> |
| 590 |
<p>The default behavior for a 2.5.x gmond would be specified as...</p> |
| 591 |
<pre> |
| 592 |
udp_recv_channel { |
| 593 |
mcast_join = 239.2.11.71 |
| 594 |
bind = 239.2.11.71 |
| 595 |
port = 8649 |
| 596 |
} |
| 597 |
udp_send_channel { |
| 598 |
mcast_join = 239.2.11.71 |
| 599 |
port = 8649 |
| 600 |
} |
| 601 |
tcp_accept_channel { |
| 602 |
port = 8649 |
| 603 |
}</pre> |
| 604 |
<p>To see the complete default configuration for gmond simply run:</p> |
| 605 |
<pre> |
| 606 |
% gmond -t</pre> |
| 607 |
<p>gmond will print out its default behavior in a configuration file |
| 608 |
and then exit. Capturing this output to a file can serve as |
| 609 |
a useful starting point for creating your own custom configuration.</p> |
| 610 |
<pre> |
| 611 |
% gmond -t > custom.conf</pre> |
| 612 |
<p>edit <strong>custom.conf</strong> to taste and then</p> |
| 613 |
<pre> |
| 614 |
% gmond -c ./custom.conf</pre> |
| 615 |
<p> |
| 616 |
</p> |
| 617 |
<hr /> |
| 618 |
<h1><a name="see_also">SEE ALSO</a></h1> |
| 619 |
<p><code>gmond(1)</code>.</p> |
| 620 |
<p> |
| 621 |
</p> |
| 622 |
<hr /> |
| 623 |
<h1><a name="notes">NOTES</a></h1> |
| 624 |
<p>The ganglia web site is at <a href="http://ganglia.info/.">http://ganglia.info/.</a></p> |
| 625 |
<p> |
| 626 |
</p> |
| 627 |
<hr /> |
| 628 |
<h1><a name="copyright">COPYRIGHT</a></h1> |
| 629 |
<p>Copyright (c) 2005 The University of California, Berkeley</p> |
| 630 |
<table border="0" width="100%" cellspacing="0" cellpadding="3"> |
| 631 |
<tr><td class="block" style="background-color: #cccccc" valign="middle"> |
| 632 |
<big><strong><span class="block"> Ganglia Monitoring Daemon v3.7.2 Configuration</span></strong></big> |
| 633 |
</td></tr> |
| 634 |
</table> |
| 635 |
|
| 636 |
</body> |
| 637 |
|
| 638 |
</html> |