====== Generic event server ======

===== Purpose =====

This plugin makes possible to collect generated metrics, alerts and monitored landscape structure from a third party software by using a REST API.
When the Generic event server plugin is created and active, all generated alarms and metrics, will be stored in separate queues.

These queues will be polled via a REST API to collect alarms and metrics by chunks.
Once the plugin is active, it is necessary to poll queues very regularly.

**Warning:** Queues are not persistent and are stored in memory. They will be lost if the Pro.Monitor server is restarted. 

===== Configuration =====

  * From the plugin menu of Pro.Monitor, select ''Generic event server'' in the plugin drop down and press ''Add''
  * The plugin has the following parameters:

^ Parameter ^ Description ^ Mandatory ^
| Name | Give a name to the plugin | Yes |
| Allowed IPs | To restrict the IPs allowed to call the service, Use ''*'' for all | Yes |
| Max alarm queue size | The size of the queue holding the alarms | Yes |
| Max metric queue size | The size of the queue holding the metrics | Yes |
| Enable cache | Activate metrics caching | No|
| Track distinct time series | If enabled, Pro.Monitor will record distinct timeseries (see explanation below)| Yes | 

**Note:** To preserve server memory, alarms and metrics queue have a maximum size. If a queue is full, any new element will replace the oldest one.

**Estimated memory consumption of alarms and metrics queues: 200 KB for chunk of 1000 alarms/metrics**

===== Authorizations =====

The API can be used only with an authenticated user. He must have the **monitoring** authorization.

The API call must always include an ''Authorization'' header with Basic authentication key.

===== API Endpoints =====
  * The API is described in the [[..:..:api:events|API section]]

===== Metrics caching =====
  * If enable cache is active, collected metrics will stop to be removed from the queue on each API call.
  * Caching can be use when several external applications must be able to retrieve the metrics data.
  * The cache stores the last generated metric from a given metric key and tag association.

===== Distinct time series tracking =====
  * The the tracking is active, the distinct times series sent to Datadog will be tracked down
  * This gives the possiblility to know how many metrics have been created in datadog
  * This also allows to analyze the cardinality of the metrics and fine tune the configuration
  * The list of distinct time series can be collected by this HTTP API call:
<code>GET /plugins/statistics/distinct_ts?type=GENERIC_EVENT_SERVER</code>