InfluxDB Query

The nep-influxdb-query allow to perform queries directly on an InfluxDB OSS, allowing to build monitoring on Real-Time Telemetry data. Whit this package is possible to take full advantage of a Real-Time Monitoring infrastructures that can send data to InfluxDB by building a monitoring that uses powerful IQL queries to create complex elaborations on Real-Time telemetries.

Minimum supported environment

This package can be installed on systems running the software described below. Systems with equivalent components are also suitable for installation.

Required software	Requirements
NetEye	Version 4.26+
NetEye modules	Core

Package requirements

Service and Host Templates shipped with package nep-influxdb-query require the following NEPs:

• nep-common

• nep-centreon-plugins-base

You may need to create a dedicated account to read metrics from the InfluxDB OSS you want to query.

Setup instructions

If all requirements are met, you can now install this package. To manually set up the nep-influxdb-query package, just use nep-setup utility to install it.

nep-setup install nep-influxdb-query

After the setup is done, you have to identify all the InfluxDB OSS you want to query and create the required accounts to query the desired measurements. To ensure better security, we encourage the creation of a new dedicated user with the minimum READ privileges. To create an account using InfluxDB OSS 1.8, refer to Authentication and Authorization in InfluxDB

How to query InfluxDB Data

This Centreon Plugin has quite a peculiar structure for an IQL Query.

• It must return one data column (a Field Column)

• This data column must use the AS keyword to give it a friendly name named label

• This label must be written BEFORE the IQL Query itself

• The query must be grouped using a Tag Column

• Each group will become a separated metric

• Each value from the Tag Column is referred to as instance

• In a IQL Query must be at least one instance

• The Measurement must be filly referenced by providing both Database name and Retention Policy name

Here the sample structure:

mymetric,SELECT the_data AS "mymetric" FROM "database"."retention"."measurement" GROUP BY "instance"

The names mymetric, and instance can be referenced by the Plugin to build the Plugin Output and to check against warning and critical thresholds.

Now, to provide an example, suppose you need to check the mean value of CPU usage for server myserver in the last 10 minutes. Suppose the Measurement name is cpu, the name of the server is stored in Tag Column host and the cpu usage is stored in Field Column usage. The IQL query should look like this:

cpu_usage,SELECT mean(usage) AS cpu_usage FROM "101520"."autogen"."cpu" WHERE host='myserver' AND time > (now() - 10m) GROUP BY host ORDER BY time DESC;

Please note that the label is repeated both at the beginning (before the query) and in the AS keyword. Otherwise, the plugin will not work.

Writing thresholds

This plugin understands Nagios Ranges. It is possible to provide Warning and Critical Thresholds using Nagios Ranges. Since this Plugin can accept more than one IQL Query, a name resolution mechanism must be used. To refer to a set of metrics coming from a specific IQL Query, the label must be used. To reference a specific label the label must be enclosed in a special set o characters:

%{mymetric}

Continuing with the example, assuming the CPU Usage is percentage, we might want to define a Warning Threshold of 80% and a Critical Threshold of 90%.

%{cpu_usage} > 80
%{cpu_usage} > 90

Formatting Output

The Plugin itself has plenty of options to format output. It is possible to provide an Output Text for each possible Metric. It can be written as a simple string, and is possible to refer to each label and instance by using the notation available for thresholds. In our example, if we assume the query can return CPU usage for multiple Hosts, it is possible to write an Output Text like this:

CPU usage for %{instance} is %{cpu_usage}%

Supposing the CPU usage is returned for myserver and anotherserver, the Plugin Output might look like this:

CPU usage for myserver is 60%
CPU usage for anotherserver is 93.756%

In case all metrics are under threshold, the Plugin can return a summary output named Output Global text that replaces the standard Output text. It is useful to say ‘Everything is OK’ in a more compact way.

Available Objects

This section contains a description of all the Objects from this package that can be used to build your own monitoring environment.

Director Objects

Director Objects are Objects created (or imported) into Icinga Director. This package contains the following Director Objects:

Host Templates

The following Host Templates can be used to freely create Host Objects. Remember: do not edit these Host Templates because they will be restored/updated at the next NEP package update.

Host Template name	Description
nx-ht-influxdb	Represents a generic InfluxDB OSS Server, with its main access coordinates and cretential
nx-ht-influxdb-neteye	Represent the specific instance of InfluxDB OSS Server running into NetEye

Service Templates

The following Service Templates can be used to freely create Service Objects, Service Apply Rules or Service Sets. Remember to not edit these Service Templates because they will be restored/updated at the next NEP Package update.

Template name	Run on Agent	Description
nx-st-centreon-influxdb-query	No	Performs IQL Query against an InfluxDB OSS Server and returns the results

Package’s objects list

Object Type	Object Name	Do not edit	Containing File
Director Command	nx-c-centreon-plugins-influxdb-query	No	baskets/import/nep-influxdb-query-02-command.json
Director Data List	[NX] Centreon InfluxDB Connection protocols List	No	baskets/import/nep-influxdb-query-01-datalist.json
Director Data List	[NX] Centreon InfluxDB HTTP Backend types List	No	baskets/import/nep-influxdb-query-01-datalist.json
Director Data List	[NX] Centreon InfluxDB Metric aggregations List	No	baskets/import/nep-influxdb-query-01-datalist.json
Director Data List	[NX] Centreon InfluxDB SSL Protocols List	No	baskets/import/nep-influxdb-query-01-datalist.json
Director Host Template	nx-ht-influxdb	No	baskets/import/nep-influxdb-query-03-host.json
Director Host Template	nx-ht-influxdb-neteye	No	baskets/import/nep-influxdb-query-03-host.json
Director Service Template	nx-st-agentless-centreon-plugin	No	baskets/import/nep-influxdb-query-04-service.json
Director Service Template	nx-st-centreon-influxdb	No	baskets/import/nep-influxdb-query-04-service.json
Director Service Template	nx-st-centreon-influxdb-query	No	baskets/import/nep-influxdb-query-04-service.json