.. _data-structures:

=================
 Data Structures
=================

The following documentation discusses the flow, handling and storage of data used by the various
Munin components.  This includes partially internal processing details, in order to provide a good
understanding of data structures within Munin for interested developers.


Munin Node
==========

The Munin Node parses its configuration once during startup.


.. _data-structure-node-configuration:

Node Configuration
------------------

The Node configuration specifies the details of the node service, which is responding to requests
from the Munin Master.

The Node configuration is read from plain text files (e.g. ``/etc/munin/munin-node.conf``).
Its content is stored in a simple perl object (usually called ``$config``).
All settings are available as object attributes (e.g. ``$config->{default_plugin_user}``).

Configuration settings with different names (for compatibility over multiple Munin releases) are
normalized while parsing (see ``Munin::Node::Config::_parse_line``). One example for normalization
is ``hostname`` and ``host_name`` - both are normalized to ``fqdn``.


Plugin Configuration
--------------------

During the startup of the Munin Node server, the list of plugins (e.g. below
``/etc/munin/plugins``) is collected once.  Additionally the plugin configuration files
(e.g. below ``/etc/munin/plugin-conf.d``) are parsed.  Afterwards all configuration settings
(including wildcard configurations) for all locally enabled plugins are stored in the hash
``$config->{sconf}``.

Configuration settings for a specific plugin are accessible as a hash (``$config->{sconf}{$plugin_name}``).


Munin Master
============

Periodic operations of the Munin Master are executed by ``munin-cron`` (via ``munin-update`` and ``munin-limits``).
Web resources (html and graphs) are generated by ``munin-html`` and ``munin-graph``. Delivery happens either directly (via CGI) or indirectly via ``munin-httpd``.

Master Configuration
--------------------

The Master configuration specifies the details of the update operation (collecting data from nodes), outbound connection details, resource locations, logging and process management.

The Master configuration is read from plain text files (e.g. ``/etc/munin/munin.conf``) by ``munin-update`` via ``Munin::Master::Update->run()``.
Its content is stored in the :ref:`database storage <data-structure-database>` in table ``param`` (see ``_db_params_update``).

All other processes query the database, whenever they need a configuration setting.


Service Configurations
----------------------

The ``config`` of every plugin is requested periodically via :ref:`Munin's network protocol <network-protocol>`. The resulting information describe the service, as well as its datasets.


.. _data-structure-database:

Database Storage
----------------

The database is used for exchanging information between different parts of munin.
By default the database is an sqlite3 file stored as ``/var/lib/munin/datafile.sqlite``.

Table "param"
^^^^^^^^^^^^^

The *param* table is used for storing Munin Master config parameters. It is populated during every initialization of ``munin-update`` (``Munin::Master::Update::_db_params_update``).

===== =====
Field Value
===== =====
name  name of the configuration setting (e.g. ``logdir``)
value configured value of the configuration setting
===== =====

Every configuration setting is stored in the database. The default value is stored in case of a missing explicit setting.

Table "grp"
^^^^^^^^^^^

The *grp* table contains all group/member relationships. Nodes and groups can be members of groups. Thus hierarchical relationships with multiple levels are supported.

===== =====
Field  Value
===== =====
id    unique ID
p_id  ID of parent group (special group ``0``: this group has no parent)
name  name of the group
path  not used anymore
===== =====

Table "node"
^^^^^^^^^^^^

The *node* table stores the identity of a Munin Node.

====== =====
Field  Value
====== =====
id     unique ID
grp_id ID of the group (or ``0`` if the node is not part of a group)
name   name of the node
path   not used anymore
====== =====

Table "node_attr"
^^^^^^^^^^^^^^^^^

The *node_attr* table contains all attributes related to a Munin None.

===== =====
Field  Value
===== =====
id    ID of the related *node*
name  name of the attribute (e.g. ``use_node_name``)
value string representation of the value (e.g. ``1``)
===== =====

Table "service"
^^^^^^^^^^^^^^^

The *service* table stores the identity of the *service* datastructure.

============= =====
Field         Value
============= =====
id            unique ID
node_id       ID of the node this service belongs to
name          unique name of the service within the node
service_title human readable name of the service
graph_info    human readable description of the service (see :ref:`graph_info <graph_info>`)
subgraphs     number of related graphs produced by this service
path          not used anymore
============= =====

Table "service_attr"
^^^^^^^^^^^^^^^^^^^^

The *service_attr* table contains all attributes related to a service.

===== =====
Field  Value
===== =====
id    ID of the related *service*
name  name of the attribute (e.g. ``graph_vlabel``)
value string representation of the value (e.g. ``Bytes``)
===== =====

Table "service_categories"
^^^^^^^^^^^^^^^^^^^^^^^^^^

Multiple category names can be assigned to a *service*.

======== =====
Field    Value
======== =====
id       ID of the related *service*
category category name assigned to the *service*
======== =====

Table "ds"
^^^^^^^^^^

Every dataset is described by *Field-level attributes* (see :ref:`nomenclature`).
The collected values for a dataset are stored in an RRD file.

========== =====
Field      Value
========== =====
id         unique ID
service_id ID of the *service* to which this dataset belongs
name       unique name of the dataset within the *service*
type       :ref:`field type <fieldname.type>` (e.g. *DERIVE*)
ordr       datasets of a *service* are sorted according to their respective *ordr* attribute
unknown    TODO
warning    description of the *warning* range (TODO: format?)
critical   description of the *critical* range (TODO: format?)
path       not used anymore
========== =====

Table "ds_attr"
^^^^^^^^^^^^^^^

The *ds_attr* table contains all attributes related to a dataset.

===== =====
Field  Value
===== =====
id    ID of the related *ds*
name  name of the attribute (e.g. ``draw``)
value string representation of the value (e.g. ``AREASTACK``)
===== =====

Table "url"
^^^^^^^^^^^

The *url* table is used for caching the URL *path* of entities (groups, nodes or services).
The path is calculated, when the entity is created.

===== =====
Field  Value
===== =====
id    ID of the related entity
type  text specifying the type of the related entity (one of: *group*, *node* and *service*)
path  URL path to be used when accessing the service graphs (e.g. ``group1/group2/host/plugin/graphFoo/subGraphBar``)
===== =====

Table "state"
^^^^^^^^^^^^^

The *state* table is used for storing the current state of datasets. These values can be used for determining :ref:`alert <tutorial-alert>` conditions.

================ =====
Field            Value
================ =====
id               ID of the related entity
type             type of the related entity (currently only used as *ds*)
previously_epoch timestamp of the second to last retrieved value
previously_value second to last retrieved value
last_epoch       timestamp of the most recently retrieved value
last_value       most recently retrieved value
alarm            current state of the related entity (one of: *unknown*, *critical*, *warning*, "" (empty))
num_unknowns     count of recent successively received ``unknown`` values (used for delayed "unknown" detection via :ref:`<unknown_limit <fieldname.unknown_limit>`)
================ =====
