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 (RRGGBB)

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