Plugin reference¶
When a plugin is invoked with “config” as (the only) argument it is expected to output configuration information for the graph it supports. This output consists of a number of attributes. They are divided into one set of global attributes and then one or more set(s) of datasource-specific attributes. (Things are more complex in the case of Multigraph plugins due to their nested hierarchy.)
Global attributes¶
- Attribute
graph
- Value
yes|no
- Type
optional
- Description
Decides whether to draw the graph.
- See also
- Default
yes
- Attribute
graph_args
- Value
string
- Type
optional
- Description
Arguments for the rrd grapher. This is used to control how the generated graph looks, and how values are interpreted or presented.
- See also
- Default
- Attribute
graph_category
- Value
string (Allowed characters: [a-z0-9-.])
- Type
optional
- Description
- Name of the category used to sort the graphs on the generated index web page.Lower case string as we like a consistent view and want to avoid duplicates.No whitespace as this makes the build of Munin Gallery a lot easier.
- See also
- Default
‘other’
- Attribute
graph_height
- Value
integer (pixel)
- Type
optional
- Description
The height of the graph. Note that this is only the graph’s height and not the height of the whole PNG image.
- See also
- Default
200
- Attribute
graph_info
- Value
html text
- Type
optional
- Description
Provides general information on what the graph shows.
- See also
- Default
- Attribute
graph_order
- Value
space separated list of data sources (fieldnames)
- Type
optional
- Description
- Ensures that the listed fields are displayed in specified order. Any additional fields are added in the order of appearance after fields appearing on this list. This attribute is useful when STACKing data sources with fieldname.draw.It’s also used for loaning data from other data sources (other plugins), which enables Munin to create aggregate or other kinds of combined graphs.
- See also
- Default
None (If not set, the order of the graphs follows the order in which the data sources are read; i.e. the order that the plugin itself provides.)
- Attribute
graph_period
- Value
second|minute|hour
- Type
optional
- Description
- Controls the time unit munin (actually rrd) uses to calculate the average rates of change. Changing the default “second” to “minute” or “hour” is useful in cases of a low frequency of whatever the plugin is measuring.Changing the graph_period makes sense only when the data type is COUNTER or DERIVE.This does not change the sample interval - it remains per default at 5 minutes.
- See also
- Default
second
- Attribute
graph_printf
- Value
Default format string for data source values.
- Type
optional
- Description
- Controls the format munin (actually rrd) uses to display datasource values in the graph legend.
- See also
- Default
“%7.2lf” if –base is 1024, otherwise “%6.2lf”
- Attribute
graph_scale
- Value
yes|no
- Type
optional
- Description
Per default the unit written on the graph will be scaled. So instead of 1000 you will see 1k or 1M for 1000000. You may disable autoscale by setting this to ‘no’.
- See also
- Default
‘yes’
- Attribute
graph_title
- Value
string [a-zA-Z0-9-.]
- Type
required
- Description
Sets the title of the graph
- See also
- Default
The plugin’s file name
- Attribute
graph_total
- Value
string
- Type
optional
- Description
- If set, summarizes all the data sources’ values and reports the results in an extra row in the legend beneath the graph. The value you set here is used as label for that line.Note that, since Munin version 2.1, using the special
undef
keyword disables it (to override in munin.conf). - See also
- Default
- Attribute
graph_vlabel
- Value
string
- Type
optional
- Description
Label for the vertical axis of the graph. Don’t forget to also mention the unit ;)
- See also
- Default
- Attribute
graph_width
- Value
integer (pixel)
- Type
optional
- Description
The width of the graph. Note that this is only the graph’s width and not the width of the whole PNG image.
- See also
- Default
400
- Attribute
host_name
- Value
string [a-zA-Z0-9-.]
- Type
optional
- Description
Fully qualified host name (FQDN). Override the host name for which the plugin is run. Should normally not be set in the plugin. It is meant to be used when the munin-node acts as proxy to monitor remote hosts e.g. per SNMP plugins. In these cases you have to add an own entry for the remote host in the Munin master configuration to pick up these additional host names.
- See also
- Default
Host name as declared in munin.conf.
- Attribute
multigraph
- Value
string
- Type
optional
- Description
- Herewith the plugin tells that it delivers a hierarchy of graphs. The attribute will show up multiple times in the config section, once for each graph that it contains. It announces the name of the graph for which the further configuration attributes then follow.This feature is available since Munin version 1.4.0.
- See also
- Default
- Attribute
update
- Value
yes | no
- Type
optional
- Description
- Decides whether munin-update should fetch data for the graph.Note that the graph will be shown even if updates are disabled and then be blank.
- See also
Set to
no
when dealing with Graph aggregation and/or loaning data.- Default
‘yes’
- Attribute
update_rate
- Value
integer (seconds)
- Type
optional
- Description
- Sets the update_rate used by the Munin master when it creates the RRD file.The update rate is the interval at which the RRD file expects to have data.This attribute requires a Munin master version of at least 2.0.0
- See also
- Default
Data source attributes¶
Notes on field names¶
Each data source in a plugin must be identified by a field name.
The characters must be [a-zA-Z0-9_]
, while the first character must be [a-zA-Z_]
.
Reserved keyword(s): A field must not be named root
. If it’s done Graph generation would be stopped.
In earlier versions of Munin the fieldname may not exceed 19 characters in length. Since munin 1.2 this limit has been circumvented.
Field name attributes¶
- Attribute
{fieldname}.cdef
- Value
CDEF statement
- Type
optional
- Description
- A CDEF statement is a Reverse Polish Notation statement. It can be used here to modify the value(s) before graphing.This is commonly used to calculate percentages. See the FAQ for examples.
- See also
- Default
- Attribute
{fieldname}.colour
- Value
Hexadecimal colour code
- Type
optional
- Description
Custom specification of colour for drawing curve. Available since 1.2.5 and 1.3.3.
- See also
- Default
Selected by order sequence from Munin standard colour set
- Attribute
{fieldname}.critical
- Value
integer or decimal numbers (both may be signed)
- Type
optional
- Description
Can be a max value or a range separated by colon. E.g. “min:”, “:max”, “min:max”, “max”. Used by munin-limits to submit an error code indicating critical state if the value fetched is outside the given range.
- See also
- Default
- Attribute
{fieldname}.draw
- Value
AREA, LINE, LINE[n], STACK, AREASTACK, LINESTACK, LINESTACK[n]
- Type
optional
- Description
- Determines how the data points are displayed in the graph. The “LINE” takes an optional width suffix, commonly “LINE1”, “LINE2”, etc…The *STACK values are specific to munin and makes the first a LINE, LINE[n] or AREA datasource, and the rest as STACK.
- See also
- Default
‘LINE1’ since Munin version 2.0.
- Attribute
{fieldname}.extinfo
- Value
html text
- Type
optional
- Description
Extended information that is included in alert messages (see warning and critical). Since 1.4.0 it is also included in the HTML pages.
- See also
- Default
- Attribute
{fieldname}.graph
- Value
yes|no
- Type
optional
- Description
Determines if the data source should be visible in the generated graph.
- See also
- Default
yes
- Attribute
{fieldname}.info
- Value
html text
- Type
optional
- Description
Explanation on the data source in this field. The Info is displayed in the field description table on the detail web page of the graph.
- See also
- Default
- Attribute
{fieldname}.label
- Value
anything except # and \
- Type
required
- Description
The label used in the legend for the graph on the HTML page.
- See also
- Default
- Attribute
{fieldname}.line
- Value
value:color:label
- Type
optional
- Description
Adds a horizontal line with the specified colour (HRULE) at the value defined. Will not show if outside the graph’s scale.
- See also
- Default
- Example
foo.line 23:FF0080:Foo
- Attribute
{fieldname}.max
- Value
numerical of same data type as the field it belongs to.
- Type
optional
- Description
Sets a maximum value. If the fetched value is above “max”, it will be discarded.
- See also
- Default
- Attribute
{fieldname}.min
- Value
numerical of same data type as the field it belongs to.
- Type
optional
- Description
Sets a minimum value. If the fetched value is below “min”, it will be discarded.
- See also
- Default
- Attribute
{fieldname}.negative
- Value
{fieldname} of related field.
- Type
optional
- Description
You need this for a “mirrored” graph. Values of the named field will be drawn below the X-axis then (e.g. plugin
if_
that shows traffic going in and out as mirrored graph).- See also
See the Best Current Practices for good plugin graphs for examples
- Default
- Attribute
{fieldname}.stack
- Value
List of field declarations referencing the data sources from other plugins by their virtual path. (FIXME: Explanation on topic “virtual path” should be added elsewhere to set a link to it here)
- Type
optional
- Description
Function for creating stacked graphs.
- See also
How do I use fieldname.stack? and Graph aggregation stacking example
- Default
- Attribute
{fieldname}.sum
- Value
List of fields to summarize. If the fields are loaned from other plugins they have to be referenced by their virtual path. (FIXME: Explanation on topic “virtual path” should be added elsewhere to set a link to it here)
- Type
optional
- Description
Function for creating summary graphs.
- See also
How do I use fieldname.sum? and Graph aggregation by example
- Default
- Attribute
{fieldname}.type
- Value
GAUGE|COUNTER|DERIVE|ABSOLUTE
- Type
optional
- Description
Sets the RRD Data Source Type for this field. The values must be written in capitals. The type used may introduce restrictions for
{fieldname.value}
.- See also
- Default
GAUGE
Note
COUNTER is now considered harmful because you can’t specify the wraparound value. The same effect can be achieved with a DERIVE type, coupled with a min 0
.
- Attribute
{fieldname}.unknown_limit
- Value
positive integer
- Type
optional
- Description
Defines the number of unknown values to be received successively, before the state of the dataset changes from ok to unknown. Use a higher value, if you want to tolerate a certain number of non-computable values, before an alarm should be raised. This attribute is available since Munin 3.0.
- See also
- Default
3
- Attribute
{fieldname}.warning
- Value
integer or decimal numbers (both may be signed)
- Type
optional
- Description
Can be a max value or a range separated by colon. E.g. “min:”, “:max”, “min:max”, “max”. Used by munin-limits to submit an error code indicating warning state if the value fetched is outside the given range.
- See also
- Default
On a data fetch run, the plugin is called with no arguments. the following fields are used.
- Attribute
{fieldname}.value
- Value
integer, decimal numbers, or “U” (may be signed). For DERIVE and COUNTER values this must be an integer. See rrdcreate for restrictions.
- Type
required
- Description
The value to be graphed.
- See also
- Default
No default
Example¶
This is an example of the plugin fields used with the “df” plugin. The “munin-run” command is used to run the plugin from the command line.
Configuration run¶
# munin-run df config
graph_title Filesystem usage (in %)
graph_args --upper-limit 100 -l 0
graph_vlabel %
graph_category disk
graph_info This graph shows disk usage on the machine.
_dev_hda1.label /
_dev_hda1.info / (ext3) -> /dev/hda1
_dev_hda1.warning 92
_dev_hda1.critical 98
Data fetch run¶
# munin-run df
_dev_hda1.value 83