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:rrdgraph_args
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:Well known categories, Plugin Gallery
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:Loaning Data, Aggregate Graphs
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 data
source 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:Using SNMP plugins
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:Multigraph plugins
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:cdeftutorial
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:Let Munin croak alarm
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:rrdgraph
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:rrdgraph
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:Datatypes, rrdcreate
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:Let Munin croak alarm
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:Let Munin croak alarm
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