Merge remote-tracking branch 'origin/devel'

* origin/devel: doc: move wiki page MuninExtraordinaryUsage to MuninGuide doc: more explanations on Munin Exchange doc: Refer to option --families directly. doc: moved wiki page MuninAggregateGraphs to MuninGuide doc: rework munin-node.conf merged wiki page munin-node.conf and current release of munin-node.conf doc: Moved wiki page MuninExchangeIsDown to MuninGuide doc: moved wiki page PluginDebugging to MuninGuide doc: moved wiki page to MuninGuide (MuninTroubleshooting) doc: Subsection titles were on first hierarchy level doc: bump the copyright to 2016 DOC: Improved version of wiki page MuninConfigurationMasterExampleStack moved to TheMuninGuide
munin-monitoring · Nov 9, 2016 · 203a421 · 203a421
2 parents 00344e4 + d21a943
commit 203a421
Show file tree

Hide file tree

Showing 16 changed files with 627 additions and 39 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -44,7 +44,7 @@
 project = 'Munin'
 description = 'Munin monitoring'
 authors   = 'The Munin project and its contributors'
-copyright = '2012-2015, %s' % authors
+copyright = '2012-2016, %s' % authors
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

diff --git a/doc/develop/documenting.rst b/doc/develop/documenting.rst
@@ -37,6 +37,8 @@ section in the plugins code file accordingly.
 Finally send a patch or a pull request on github to help us improve
 the plugins documentation.
 
+.. _munin-gallery:
+
 Munin Gallery
 =============
 

diff --git a/doc/example/graph/aggregate.rst b/doc/example/graph/aggregate.rst
@@ -1,7 +1,10 @@
 .. _example-plugin-aggregate:
 .. index::
    single: Aggregating munin plugins
+   pair: data source; loan
    pair: plugin; aggregate
+   pair: plugin; virtual
+   pair: virtual; node
 
 ==============================
  Graph aggregation by example
@@ -187,5 +190,6 @@ field name, namely "output" (lines 31 - 35).
 Further reading
 ===============
 
+ * :ref:`Graph aggregation stacking example <example-aggregated-stack>`
  * :ref:`Using SNMP plugins <tutorial-snmp>`
  * :ref:`munin.conf <munin.conf>` directives explained
diff --git a/doc/example/graph/aggregated-stack.rst b/doc/example/graph/aggregated-stack.rst
@@ -0,0 +1,173 @@
+.. _example-aggregated-stack:
+.. index::
+   single: Aggregating munin plugins
+   pair: data source; loan
+   pair: graph; stacked
+   pair: plugin; aggregate
+   pair: plugin; virtual
+   pair: virtual; node
+
+===================================
+ Graph aggregation stacking example
+===================================
+
+Here we show how to create a stacked graph with data sources from multiple nodes.
+
+
+.. _config_postfix_mailstats:
+
+Plugin involved
+================
+
+The example uses a plugin that monitors Postfix message throughput.
+
+Let's first look at its config output:
+
+::
+
+ # munin-run postfix_mailstats config
+ graph_title Postfix message throughput
+ graph_args --base 1000 -l 0
+ graph_vlabel mails / ${graph_period}
+ graph_scale  no
+ graph_total  Total
+ graph_category postfix
+ graph_period minute
+ delivered.label delivered
+ delivered.type DERIVE
+ delivered.draw AREA
+ delivered.min 0
+ r450.label reject 450
+ r450.type DERIVE
+ r450.draw STACK
+ r450.min 0
+ r454.label reject 454
+ r454.type DERIVE
+ r454.draw STACK
+ r454.min 0
+ r550.label reject 550
+ r550.type DERIVE
+ r550.draw STACK
+ r550.min 0
+ r554.label reject 554
+ r554.type DERIVE
+ r554.draw STACK
+ r554.min 0
+
+
+Extract from munin.conf
+=======================
+
+The following extract from :ref:`munin.conf <munin.conf>` is explained in
+detail, step by step, below the configuration.
+
+::
+
+  1 [foo.example.com]
+  2       address ..
+  3
+  4 [bar.example.com]
+  5       address ..
+  6
+  7 [baz.example.com]
+  8       address ..
+  9
+ 10 [aggregates.example.com]
+ 11       update no
+ 12       contacts no
+ 13
+ 14 # This graph stacks the number of postfix delivered mails / minute
+ 15 # from the nodes foo.example.com, bar.example.com and baz.example.com
+ 16
+ 17       total_mailstats.update no
+ 18       total_mailstats.graph_args --base 1000 -l 0
+ 19       total_mailstats.graph_category postfix
+ 20       total_mailstats.graph_period minute
+ 21       total_mailstats.graph_title Postfix delivered messages
+ 22       total_mailstats.graph_vlabel mails / ${graph_period}
+ 23       total_mailstats.graph_scale  no
+ 24       total_mailstats.graph_total  Total
+ 25       total_mailstats.total_delivered.label not_used
+ 26       total_mailstats.total_delivered.type DERIVE
+ 27       total_mailstats.total_delivered.draw AREA
+ 28       total_mailstats.total_delivered.min 0
+ 29       total_mailstats.total_delivered.stack \
+ 30           foo=Infrastruktur;foo.example.com:postfix_mailstats.delivered \
+ 31           bar=Infrastruktur;bar.example.com:postfix_mailstats.delivered \
+ 32           baz=Infrastruktur;baz.example.com:postfix_mailstats.delivered
+
+
+Explanations, per line
+======================
+
+* 1 - 2: Configuration of Node foo.example.com.
+
+* 4 - 5: Configuration of Node bar.example.com.
+
+* 7 - 8: Configuration of Node bar.example.com.
+
+* 10: Define the name of the virtual node.
+  The name of a node group can optionally be added here,
+  e.g. "[Virtual; aggregates.example.com]".
+
+* 11: Make sure that ``munin-update`` does not try
+  to actively gather information for this node.
+
+* 12: Tell ``munin-limits`` not to send alerts if any limit is breached.
+
+The above lines (1 - 12) have now established the fundament for four
+nodes in the Munin tree; three *real* nodes delivering data on connect
+by ``munin-update`` and one *virtual* node for the aggregate graphs.
+
+* 17: No fetch from node should be done for this virtual plugin
+  (which is named implicitly herewith to "total_mailstats").
+
+* 18 - 24: Define the virtual plugin's config in the same way as
+  set for its *ancestor* plugin ``postfix_mailstats`` (see output in section :ref:`Plugin involved <config_postfix_mailstats>`  above).
+  We set a different graph title though, as we graph only field ``delivered`` here.
+
+* 25: The virtual plugin's field itself will not show up in the graph
+  but only the fields loaned from the real nodes. Therefore this
+  hint that will be shown in the graphs legend.
+
+* 26: Default type is ``GAUGE`` but we have type ``DERIVE`` here.
+  So the field's type has to be declared explicitly.
+
+* 27: Values should be drawn as AREA and not as LINE for
+  better recognition of small values.
+
+* 28: Cut off negative values which can arise at arithmetic overflow for data type ``DERIVE``.
+  `See manual of rrdgraph <http://oss.oetiker.ch/rrdtool/doc/rrdcreate.en.html#IDERIVE>`_
+
+* 29: This directive is the key that opens the door for
+  loaning data sources from other nodes and plugins.
+  As we choose option ``stack`` here, the values of the
+  hereafter referenced data sources will show up
+  stacked on each other in the graph.
+
+* 30 - 33: Declare the virtual data fields as reference to
+  the original data source in node foo, bar and baz.
+  The string on the left side of the expression will be the name
+  of the data field shown in the graph of this virtual plugin.
+  Hint: If you need to reference a node that is member of a node group,
+  then enter its name with the leading group name like "Group;node.name".
+
+
+Result graph
+=============
+
+Source graph for bar.example.com:
+
+.. image:: stack/postfix_mailstats-year.png
+
+Aggregate graph:
+
+.. image:: stack/total_mailstats-year.png
+
+
+Further reading
+===============
+
+ * :ref:`Graph aggregation by example <example-plugin-aggregate>`
+ * :ref:`munin.conf <munin.conf>` directives explained
+
diff --git a/doc/example/graph/stack/postfix_mailstats-year.png b/doc/example/graph/stack/postfix_mailstats-year.png
diff --git a/doc/example/graph/stack/total_mailstats-year.png b/doc/example/graph/stack/total_mailstats-year.png
diff --git a/doc/example/index.rst b/doc/example/index.rst
@@ -15,6 +15,7 @@ Examples of munin and related configuration are gathered here.
    rrdcached/upstart.rst
    rrdcached/systemd.rst
    graph/aggregate.rst
+   graph/aggregated-stack.rst
    tips/multimaster.rst
    transport/ssh.rst
    service/service.rst

diff --git a/doc/installation/configuration.rst b/doc/installation/configuration.rst
@@ -1,3 +1,5 @@
+.. _initial_configuration:
+
 =======================
  Initial configuration
 =======================

diff --git a/doc/installation/upgrade.rst b/doc/installation/upgrade.rst
@@ -1,3 +1,5 @@
+.. _upgrade:
+
 ===============
  Upgrade notes
 ===============
@@ -6,7 +8,7 @@ Upgrading Munin from 2.0.x to 2.1.x
 ===================================
 
 Munin HTTPD
-===========
+-----------
 
 :ref:`munin-httpd` replaces FastCGI.  It is a basic webserver capable
 of serving pages and graphs.
@@ -18,7 +20,7 @@ If you choose to use :ref:`munin-httpd`, set :option:`graph_strategy`
 and :option:`html_strategy` to "cgi".
 
 FastCGI
-=======
+-------
 
 …is gone.  It was hard to set up, hard to debug, and hard to support.
 
@@ -29,14 +31,14 @@ This is a compilation of items you need to pay attention to when
 upgrading from Munin 1.x to munin 2.x
 
 FastCGI
-=======
+-------
 
 Munin graphing is now done with FastCGI.
 
 Munin HTML generation is optionally done with FastCGI.
 
 Logging
-=======
+-------
 
 The web server needs write access to the munin-cgi-html and
 munin-cgi-graph logs.
diff --git a/doc/reference/history.rst b/doc/reference/history.rst
@@ -16,6 +16,9 @@ A Brief History of Munin
 2009
         1.4 came out
 
+2011
+        EOL of :ref:`Munin Exchange website <Munin-Exchange>`, content moved to GitHub branch **contrib**
+
 2012
         Released 2.0, for its 10 years !
 
@@ -25,3 +28,35 @@ A Brief History of Munin
 
 July 2014
         target for 2.2
+
+
+Glossary
+========
+
+.. index::
+   single: Munin Exchange
+
+.. _Munin-Exchange:
+
+Munin Exchange
+--------------
+
+Was a web platform in the beginning setup and hosted by Linpro (Bjorn Ruberg?).
+Later (when?) a Munin supporter re-invented the `Munin Exchange` website to improve its usablity.
+When he left the project (when?) it was not possible to maintain the website any longer,
+because it was coded in Python with Django and Steve Schnepp said "we clearly lack skills on that".
+So it was decided to move all the plugins over to github branch "contrib".
+
+Github is now the official way of contributing 3rd-party plugins.
+
+These are tagged with **familiy contrib** (see: :option:`--families` in :ref:`munin-node-configure`).
+
+Only if they meet the requirements for `vetted plugins <http://munin-monitoring.org/wiki/requirements-vetted>`_
+they can be included in the core plugins collection (distributed as `official` Munin release
+by the Munin developer team). They get tagged with **family auto** then
+as all core collection plugins should have the command
+`autoconf <http://munin-monitoring.org/wiki/PluginConcise#autoconf>`_
+implemented.
+
+
+See also: :ref:`munin-gallery`