Skip to main content
Version: ⭐ 22.04

Opsgenie integration

Opsgenie + Centreon Integration Benefits​

  • Manage your notifications when an alert is detected by Centreon.
  • Deduplicate your alerts from Centreon
  • Distinguish alerts from incidents using Centreon BAM and Opsgenie
  • Create reporting based on your notifications from Centreon

How it Works​

  • Every time a service, a host or a BA state is checked, the event passes through Centreon Broker, which loads the Stream Connector to send state changes.
  • State changes can occur in case of an anomaly detection.
  • An alias is generated for each alert to make use of Opsgenie deduplication:

architecture

Requirements​

  • Opsgenie integration requires two different API key. The first one is an integration API key coming from the Rest API HTTPS over JSON integration. This integration must have the Create and Update Access. The second access is an API key coming from the APP Settings. This key must have the Create and Update access right.
  • It is also necessary to use a Centreon account with either admin privileges or Export configuration and Broker configuration menu access in the WUI, as well as a root access in command-line interface.

Support​

If you need help with this integration, depending on how you are using Centreon, you can:

  • Commercial Edition customers: please contact the Centreon Support team.
  • Open Source Edition users or Centreon IT-100 users (free versions): please reach our Community Slack where our users and staff will try to help you.

Integration Walkthrough​

In Opsgenie​

Warning, this documentation was written in February 2021, it is possible that certain elements described below became obsoletes due to changes on Opsgenie.

Opsgenie integration: alerts​

  1. From the Settings menu, select Integration list.
  2. In the integration list, add an API integration (Rest API HTTPS over JSON).
  3. Head over the Configured integrations menu and edit your API integration to enable it if it is not. You also must to give it a Create and Update Access. Save your configuration and the API Key that is mandatory to send alerts from Centreon to Opsgenie. This API key is referred as integration_api_token in the Centreon configuration.

Opsgenie integration: incidents​

  1. Before starting, this integration will only work if you are using the Centreon BAM module.
  2. From the Settings menu, select API key management in the subcategory APP SETTINGS.
  3. In the API key management menu, add a new API key with Create and Update access
  4. Save your configuration and your Api key that is mandatory to send incidents from Centreon to Opsgenie. This API key is referred as app_api_token in the Centreon configuration.

In Centreon​

Installation​

Login as root on the Centreon central server using your favorite SSH client.

In case your Centreon central server must use a proxy server to reach the Internet, you will have to export the https_proxy environment variable and configure yum to be able to install everything.

export https_proxy=http://my.proxy.server:3128
echo "proxy=http://my.proxy.server:3128" >> /etc/yum.conf

Now that your Centreon central server is able to reach the Internet, you can run:

yum install -y lua-curl epel-release

These packages are necessary for the script to run. Now let's download the script:

wget -O /usr/share/centreon-broker/lua/opsgenie.lua https://raw.githubusercontent.com/centreon/centreon-stream-connector-scripts/master/centreon-certified/opsgenie/opsgenie-apiv1.lua
chmod 644 /usr/share/centreon-broker/lua/opsgenie.lua

The Opsgenie Stream Connnector is now installed on your Centreon central server!

Broker configuration​

  1. Login to the Centreon WUI using an administrator account.
  2. Navigate to the Configuration > Pollers menu and select Broker configuration.
  3. Click on the central-broker-master broker configuration object and navigate to the Output tab.
  4. Add a new Generic - Stream connector output.
  5. Name it as you want (eg. Opsgenie) and set the right path for the LUA script: /usr/share/centreon-broker/lua/opsgenie.lua.
  6. Add at least one string parameter. That parameter is a key that must be configured. The parameter name must be app_api_token (for the alerts) or integration_api_token (for the incidents, requires the Centreon BAM module). If you want to use both aspects then you need to add both parameters in your configuration
NameTypeValue
app_api_tokenString<paste your key here>
integration_api_tokenString<paste your key here>
  1. Save your configuration, then navigate to the Configuration > Pollers menu and select Pollers.
  2. Select the Central poller and click on Export configuration.
  3. Keep Generate Configuration Files and Run monitoring engine debug (-v) checked and select Move Export Files and then click on the Export button.
  4. Restart the cbd service:
systemctl restart cbd

Now your central server has loaded the Opsgenie Stream Connector and has started to send data!

To make sure that everything goes fine, you should have a look at central-broker-master.log and connector-opsgenie.log, both located in /var/log/centreon-broker.

Advanced configuration​

Parameters table

NameTypeDefault valueDescription
api_urlStringhttps://api.opsgenie.comOpsgenie api address. Use https://api.eu.opsgenie.com if your instance is in Europe
proxy_addressStringIf needed, the address of the proxy server (requires proxy_port option)
proxy_portStringThe port of the proxy server
proxy_usernameStringIf needed, the proxy user (requires proxy_password option)
proxy_passwordStringthe proxy user password
logfileString/var/log/centreon-broker/connector-opsgenie.loglogfile for the stream connector
host_statusString0,1,2send event for up, down and unreachable hosts
service_statusString0,1,2,3send event for ok, warning, critical, unknown services
ba_statusString0,1,2send event for ok, warning, critical business activities
hard_onlyNumber1Only send events in hard state
acknowledgedNumber0Only send events that are not acknowledged
element_typeStringhost_status,service_status,ba_statusSend host, service, BA centreon status event
category_typeStringneb,bamFilter out non neb or bam events
in_downtimeNumber0Only send events that are not in downtime
max_buffer_sizeNumber1Send events one at a time
max_buffer_ageNumber5Store events for 5 second before sending them unless max_buffer_size is reached before
max_stored_eventsNumber10Keep event in cache to avoid sending duplicated events, change with caution
skip_anon_eventsNumber1Do not send events from hosts or services that are not found in the broker cache
skip_nil_idNumber1Do not send events from objects that do not have an ID (meta services most of the time)
accepted_hostgroupsStringList of hostgroups in which the host must be (coma separeted eg: grp1,grp2,grp3)
date_formatString%Y-%m-%d %H:%M:%SThe default date format for converted timestamps (https://www.lua.org/pil/22.1)
host_alert_messageString{last_update_date} {hostname} is {state}The default message for host alerts. See host event macros for more details about macros
host_alert_descriptionStringThe default description of a host alert. See host event macros for more details about macros
host_alert_aliasString{hostname}_{state}The default alias for a host alert, useful for alert deduplication. See host event macros for more details about macros
service_alert_messageString{last_update_date} {hostname} // {serviceDescription} is {state}The default message for service alerts. See service event macros for more details about macros
service_alert_descriptionStringThe default description of a service alert. See service event macros for more details about macros
service_alert_aliasString{hostname}_{serviceDescription}_{state}The default alias for a service alert, useful for alert deduplication. See service event macros for more details about macros
ba_incident_messageString{baName} is {state}, health level reached {level_nominal}The default message for a ba incident. See BA event macros for more details about macros
ba_incident_descriptionStringThe default description of a ba incident. See BA event macros for more details about macros
enable_incident_tagsNumber1Add tags to incidents
get_bvNumber1Add BV names as tags if enable_incident_tags is set to 1
ba_incident_tagsStringcentreon,applicationsList of tags for an incident. must be coma separeted. It will automatically add all the BV related to the BA as tags
enable_severityNumber0If set to 1, tries to match a Centreon severity value to an Opsgenie priority.
priority_must_be_setNumber0Will drop the alert if set to 1 and it can't match the severity with a priority according to the relation set in the priority_matching parameter
priority_matchingStringP1=1,P2=2,P3=3,P4=4,P5=5Links priorities to severities with the following syntax: priority_name=severity_value,priority_name=severity_value.
opsgenie_prioritiesStringP1,P2,P3,P4,P5Coma separeted list of Opsgenie priorities

Remarks

  • A value of 2 for log_level is fine for initial troubleshooting, but can generate a huge amount of logs if you monitor a lot of hosts. In order to get less log messages, you should keep it a 1.

How to Uninstall​

  1. Login to the Centreon WUI using an administrator account.
  2. Navigate to the Configuration > Pollers menu and select Broker configuration.
  3. Click on the central-broker-master broker configuration object and navigate to the Output tab.
  4. Delete the Generic - Stream connector output by clicking on the red circled cross at the end of the line.
  5. Save your configuration, then navigate to the Configuration > Pollers menu and select Pollers.
  6. Select the Central poller and click on Export configuration.
  7. Keep Generate Configuration Files and Run monitoring engine debug (-v) checked and select Move Export Files and then click on the Export button.
  8. Restart the cbd service:
systemctl restart cbd

The Stream Connector is not loaded anymore!

  1. Optionally, you can even delete the script file:
rm -f /usr/share/centreon-broker/lua/opsgenie.lua

Macros​

Macros are a tool to create dynamic messages depending on the event you want to send. They must be enclosed by {} (eg: {hostname}). If a macro is a time type macro then you will be able to use _date suffix to convert it to a human readable format. You can Change this format using the string parameter date_format (eg: {last_update} is a timestamp macro. You can use {last_update_date} to have it converted)

Host event macros​

Macro name
hostname

All the Properties in the Host status table are also usable

Service event macros​

Macro name
hostname
serviceDescription

All the Properties in the Service status table are also usable

BA event macros​

Macro name
baName
baDescription

All the Properties in the Ba status event table are also usable