wiki:MuninDataStructure

Introduction

This page describes the functions and data structure as they are in 1.3.4 and later.

This page tries to explain how the internal data structure is constructed, and how you should manipulate it.

Data structure manipulation

Most of these functions take a parameter $hash. This should be a pointer to the object in the $config hash that you are working on.

Some handy functions

munin_get ($hash, $field [, $default])

Seach for $field in the node $hash. Traverse recursively up parent nodes if the field is not defined, until it is found or traversion is attempting to go beyond the root node. If the field is not found, return $default if parameter is supplied, or undef if not.

munin_get_bool ($hash, $field, [, $default])

Same as munin_get, but change return value to 0 or 1 depending on what the variable is set to. Understands most boolean ways of setting configuration items, like true/false, yes/no, 1/0, etc.

munin_set ($hash, $field, $value)

Sets $field to $value in $hash

munin_get_node_name ($hash)

Returns the name of the $hash node.

munin_get_parent ($hash)

Get parent node of $hash, or "none" if there is no such node. (This function is used places where an undef value would break things.)

munin_get_children ($hash)

Get an array of child nodes of $hash

munin_find_field ($hash, $field, $avoid)

Search $hash and its children recursively for the field $field, but avoid recursing into or below nodes containing the $avoid field. Returns an array of hash nodes that match the requirements. Example which finds all hash nodes containing the address field (i.e. nodes we need to connect to): munin_find_field ($config, "address")

munin_get_node_loc ($hash)

Get an array with the path (from root node) to the $hash node.

munin_get_node ($hash, $loc)

Return node object gotten by starting at $hash and traversing down the path described by $loc. Often used in conjunction with munin_get_node_loc.

munin_get_separated_node ($hash)

Return a copy of the $hash node without any of the internal data fields in the regular data structure. The returned hash will not be suited for use in other munin_ functions, but will be better suited for export out of Munin.

Raw in-memory data structure

Generally, you should keep your hands off direct manipulation and access of the data structure, and use the functions specified in the previous section. The one exception is when you're searching for a field in a specific node, without searching up the hierarchy if it isn't found.

The data structure is simply a multi-layered hash. E.g. if your munin.conf says:

[Foo;Bar;Baz;my.node.net]
cpu.system.warning 85

...it will result in the node $config->{Foo}->{Bar}->{Baz}->{my.node.net}->{cpu}->{system}->{warning} being set to "85".

The data hash also contains some fields used for internal purposes, all of which are prepended by #%# to avoid clashing with regular Munin fields.

Stored data structure

The files stored from this data structure datafile and limits in the Munin lib directory) are basically saved in the configuration file format (I.e. the format that munin.conf is in), but without the beautification. :-)

When Munin sees a munin.conf looking like

[Foo;Bar;Baz;my.node.net]
cpu.system.warning 85

...the [] part is simply prepended to each following line, with a delimiter between them. In other words, that is equal to

.Foo;Bar;Baz;my.node.net:cpu.system.warning 85

The leftmost dot "roots" the line, and makes it ignore any prepending [] blocks (if you haven't got any [] furhter up the file, you can safely remove it).

There are two rules dictating which of the three delimiters (".", ":", ";") you can use:

  • There can only be one ":" delimiter in each line
  • There can only be "." delimiters after an ";" delimiter

Most of the lines in the config files generated by Munin will use the ";" delimiter exclusively.

Last modified at 2008-03-02T21:08:05+01:00 Last modified on 2008-03-02T21:08:05+01:00