.. _user_modules:

********
 Modules
********

NEB
===

The NEB module is required if monitoring events generated by a
monitoring engine (Centreon Engine, Nagios, Icinga, ...) are
transmitted by this instance of Centreon Broker. No special
configuration is required, the module just need to be loaded through
the global *module_directory* directive.

File
====

As its name suggests, the file module is used to read from or write to
files.

===================== ====
**Type**              file
**Layer(s)**          1-3
**Work on input**     Yes
**Work on output**    Yes
**Work on temporary** Yes
===================== ====

Configuration
-------------

======== ===========================================================
Tag      Description
======== ===========================================================
path     Path to the file.
max_size Maximum file size in bytes. If the limit is reached, Broker
         will go on with *path1*, then *path2*, ..., *pathN*.
======== ===========================================================

Example
-------

::

  <input>
    <type>file</type>
    <path>/var/lib/centreon/broker.file</path>
    <protocol>bbdo</protocol>
    <max_size>100000000</max_size> <!-- 100MB limit -->
  </input>

.. _user_modules_rrd:

RRD
===

The RRD module is used to create RRD graphs. It fetches events
generated by storage output and directly handle them. It was designed to
be used with Centreon and replace the Centstorage software. Its type in
the configuration should be rrd.

===================== ===
**Type**              rrd
**Layer(s)**          1-7
**Work on input**     No
**Work on output**    Yes
**Work on temporary** No
===================== ===

Description
-----------

Notice that an RRD endpoint receives data to insert in RRD graphs from
:ref:`a storage endpoint <user_modules_storage>`. RRD endpoints only
manage physical graph creation, update and deletion. The whole
intelligence on what to update and when is not done here.

Configuration
-------------

==================== ===================================================
Tag                  Description
==================== ===================================================
metrics_path         Path to where the metrics graphs should be written.
status_path          Path to where the status graphs should be written.
path                 If using *rrdcached* software with local socket
                     connection, path to this socket.
port                 If using *rrdcached* software with a network
                     connection, port on which rrdcached listens. The
                     RRD module onlys supports connection with localhost
                     *rrdcached*.
write_metrics        Enable or disable metrics graph creation and
                     update. Enabled by default.
write_status         Enable or disable status graph creation and update.
                     Enabled by default.
cache_size           Maximum number of templates (used for file
                     creation) kept on disk.
ignore_update_errors Ignore RRD files update errors (Broker 2.4
                     compatible behavior).
==================== ===================================================

Example
-------

::

  <output>
    <type>rrd</type>
    <metrics_path>/var/lib/centreon/metrics</metrics_path>
    <status_path>/var/lib/centreon/status</status_path>
  </output>

rrdcached
---------

In large setups, the number of graphs handled by Centreon Broker can
become very important and generate I/O massively. The *rrdcached*
software was created to circumvent this issue as explained in its
`man page <http://oss.oetiker.ch/rrdtool/doc/rrdcached.en.html>`_.

Due to current *rrdcached* limitations, Centreon Broker can only use it
when local. This explains why you do not have any configuration tag for
the *rrdcached* host.

SQL
===

Insert data in Centreon Broker database.

===================== ===
**Type**              sql
**Layer(s)**          1-7
**Work on input**     No
**Work on output**    Yes
**Work on temporary** No
===================== ===

Configuration
-------------

======================= ===============================================
Tag                     Description
======================= ===============================================
db_type                 Type of the database (mysql, postgresql,
                        oracle, ...).
db_host                 Database host.
db_port                 Database port.
db_user                 Database user.
db_password             Password associated with *db_user*.
db_name                 Database name.
queries_per_transaction Number of queries per transaction. Set to 1 or
                        below to disable transactions. Default to 1.
read_timeout            When using transactions, maximum time between
                        commits. This prevent database from not being
                        updated due to lack of queries to fill the
                        transaction.
check_replication       Useful when using DB replication. Enable or
                        disable replication check when connecting.
                        Default is enabled.
cleanup_check_interval  How often the cleanup thread should run. This
                        thread cleans multiple tables of the database
                        containing outdated data.
instance_timeout        In seconds, how long the broker will wait for
                        a poller before signaling the poller as
                        unresponsive. 0 to disable this feature.
with_state_events       Generate host/service state events. This is an
                        *experimental* feature used to compute
                        real-time BI information.
======================= ===============================================

Example
-------

::

  <output>
    <type>sql</type>
    <db_type>mysql</db_type>
    <db_host>localhost</db_host>
    <db_port>3306</db_port>
    <db_user>centreon</db_user>
    <db_password>noertnec</db_password>
    <db_name>centreon_storage</db_name>
  </output>


.. _user_modules_storage:

Storage
=======

The storage module extract performance data from check results and
insert them in a database. It also generate events for use by the
:ref:`modules rrd <user_modules_rrd>`.

===================== =======
**Type**              storage
**Layer(s)**          1-7
**Work on input**     No
**Work on output**    Yes
**Work on temporary** No
===================== =======

Configuration
-------------

======================= ===============================================
Tag                     Description
======================= ===============================================
interval                Monitoring engine base interval (usually 60
                        seconds).
length                  RRD file length in seconds (ie. how much data
                        your RRD file will contain). For 180 days
                        (recommended), use 15552000
                        (180 * 24 * 60 * 60).
db_type                 Database type. One of db2, ibase, mysql,
                        oracle, odbc, postgresql, sqlite, tds.
db_host                 Database host.
db_port                 Database port.
db_user                 Database user.
db_password             Database password.
db_name                 Database name.
queries_per_transaction Number of queries per transaction. Set to 1 or
                        below to disable transactions. Default to 1.
read_timeout            When using transactions, maximum time between
                        commits. This prevent database from not being
                        updated due to lack of queries to fill the
                        transaction.
check_replication       Useful when using DB replication. Enable or
                        disable replication check when connecting.
                        Default is enabled.
rebuild_check_interval  How often (in seconds) metrics should be
                        checked for rebuild.
store_in_data_bin       This can be used to avoid keeping performance
                        data in the *data_bin* table. *Warning*: this
                        will prevent you to rebuild RRD files.
insert_in_index_data    Internal option used by Centreon to allow
                        graphs to properly work on satellite (deported
                        interface).
======================= ===============================================

Example
-------

::

  <output>
    <type>storage</type>
    <interval>60</interval>
    <length>15552000</length>
    <db_type>oracle</db_type>
    <db_host>localhost</db_host>
    <db_port>1521</db_port>
    <db_user>centreon</db_user>
    <db_password>noertnec</db_password>
    <db_name>centreon_storage</db_name>
  </output>


BAM
===

Monitoring endpoint
-------------------

Compute Business Activity and Key Performance Indicator levels as well
as meta-services. This is the improved version (as a Centreon Broker
module) of the Centreon BAM extension.

===================== ===
**Type**              bam
**Layer(s)**          1-7
**Work on input**     No
**Work on output**    Yes
**Work on temporary** No
===================== ===

Configuration of the monitoring endpoint
----------------------------------------

======================= ===============================================
Tag                     Description
======================= ===============================================
db_type                 Type of the database (mysql, postgresql,
                        oracle, ...).
db_host                 Database host.
db_port                 Database port.
db_user                 Database user.
db_password             Password associated with *db_user*.
db_name                 Centreon database name (usually *centreon*).
storage_db_name         Storage database name (usually
                        *centreon_storage*).
queries_per_transaction Number of queries per transaction. Set to 1 or
                        below to disable transactions. Default to 1.
read_timeout            When using transactions, maximum time between
                        commits. This prevent database from not being
                        updated due to lack of queries to fill the
                        transaction.
check_replication       Useful when using DB replication. Enable or
                        disable replication check when connecting.
                        Default is enabled.
command_file            Centreon Engine external command file. This is
                        used to provide check results on BAs and launch
                        notifications as a consequence.
======================= ===============================================

Reporting endpoint
------------------

Compute reporting information on BAs. This is only useful for use with
Centreon BI to generate reports on Business Activities.

===================== ======
**Type**              bam_bi
**Layer(s)**          1-7
**Work on input**     No
**Work on output**    Yes
**Work on temporary** No
===================== ======

Configuration of the reporting endpoint
---------------------------------------

======================= ===============================================
Tag                     Description
======================= ===============================================
db_type                 Type of the database (mysql, postgresql,
                        oracle, ...).
db_host                 Database host.
db_port                 Database port.
db_user                 Database user.
db_password             Password associated with *db_user*.
db_name                 Database name.
queries_per_transaction Number of queries per transaction. Set to 1 or
                        below to disable transactions. Default to 1.
read_timeout            When using transactions, maximum time between
                        commits. This prevent database from not being
                        updated due to lack of queries to fill the
                        transaction.
check_replication       Useful when using DB replication. Enable or
                        disable replication check when connecting.
                        Default is enabled.
======================= ===============================================


Example
-------

::

  <output>
    <type>bam</type>
    <db_type>mysql</db_type>
    <db_host>localhost</db_host>
    <db_port>3306</db_port>
    <db_user>centreon</db_user>
    <db_password>noertnec</db_password>
    <db_name>centreon</db_name>
    <storage_db_name>centreon_storage</storage_db_name>
  </output>


TCP
===

Probably one of the most used module. Provides network connectivity.

===================== ===
**Type**              tcp
**Layer(s)**          1-3
**Work on input**     Yes
**Work on output**    Yes
**Work on temporary** No
===================== ===

Configuration
-------------

======================= ================================================
Tag                     Description
======================= ================================================
host                    Host to connect to. To have a server connection,
                        do not use this tag.
one_peer_retention_mode Allow only one connection for a specific output.
                        This option allow to keep retention on a server
                        output (socket on a listen mode).
port                    Port on which Centreon Broker should listen (if
                        no host is defined) or connect to.
protocol                Choose your protocol (bbdo or ndo).
socket_write_timeout    The number of microseconds to wait for data to
                        be sent in the socket before the waiting
                        timeout. If not present, or 0, the write will
                        never time out.
======================= ================================================

Example
-------

Input stream that waits for clients to connect on port 5668.

::

  <input>
    <type>tcp</type>
    <port>5668</port>
    <protocol>bbdo</protocol>
  </input>

Output stream that connects on host remotehost.tld on port 5668.

::

  <output>
    <type>tcp</type>
    <host>remotehost.tld</host>
    <port>5668</port>
    <protocol>bbdo</protocol>
  </output>

Output stream that connects on host remotehost.tld on port 5668
and allow single peer connection.

::

  <output>
    <type>tcp</type>
    <host>remotehost.tld</host>
    <port>5668</port>
    <protocol>bbdo</protocol>
    <one_peer_retention_mode>1</one_peer_retention_mode>
  </output>

BBDO
====

BBDO is a serialization layer introduced by Centreon Broker. Its name
stands for *Broker Binary Data Objects*. This protocol was initially
introduced to improve performance over the NDO protocol which was using
data stringification. As its name suggests, BBDO is using raw binary
data transfer which drastically reduce its CPU footprint on busy
servers.

BBDO also supports feature negotiation and can automatically encrypt
and/or compress transmitted data. No configuration is required, whereas
possible, to use compression and TLS modules.

===================== ===
**Type**              N/A
**Layer(s)**          7
**Work on input**     Yes
**Work on output**    Yes
**Work on temporary** No
===================== ===

Configuration
-------------

=========== =====================================================
Tag         Description
=========== =====================================================
protocol    Must be set to *bbdo*.
negotiation Enable or disable BBDO automatic feature negotiation.
=========== =====================================================

NDO
===

NDO is the historical but deprecated serialization layer for events. A
serialization layer is required on some endpoints to reach the 7th layer
(NDO is inserted at layer 7).

===================== ===
**Type**              N/A
**Layer(s)**          7
**Work on input**     Yes
**Work on output**    Yes
**Work on temporary** No
===================== ===

Configuration
-------------

======== =====================
Tag      Description
======== =====================
protocol Must be set to *ndo*.
======== =====================

Example
-------

::

  <input>
    <type>tcp</tcp>
    <port>5668</port>
    <protocol>ndo</protocol>
  </input>


.. _user_modules_tls:

TLS
===

The TLS module is using `GNU TLS <http://www.gnutls.org>`_ to provide
encryption. Encryption can work with two modes : either with provided
certificates (and optionally authentication with a trusted CA) or by
using anonymous mode. With this last mode, TLS just have to be enabled
and encryption is configured by the software. It is this last mode that
is used by the BBDO protocol.

================== ===
**Type**           N/A
**Layer(s)**       5
**Work on input**  Yes
**Work on output** Yes
================== ===

Description
-----------

By default, TLS do not need to be explicitely enabled. It will be
enabled automatically if BBDO's negotiation succeeds.

You will need to configure it manually if you wish to use certificates.
In this case, you will need to explicitely enable TLS on both
communicating endpoints (ie. the input endpoint and the output
endpoint). You can use unsigned, signed or self-signed certificates
as long as you do not use a Certificate Authority certificate.

If you are using a Certificate Authority certificate to authenticate
connections, then each peer's certificate will be checked against this
CA certificate (ie. the peer's certificate must be signed by the CA
you are using).

Options
-------

============== =======================================================
Tag            Description
============== =======================================================
tls            Enable TLS protocol. It can either be used as anonymous
               (no public_cert nor private_key) or with appropriate
               settings (ca_certificate) used with certificate
               authentication. Note that if this option is set (to
               either true or false), BBDO's TLS negotiation won't be
               possible.
private_key    Private key, in PEM format.
public_cert    Public certificate, in PEM format, associated with
               private_key.
ca_certificate Trusted Certificate Authority certificate, in PEM
               format. If this parameter is set, the CA’s certificate
               is used to authenticate client connections which are
               denied if the peer key could not be validated.
============== =======================================================

Example
-------

Output stream connecting to remotehost.tld using public.cert and
private.key files.

::

  <output>
    <type>tcp</type>
    <host>remotehost.tld</host>
    <port>5669</port>
    <public_cert>public.cert</public_cert>
    <private_key>private.key</private_key>
    <protocol>bbdo</protocol>
  </output>

Input stream that authenticate clients using the trusted CA's
certificate (trusted_ca.cert).

::

  <input>
    <type>tcp</type>
    <port>5669</port>
    <public_cert>public.cert</public_cert>
    <private_key>private.key</private_key>
    <ca_certificate>trusted_ca.cert</ca_certificate>
    <protocol>bbdo</protocol>
  </input>


.. _user_modules_compression:

Compression
===========

The compression module uses the `zlib <http://www.zlib.org>`_
compression algorithm to reduce the size of data transmitted by Centreon
Broker. Typical compression ratio range from 2:1 to 5:1.

================== ===
**Type**           N/A
**Layer(s)**       6
**Work on input**  Yes
**Work on output** Yes
================== ===

Options
-------

The compression can be configured with the tags defined in the table
below.

================== ====================================================
Tag                Description
================== ====================================================
compression        Set it to 1 to enable compression. This is the sole
                   mandatory parameter.
compression_level  Level of compression from 0 (no compression) to 9
                   (best compression). Defaults to -1 which is zlib's
                   default compression level.
compression_buffer Size in bytes of the compression buffer. The biggest
                   the buffer is, the best is the compression. However
                   the latency increase along with the buffer size.
================== ====================================================

Example
-------

::

  <output>
    <type>tcp</type>
    <host>localhost</host>
    <port>5668</port>
    <compression>1</compression>
    <compression_level>4</compression_level>
    <compression_buffer>5000</compression_buffer>
  </output>


.. _user_modules_stats:

Statistics
==========

The statistics (stats) module was created to provide information about
the ongoing processing of Centreon Broker. You find various statistics
such as the number of events processed by second per input or output,
the number of queued events, connected peers, loaded modules, ...

This is a global module that do not apply to a specific endpoint.

===================== ====
**Type**              N/A
**Layer(s)**          N/A
**Work on input**     No
**Work on output**    No
**Work on temporary** No
===================== ====

Configuration
-------------

A *stats* node must be defined right under the root node of the XML
configuration file. This node can then contain the following tags.

====== =====================================================
Tag    Description
====== =====================================================
fifo   The FIFO file from which you can read the statistics.
remote Send statistics information from monitoring engine
       or broker over the networks (This feature need
       centreon-broker >= 2.7).
====== =====================================================

Example
-------

::

  <stats>
    <fifo>/var/lib/centreon-broker/central-module.stats</fifo>
  </stats>

You can then read the file with a simple *cat* command.

::

  $> cat /var/lib/centreon-broker/central-module.stats
  module /usr/share/centreon/lib/centreon-broker/50-tcp.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/20-correlation.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/10-neb.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/60-compression.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/20-storage.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/80-sql.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/70-rrd.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/50-local.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/80-ndo.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/05-stats.so
  state=loaded

  module /usr/share/centreon/lib/centreon-broker/50-file.so
  state=loaded

  output poller-module
  state=connected
  queued_events=0
  last event at=1358863864
  event processing speed=160.3 events/s
  last connection attempt=1358862546
  last connection success=1358862546

Since Centreon-Broker 2.7 we can send statistics over the network with
the node "remote". This node can then contain the following tags.

========== =====================================================
Tag        Description
========== =====================================================
dumper_tag Tag name of the dumper output to write statistics.
interval   Interval in seconds to dump statitics.
metrics    This node contain informations about statistics to
           write (see below). All stats into metrics create RRD
	   files.
========== =====================================================

This table describe the node metrics.

========== =====================================================
Tag        Description
========== =====================================================
host       Host id of the metric.
service    Service contain service id and servce name of the
           metric.
========== =====================================================

This table describe the node service.

========== =====================================================
Tag        Description
========== =====================================================
id         Service id of the metric.
name       Service name.
========== =====================================================

This is list of available services for NEB module.

============================= ================================================= ==================================================
Name                          Description                                       Perfdata
============================= ================================================= ==================================================
active_host_execution_time    Active host check execution time (ms)             avg, min, max
active_host_latency           Active host check latency (ms)                    avg, min, max
active_hosts_last             Number of active host checks in last minutes      active_hosts_last_1, active_hosts_last_5,
                                                                                active_hosts_last_15, active_hosts_last_60
active_host_state_change      Active host check % state change                  avg, min, max
active_service_execution_time Active service check execution time (ms)          avg, min, max
active_service_latency        Active service check latency (ms)                 avg, min, max
active_services_last          Number of active service checks in last minutes   active_services_last_1, active_services_last_5,
                                                                                active_services_last_15, active_services_last_60
active_service_state_change   Active service check % state change               avg, min, max
command_buffers               External command buffer informations              used, high, total
hosts_actively_checked        Total of hosts actively checked                   hosts_actively_checked
hosts_checked                 Total of hosts checked                            hosts_checked
hosts_flapping                Number of host in flapping                        hosts_flapping
hosts                         Total hosts state informations                    up, down, unreachable
hosts_in_downtime             Number of host in downtime                        hosts_in_downtime
hosts_passively_checked       Total of hosts passively checked                  hosts_passively_checked
hosts_scheduled               Total of scheduled hosts                          hosts_scheduled
passive_host_latency          Passive host check latency (ms)                   avg, min, max
passive_hosts_last            Number of passive host checks in last minutes     passive_hosts_last_1, passive_hosts_last_5,
                                                                                passive_hosts_last_15, passive_hosts_last_60
passive_host_state_change     Passive host check % state change                 avg, min, max
passive_service_latency       Passive service check latency (ms)                avg, min, max
passive_services_last         Number of passive service checks in last minutes  passive_services_last_1, passive_services_last_5,
                                                                                passive_services_last_15, passive_services_last_60
passive_service_state_change  Passive service check % state change              avg, min, max
services_actively_checked     Total of services actively checked                services_actively_checked
services_checked              Total of services checked                         services_checked
services_flapping             Number of service in flapping                     services_flapping
services                      Total services state informations                 ok, warning, critical, unknown
services_in_downtime          Number of service in downtime                     services_in_downtime
services_passively_checked    Total of services passively checked               services_passively_checked
services_scheduled            Total of scheduled services                       services_scheduled
total_hosts                   Total number of hosts                             total_hosts
total_host_state_change       Total host check % state change                   avg, min, max
total_services                Total number of services                          total_services
total_service_state_change    Total service check % state change                avg, min, max
============================= ================================================= ==================================================

Example
-------

::

  <stats>
    <remote>
      <dumper_tag>CentralBroker</dumper_tag>
      <interval>300</interval>
      <metrics>
        <host>1</host>
	<service>
  	  <id>1</id>
	  <name>active_host_execution_time</name>
	</services>
	<service>
  	  <id>2</id>
	  <name>active_host_latency</name>
	</services>
      </metrics>
    </remote>
  </stats>

.. _user_modules_correlation:

Correlation
===========

The correlation module provide basic correlation features to Centreon
Broker.

This is a global module that do not apply to a specific endpoint.

===================== ====
**Type**              N/A
**Layer(s)**          N/A
**Work on input**     No
**Work on output**    No
**Work on temporary** No
===================== ====

Configuration
-------------

A *correlation* node must be defined right under the root node of the
XML configuration file. This node can then contain the tags described
in the table below.

========== ==============================================================
Tag        Description
========== ==============================================================
file       The XML configuration file containing host and service
           definitions along with parenting and dependencies definitions.
retention  The XML retention file. This file is written by Centreon
           Broker so that the correlation engine does not forget the
           current states of the hosts and services across Broker
           restarts.
passive    Enable passive mode. In this mode, the correlator update the
           internal state with correlation events. No events are emits
           in passive mode.
========== ==============================================================

Example
-------

::

  <correlation>
    <file>/etc/centreon-broker/correlation.cfg</file>
    <retention>/var/lib/centreon-broker/correlation.sav</retention>
  </correlation>

Dumper
======

The dumper module is used to transfer files between Centreon Broker
instances.

Dumper endpoint
---------------

The dumper endpoint is used to write files on the disk. It can filter
data by tagname. A dumper write only data with the same tagname as his.

===================== ======
**Type**              dumper
**Layer(s)**          1-7
**Work on input**     No
**Work on output**    Yes
**Work on temporary** No
===================== ======

Configuration of the dumper endpoint
------------------------------------

============= ===========================================================
Tag           Description
============= ===========================================================
tagname       The tag name to write file. Tag name allow filtering.
path          The path of the file to write data. You can use some macros
              in the path. Available macros are *$INSTANCEID$* (the
              instance ID of the Centreon Broker instance that generated
              the dump event) and *$FILENAME$* (the original file name
              of the file that generated the dump event).
============= ===========================================================

FIFO dump endpoint
------------------

This endpoint transfer the content of a FIFO file. Each time a line is
written to the FIFO, it is transfered.

===================== =========
**Type**              dump_fifo
**Layer(s)**          1-7
**Work on input**     Yes
**Work on output**    No
**Work on temporary** No
===================== =========

Configuration of the FIFO dump endpoint
---------------------------------------

============= ===========================================================
Tag           Description
============= ===========================================================
tagname       The tag name to write file. This is used by *dumper*
              endpoints to perform filtering.
path          The path of the FIFO file.
============= ===========================================================

Directory dump endpoint
-----------------------

This endpoint transfer the content of a directory. Each time a file is
modified it is transfered.

===================== =========
**Type**              dump_dir
**Layer(s)**          1-7
**Work on input**     Yes
**Work on output**    No
**Work on temporary** No
===================== =========

Configuration of the directory dump endpoint
--------------------------------------------

============= ===========================================================
Tag           Description
============= ===========================================================
tagname       The tag name to write file. This is used by *dumper*
              endpoints to perform filtering.
path          The path of the directory to watch for changes.
============= ===========================================================


Example
-------

::

  <input>
    <type>dump_fifo</type>
    <tagname>engine-extcmd-1</tagname>
    <path>/var/lib/centreon/poller-1.cmd</path>
  </input>

  <input>
    <type>dump_dir</type>
    <tagname>engine-cfg-1</tagname>
    <path>/var/lib/centreon/cfg/1</path>
  </input>

  <output>
    <type>dumper</type>
    <tagname>CentralBroker</tagname>
    <path>/var/lib/centreon-broker/$INSTANCEID$.stats</path>
  </output>

  <output>
    <type>dumper</type>
    <tagname>engine-extcmd-1</tagname>
    <path>/var/lib/centreon-engine/rw/centengine.cmd</path>
  </output>

  <output>
    <type>dumper</type>
    <tagname>engine-cfg-1</tagname>
    <path>/etc/centreon-engine/$FILENAME$</path>
  </output>

InfluxDB
========

.. warning::
  This module is experimental.

This module fills an InfluxDB instance with metrics. It uses the
:ref:`storage engine <user_modules_storage>` as its performance data
source.

===================== ========
**Type**              influxdb
**Layer(s)**          1-7
**Work on input**     No
**Work on output**    Yes
**Work on temporary** No
===================== ========

Description
-----------

Users of this module can make their own storage scheme to suite their
needs. The InfluxDB module will provide information on a particular
metric using a macro system. Each macro must be written between two
dollar-sign (like *$MACRO$*). If one wishes to write a dollar-sign he
must write two continguous dollar-signs (*$$*).

Configuration
-------------

======================== ===============================================
Tag                      Description
======================== ===============================================
db_host                  Database host.
db_port                  Database port. Default 8086.
db_user                  Database user.
db_password              Password associated with *db_user*.
db_name                  Database name.
queries_per_transaction  Number of queries per transaction. Set to 1 or
                         below to disable transactions. Default to 1.
read_timeout             When using transactions, maximum time between
                         commits in seconds. This prevent database from
                         not being updated due to lack of queries to
                         fill the transaction. Default to 1s.
status_timeseries        Name of the time series for statuses. Macros
                         accepted.
status_column            Define one status column. Each InfluxDB
                         endpoint can have multiple status columns.
                         Macros accepted.
status_column -> name    Name of the column. Macros accepted.
status_column -> value   Value of the column. Macros accepted.
status_column -> is_tag  Boolean value that is set to true if the
                         current column is a tag. Defaults to false.
status_column -> type    Type of the column. Can be either 'string' or
                         'number'. Default to 'string'.
metrics_timeseries       Name of the time series for metrics. Macros
                         accepted.
metrics_column           Define one metrics column. Each InfluxDB
                         endpoint can have multiplex metrics columns.
                         Macros accepted.
metrics_column -> name   Name of the column. Macros accepted.
metrics_column -> value  Value of the column Macros accepted.
metrics_column -> is_tag Boolean value that is set to true if the
                         current column is a tag. Defaults to false.
metrics_column -> type   Type of the column. Can be either 'string' or
                         'number'. Default to 'string'.
======================== ===============================================

Available macros are described in the following table.

============ ================================== ============ ===========
Macro        Description                        For statuses For metrics
============ ================================== ============ ===========
INSTANCE     Instance (poller) name.                 X            X
INSTANCEID   Instance (poller) ID.                   X            X
HOST         Host.                                   X            X
HOSTID       Host ID.                                X            X
SERVICE      Service.                                X            X
SERVICEID    Service ID.                             X            X
INDEXID      Index of the host / service within      X            X
             Centreon's *index_data* table.
METRIC       Metric name.                                         X
METRICID     ID of the metric within Centreon's                   X
             *metrics* table.
============ ================================== ============ ===========


Example
-------

::

  <output>
    <type>influxdb</type>
    <db_host>localhost</db_host>
    <db_port>8086</db_port>
    <db_user>centreon</db_user>
    <db_password>noertnec</db_password>
    <db_name>metrics</db_name>

    <!-- All statuses will be stored in the 'status' time series. -->
    <status_timeseries>status</status_timeseries>
    <status_column>
      <name>time</name>
      <value>$TIME$</value>
    </status_column>
    <status_column>
      <name>value</name>
      <value>$VALUE$</value>
    </status_column>
    <status_column>
      <name>index_id</name>
      <value>$INDEXID$</value>
      <is_tag>1</is_tag>
    </status_column>

    <!-- Each separate metric will be stored in a time series that has
         the same name as the metric name. -->
    <metrics_timeseries>$METRIC$</metrics_timeseries>
    <metrics_column>
      <name>time</name>
      <value>$TIME$</value>
    </metrics_column>
    <metrics_column>
      <name>value</name>
      <value>$VALUE$</value>
    </metrics_column>
    <metrics_column>
      <name>metric_id</name>
      <value>$METRICID$</value>
      <is_tag>1</is_tag>
    </metrics_column>
  </output>

Graphite
========

.. warning::
  This module is experimental.

This module fills a Graphite instance with metrics. It uses the
:ref:`storage engine <user_modules_storage>` as its performance data
source.

===================== ========
**Type**              graphite
**Layer(s)**          1-7
**Work on input**     No
**Work on output**    Yes
**Work on temporary** NO
===================== ========

Description
-----------

The module uses only the plaintext protocol.

Configuration
-------------

======================= ===============================================
Tag                     Description
======================= ===============================================
metric_naming           Naming hierarchy within Graphite. This defaults
                        to *centreon.metrics.$METRICID$* where
                        *$METRICID$* is the metric's ID within
                        Centreon's *metrics* table. Complete available
                        variables are *$INSTANCE$* (name of the poller),
			*$INSTANCEID$*, *$HOST$* (the host name),
			*$HOSTID$*, *$SERVICE$* (the service
			description), *$SERVICEID$*, *$METRIC$* (the
			metric name), *$METRICID$* and *$INDEXID$*.
status_naming           Naming hierarchy within Graphite. This defaults
                        to *centreon.statuses.$INDEXID$* where
                        *$INDEXID$* is the index ID of the host /
                        service within Centreon's *index_data* table.
                        Complete available variables are *$INSTANCE$*,
			*$INSTANCEID$*, *$HOST$*, *$HOSTID$*,
			*$SERVICE$*, *$SERVICEID$* and *$INDEXID$*.
db_host                 Database host.
db_port                 Database port. Default to 80.
db_user                 Database user. Default is empty (no
                        authentication).
db_password             Password associated with *db_user*. Default is
                        empty (no authentication).
queries_per_transaction Number of queries per transaction. Set to 1 or
                        below to disable transactions. Default to 1.
read_timeout            When using transactions, maximum time between
                        commits in seconds. This prevent database from
                        not being updated due to lack of queries to
                        fill the transaction. Default to 1s.
======================= ===============================================
