This extensions is designed to help administrators monitor their iTop(s) via http(s) endpoint(s) and oversee incidents coming in production.
With it you can collect metrics, store your infrastructure history (time series) and compute alert rules to notify your SRE/Devops/Sysadmin teams. Features
-
You can define your own monitoring endpoints and secure them through iTop configuration.
-
For each endpoint you can configure which set of KPIs will be returned.
-
If you have specific requirement that are not covered by the existing metrics, you can also code your own metrics via PHP APIs.
Follow below link to have up-to-date Official Combodo documentation:
https://www.itophub.io/wiki/page?id=extensions:combodo-monitoring
In order to use this extension, You'll spend most of your time within the configuration:
$MyModuleSettings = array(
'combodo-monitoring' => array (
'authorized_network' => '',
'access_token' => '123',
'metrics' => array (
'collection1' => array(
//Metrics will be configured here later on
),
'collection2' => array(
//Another collection of metrics can be placed here
),
//... you can add as many collection as you want
),
),
);Then, Prometheus just has to call this url:
Lets deep dive into each configuration key we've just seen:
This must contains a list of authorized IP under this form : /!\ TODO /!\
Since this extension can expose sensible information, you should allow only private network!!
This token is required to access the pages.
Since it is given as a GET parameter (named access_token), you should only use https pages.
Here we are, the final goal of this extension is to expose metrics to a monitoring agent.
Since not all metrics should be pulled with the same frequency, you have to group them within collections.
Their name is free, Prometheus just have to ask for one of them using the GET parameter collection.
Let's see some examples of metric within a collection:
array(
'itop_backup' =>
array (
'description' => 'backup retention_count',
'conf' => ['MyModuleSettings', 'itop-backup', 'retention_count'],
),
),
'count_users' =>
array (
'description' => 'Nb of users',
'oql_count' => [
'select' => 'SELECT URP_UserProfile JOIN URP_Profiles AS URP_Profiles_profileid ON URP_UserProfile.profileid =URP_Profiles_profileid.id',
'groupby' => ['profile' => 'URP_Profiles_profileid.friendlyname'],
]
),The first one, named itop_backup gather data from the configuration file, while the second uses an OQL to count matching objects.
As you can see, each individual metric is typed in order to perform specialized data gathering.
From now on wee will name them "Metric readers"
Let's see all the builtins Metric readers:
As seen before, this reader simply extract data from itop's configuration.
You can either read from MySettings or from MyModuleSettings
Example:
array(
'cron_max_execution_time' =>
array (
'description' => 'cron max execution time',
'conf' => ['MySettings', 'cron_max_execution_time'],
),
),
array(
'itop_backup' =>
array (
'description' => 'backup retention_count',
'conf' => ['MyModuleSettings', 'itop-backup', 'retention_count'],
),
),If you want to extract data from multidimensional arrays, simply add all the keys. example:
array(
'monitoring_access_key' =>
array (
'description' => 'The monitoring access key',
'conf' => ['MyModuleSettings', 'combodo-monitoring', 'foo', 'key1', 'key2', 'key3'],
),
);
//This will access the string `'I am accessed'` within this structure :
$MyModuleSettings = [
'combodo-monitoring' => [
'foo' => [
'key1' => [
'key2' => [
'key3' => [
'I am accessed'
]
]
]
]
]
];This Reader is the simplest possible one: it count the number of result .
Example:
[
'oql_count' => [
'select' => 'SELECT User',
],
'description' => 'ordered users',
]This Reader count the number of unique result for a given attribute.
! This should not be used on massive data !
Example:
[
'description' => 'number of used profiles',
'oql_count_unique' => [
'select' => 'SELECT URP_Profiles JOIN URP_UserProfile ON URP_UserProfile.profileid = URP_Profiles.id',
'groupby' => ['name' => 'name'],
],
]This Reader count the number of rows for each group. The labels names are the keys of the group by alias, and the label values are the value of the grouped column
Example:
[
'description' => 'ordered users',
'oql_groupby' => [
'select' => 'SELECT User',
'groupby' => ['first_name' => 'first_nameAlias'],
],
]This reader expose the value for each column as labels, the column key being in monitoring labels. value of the metric comes from 'value'.
- Examples1: simple OQL:
[
'description' => 'ordered users',
'oql_select' => [
'select' => 'SELECT User',
'labels' => ['firtname' => first_name', 'lastname' => last_name'],
'value' => 'org_id' //make no sense except this is an integer
// optional:
'orderby' => ['first_name' => true, '_itop_count_' => false],
// optional:
'limit_count' => 0,
// optional:
'limit_start' => 0,
],
]Please note that orderby, limit_count and limit_start are optionals, and take the standard iTop's syntax.
- Examples: OQL that returns different objects*:
[
'description' => 'ordered users',
'oql_select' => [
'select' => 'SELECT up, p FROM URP_UserProfile AS up JOIN URP_Profiles AS p ON up.profileid = p.id WHERE up.profileid = 1',
'labels' => [ 'profile' => 'p.name', 'name' => 'up.profile' ]
'value' => 'up.profileid'
],
]Please note how to use aliases to set metric labels or value.
This reader reports the remaining number of days before the expiration of an X509 certificate.
Example:
'metrics' => [
'certificate-exipration' => [
[
'description' => 'SSL Certificate Expiration',
'custom' => ['class' => \Combodo\iTop\Monitoring\CustomReader\X509CertificateReader::class],
'certificate_file' => '/etc/letsencrypt/live/some-domain/cert.pem',
],
],This reader is by far the most complicated, but it is also the one that can barely collect everything.
The principe is simple:
This reader will accept to call any class that implements Combodo\iTop\Monitoring\MetricReader\CustomReaderInterface.
So simply put any such class name into the 'class' property.
Example:
[
'custom' => ['class' => CustomReaderImpl::class],
'description' => 'descriptionFromConf'
//As this configuration array is passed to the class, feel free to add any relevant configuration for your use case.
]This will call the CustomReaderImpl that YOU have to implemnt, for example, you can declare:
namespace Combodo\iTop\Monitoring\Test\MetricReader\CustomReaders;
use Combodo\iTop\Monitoring\Model\Constants;
use Combodo\iTop\Monitoring\Model\MonitoringMetric;
class CustomReaderImpl implements \Combodo\iTop\Monitoring\MetricReader\CustomReaderInterface
{
private $aMetricConf;
public function __construct($aMetricConf)
{
$this->aMetricConf = $aMetricConf;
}
/**
* @inheritDoc
*/
public function GetMetrics(): ?array
{
return [ new MonitoringMetric('foo', $this->aMetricConf[Constants::METRIC_DESCRIPTION] ?? '', 42, ['bar' => 'baz'])];
}
}For a functional understanding of this extension, please read the test: \CombodoMonitoringTest
For more unit test, read the others