Zenoss 5 Integration Guide

Zenoss is a very popular open source network, server and application monitoring system used by thousands of IT organizations. It provides one of the best event management systems available in any open source monitoring system. The plug-in architecture of Zenoss allows it to be extensible by anyone.PagerDuty extends Zenoss’s functionality by providing on-call scheduling, alerts and incidents tracking through the PagerDuty API. You are notified of the most critical Zenoss events by PagerDuty so you are able to take immediate action.

This guide describes how to integrate your Zenoss 5 installation with the PagerDuty ZenPack. You might need to slightly alter these instructions depending on your exact Linux distribution and your Zenoss configuration. If you are having trouble completing the installation, please contact us.

Looking for Zenoss 4? Go here

Looking for Zenoss 3? Go here

In PagerDuty

1. From the Configuration menu, select Services.
2. On your Services page:If you are creating a new service for your integration, click +Add New Service.If you are adding your integration to an existing service, click the name of the service you want to add the integration to. Then click the Integrations tab and click the +New Integration button.
   

1. Select your app from the Integration Type menu and enter an Integration Name.If you are creating a new service for your integration, in General Settings, enter a Name for your new service. Then, in Incident Settings, specify the Escalation Policy, Notification Urgency, and Incident Behavior for your new service.
2. Click the Add Service or Add Integration button to save your new integration. You will be redirected to the Integrations page for your service.
   
3. Copy the Integration Key for your new integration:

Note: You may create multiple Generic API integrations for use with different PagerDuty policies. Zenoss 5 can be aligned to any number of different PagerDuty accounts and Generic API integrations.

In the Zenoss 5 server shell:

1. Login to your Zenoss server’s shell as root and run the following commands to install the ZenPack.

   wget http://wiki.zenoss.org/download/zenpacks/ZenPacks.PagerDuty.APINotification/1.1.0/ZenPacks.PagerDuty.APINotification-1.1.0.egg
   serviced service run zope zenpack-manager install ZenPacks.PagerDuty.APINotification-1.1.0.egg

2. From the Zenoss web interface, go to ADVANCED > Settings > PagerDuty.
3. You can then enter your PagerDuty subdomain and v2 API key then click Apply. For more information on API Access Keys, read this knowledge base article.
   Note: You will not use the service API key here. Please read the aforementioned article for more information.
   Note: Once you hit the Apply button, the list of all PagerDuty Generic API integrations will populate. If your integration does not show up, confirm your settings and verify that your integration is of type Zenoss 5 or Generic API within PagerDuty.
4. Go to EVENTS > Triggers and click on the + button to add a trigger.
5. Enter an ID for your trigger. We’re using PagerDuty, but you may want to use something more descriptive, such as “Critical Alert”. Click the SUBMIT button once you’ve entered an ID.
6. Select your trigger and click on the gear icon to configure it.
7. Configure the trigger to the rule(s) that you would like to trigger alerts within PagerDuty. Once you have completed configuring your rule(s), click on the SUBMIT button.
8. Click on Notifications from the left-hand menu, then click on the + icon to add a new notification.
9. Enter an ID for the notification, and select PagerDuty for the Action. In this example we use PagerDuty for the id, although you may want to use something more descriptive. Click on the SUBMIT button once the form is complete.
10. Select your new notification and click on the gear icon to configure it.
11. Check the Enabled box, then select the trigger that you made earlier in the drop down box and click the Add button. The trigger should show up in the lower box under Triggers.
12. Click on the Content tab. Now select (or type) the PagerDuty integration in the drop-down menu. This is the integration that will get notified when an alert is triggered within Zenoss. If you are connecting to multiple PagerDuty services/integrations from Zenoss, this is where you would select the different services or integrations. The PagerDuty ZenPack will automatically populate the remaining fields. Many of these fields are customizable. For a full list of available variables, check the FAQ. Click the SUBMIT button once you’re finished.

Post Installation

To verify that everything is working, you’ll want to trigger a new alert within Zenoss, which will in-turn trigger an incident within PagerDuty. When viewing the details for an incident, you can use the View in Zenoss link to take you to the event within your Zenoss web interface.

FAQ

How do I setup Zenoss to work with multiple PagerDuty integrations?

This is easy to do with the current integration, as each Zenoss notification can be associated with a PagerDuty integration. You would just need to add multiple notifications within Zenoss to tie to each of your PagerDuty integrations.

What if a Zenoss notification happens while my network is down?

If a PagerDuty server can’t be reached for any reason, Zenoss will re-send the notification to PagerDuty every 60 seconds. This is configurable under the notification configuration.

Since Zenoss needs my external Internet connection to send failure reports to PagerDuty, how will I receive notification if our site loses external connectivity?

You should configure an external ping check service to monitor your site’s external connectivity. Of course, you can use PagerDuty to forward alerts from these services.

I unacknowledged an alert within Zenoss, but PagerDuty still shows it as acknowledged, what happened?

PagerDuty does not support unacknowledged incidents. The event will remain as acknowledged within PagerDuty until it is resolved.

How can I customize the details of my alerts?

Other event properties can be found in Section 7.1.2 (Page 89) of the ZenOSS Core Administration Guide. Note: The Incident Key needs to be unique per incident.

Still need help?

Please contact us if you’re unable to sort out the difficulty.