Skip to content

Commit

Permalink
Review
Browse files Browse the repository at this point in the history
  • Loading branch information
@cg-tw
cg-tw committed Jun 6, 2024
1 parent 8cba436 commit dbdd679
Showing 1 changed file with 156 additions and 103 deletions.
259 changes: 156 additions & 103 deletions pp/integrations/plugin-packs/getting-started/how-to-guides/telegraf.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,123 +7,44 @@ import TabItem from '@theme/TabItem';

## Introduction

### General
The Telegraf agent collects metrics and computes statuses on the servers it monitors, and sends them to Centreon.
Centreon's OpenTelemetry processor allows it to understand data sent in OpenTelemetry format.

Centreon is able to gather monitoring data (metrics and statuses) from Telegraf agent.
This can be an added value if you need an OpenTelemetry Agent, able to execute nagios plugins.
Developped by InfluxDB, the Telegraf agent can be installed on Windows servers. Centreon Engine is able to send the configuration of monitored resources to the agent (existing hosts, thresholds...), so that the agent can execute checks and compute the statuses of these resources.

### Nagios input data format

Centreon's Telegraf integration is based on native [Nagios input data format](https://docs.influxdata.com/telegraf/v1/data_formats/input/nagios/), which allow Telegraf to execute Nagios plugins.
Centreon and custom plugins are handled by Telegraf, which can return metrics and statuses.

### Telegraf configuration server

Centreon Engine now onboard natively a Telegraf agent Configuration manager.
This component, developed by Centreon is dedicated to provide up-to-date configuration to the Telegraf.
> Configuration is updated on the Agent only during starting or reload.
As they are Nagios-based, both Centreon and custom plugins are compatible with the agent. This is because Centreon's Telegraf integration is based on the native [Nagios input data format](https://docs.influxdata.com/telegraf/v1/data_formats/input/nagios/).

### Limitations

Due to Telegraf or Centreon constraints, the following limitations need to be considered.
* Telegraf manual reload on host is needed whenever the configuration is updated in Centreon
* Unknown metrics (ie : from OTLP receivers) are not supported
* Only metrics and statuses are returned (no outputs)
* Network connections are one way only : agents to poller (ie : Host in DMZ will need a poller in DMZ)
* As for any Agent, Agent update is necessary to update plugins (no autoupdate)

## Download & Installation

Download and install instructions are documented [here](https://docs.influxdata.com/telegraf/v1/install/).

## Configuration in Centreon

### Install monitoring packs

For Windows host : Windows Telegraf AGENT
For Linux host : Linux Telegraf AGENT

### Create connector
* Due to Telegraf limitations, the configuration of resources known to the agent is only updated when you start or [reload the agent](#reload-the-agent) (typically, you would do that after [deploying the configuration](/docs/monitoring/monitoring-servers/deploying-a-configuration)). Technically, the agent requests an up-to-date configuration from Centreon.
* Only known metrics (i.e., the metrics for the hosts and services created in Centreon) are sent to Centreon. Metrics for unknown hosts or services are discarded.
* Only metrics and statuses are returned (no outputs).
* Network connections are one-way only: data goes from the agent to the poller. This means that a host in a DMZ will need a poller in this DMZ.
* As for any agent, you need to update the agent to update the plugins (there is no auto-update). XXXXXXXXXX ?

Go in Configuration Commands Connectors
## Step 1: Install the agent and the Centreon plugins on the host

![image](../../../../assets/integrations/plugin-packs/how-to-guides/telegraf-connector.png)
### Download and install the agent on the host

Create a new connector with the following values :

* Connector Name : Telegraf
* Connector Description : Telegraf
* Commande Line :
~~~
open_telemetry --processor=nagios_telegraf --extractor=attributes --host_path=resource_metrics.scope_metrics.data.data_points.attributes.host --service_path=resource_metrics.scope_metrics.data.data_points.attributes.service
~~~
**open_telemetry** tell to Engine that it’s not a real connector

**--processor=nagios_telegraf**
All datas received are stored in fifos.
This processor will pop these datas in order to build check results

**--extractor=attributes --host_path=resource_metric…..attributes.host --service_path=resource……...service**
This extractor will search host name and service description in these open telemetry attributes

* Used by command :
OS-Windows-Telegraf-Agent-Certificates
OS-Windows-Telegraf-Agent-Ntp
OS-Windows-Telegraf-Agent-Pending-Reboot
OS-Windows-Telegraf-Agent-Sessions
OS-Windows-Telegraf-Agent-Updates

* Connector Status : Enabled

### Configure Engine
1. [Download the agent](https://docs.influxdata.com/telegraf/v1/install/) on all the servers you want to monitor.

Create otl_server.json with the following content.
2. Install the agent on the servers using the following command (replace the placeholders by your values):

```shell
.\telegraf.exe --service install --config "http(s)://<ip_poller>:<port poller>/engine?host=<host_to_monitor>"
```
broker_module=/usr/lib64/centreon-engine/libopentelemetry.so /etc/centreon-engine/otl_server.json

{
"otel_server": {
"host": "0.0.0.0",
"port": 4317
},
"max_length_grpc_log": 0,
"telegraf_conf_server": {
"http_server": {
"port": 1443,
"encryption": true,
"certificate_path": "/tmp/otel/server.crt",
"key_path": "/tmp/otel/server.key"
},
"telegraf_conf": {
"interval": "10s",
"service_address": "127.0.0.1:4317"
}
}
}
```

**otel_server** gRPC server where collector will connect to and push datas
**telegraf_conf_server** Telegraf agent will connect to engine to get their configuration
- **http_server** http(s) server used by telegraf collectors to get their configuration.
- **telegraf_conf** some Telegraf configuration such as check period and where to push datas (otel_server config seen from Telegraf agent side)

### Add new Broker module
Go to Configuration Pollers Engine configuration Data
The arguments in this command will allow Telegraf to know where to fetch the configuration of the resources that it must monitor (i.e on the poller or the central, according to the IP address you have entered in the command).

On "Multiple Broker Module", click on "Add a new entry".
### Deploy the Centreon plugins on the host

Add the following entry :
```
/usr/lib64/centreon-engine/libopentelemetry.so /etc/centreon-engine/otl_server.json
```


## Monitoring
The Centreon plugins will execute the checks on the host.

### Deploy Centreon plugins on hosts

#### Linux
<!--
<Tabs groupId="sync">
<TabItem value="Linux" label="Linux">
##### Enable our plugins repository and install plugin
Expand Down Expand Up @@ -271,11 +192,143 @@ apt -y install centreon-plugin-operatingsystems-linux-local
</TabItem>
</Tabs>
</TabItem>
<TabItem value="Windows" label="Windows">
-->

On the hosts you want to monitor, download and execute the corresponding [package for Windows](https://github.com/centreon/centreon-nsclient-build/releases/download/20240325/centreon_plugins.exe).


<!--
</TabItem>
<Tabs>
-->

## Step 2: Configure Centreon

### Install the monitoring connector that will receive data from Telegraf

1. On your central server, go to **Configuration > Monitoring Connector Manager**.
2. [Install](/docs/monitoring/pluginpacks/#installing-a-monitoring-connector) the **Windows Telegraf Agent** monitoring connector.
<!-- For Linux hosts : Linux Telegraf AGENT-->

### Create the Telegraf connector

Install the Open Telemetry processor on your central server:

1. Go to **Configuration > Commands > Connectors**.
2. Create a new connector with the following values:

| Parameter | Value|
| --------- | ---- |
| Connector Name | Telegraf |
| Connector Description | Telegraf |
| Command Line |```open_telemetry --processor=nagios_telegraf --extractor=attributes --host_path=resource_metrics.scope_metrics.data.data_points.attributes.host --service_path=resource_metrics.scope_metrics.data.data_points.attributes.service``` |
| Used by command |<ul><li>OS-Windows-Telegraf-Agent-Certificates</li><li>OS-Windows-Telegraf-Agent-Ntp</li><li>OS-Windows-Telegraf-Agent-Pending-Reboot</li><li>OS-Windows-Telegraf-Agent-Sessions</li><li>OS-Windows-Telegraf-Agent-Updates</li></ul>|
| Connector Status | Enabled |

### Configure Engine

1. On the poller that will receive the data from the agent, create the following file:

```shell
touch /etc/centreon-engine/otl_server.json
```

2. Enter the following contents. This will allow the poller to receive the data that the agent will send.

<Tabs groupId="sync">
<TabItem value="Unencrypted flows" label="Unencrypted flows">

* Enter the IP address of the poller in the **service_address** field.
* The **interval** field is the frequency of checks performed by Telegraf, and should be set to 60 seconds as it is the frequency of Engine checks.

```json
broker_module=/usr/lib64/centreon-engine/libopentelemetry.so /etc/centreon-engine/otl_server.json

{
"otel_server": {
"host": "0.0.0.0",
"port": 4317,
"encryption": false
},
"max_length_grpc_log": 0,
"telegraf_conf_server": {
"http_server": {
"port": 80,
"encryption": false
},
"telegraf_conf": {
"interval": "60s",
"service_address": "xxx.xxx.xxx.xxx:4317"
}
}
}
```

</TabItem>
<TabItem value="Encrypted flows" label="Encrypted flows">

* Enter the IP address of the poller in the **service_address** field.
* The **interval** field is the frequency of checks performed by Telegraf, and should be set to 60 seconds as it is the frequency of Engine checks.

Two flows will be encrypted: the configuration sent by the poller to the agent, and the metrics sent by the agent to the poller.

1. Create the certificates.
2. Copy the certificates on to the poller that will receive data from Telegraf.
3. Enter the path to the certificates in the **otl_server.json** file.

```json
broker_module=/usr/lib64/centreon-engine/libopentelemetry.so /etc/centreon-engine/otl_server.json

{
"otel_server": {
"host": "0.0.0.0",
"port": 4317
},
"max_length_grpc_log": 0,
"telegraf_conf_server": {
"http_server": {
"port": 1443,
"encryption": true,
"certificate_path": "/tmp/otel/server.crt",
"key_path": "/tmp/otel/server.key"
},
"telegraf_conf": {
"interval": "60s",
"service_address": "xxx.xxx.xxx.xxx:4317"
}
}
}
```

</TabItem>
</Tabs>

### Add a new Broker module

1. Go to **Configuration > Pollers > Engine configuration**, then click on the poller you want to monitor your resources.
2. On the **Data** tab, in the **Broker module** section, in the **Multiple Broker Module** parameter, click on **Add a new entry**.
3. Add the following entry :

```shell
/usr/lib64/centreon-engine/libopentelemetry.so /etc/centreon-engine/otl_server.json
```

The Telegraf agent is now able to communicate with Centreon. You can set up the monitoring of your hosts.

## Step 3: Monitoring a host with the Telegraf agent

### Create hosts using templates

#### Windows
On the central server, [create hosts](/docs/monitoring/basic-objects/hosts) and apply to them templates provided by the **Windows Telegraf AGENT** monitoring connector.

Download and execute package for [Windows](https://github.com/centreon/centreon-nsclient-build/releases/download/20240325/centreon_plugins.exe)
### Reload the agent

To let the agent know about the hosts you just created and start monitoring them, run the following command on the host:

### Create hosts using templates
```shell
telegraf.exe --service start
telegraf.exe --service stop
```

0 comments on commit dbdd679

Please sign in to comment.