ZenPacks

Portal Integration ZenPack

Extends Zenoss JSON API to better support integration in external portals.

Support

This ZenPack is included with commercial versions of Zenoss and enterprise support for this ZenPack is provided to Zenoss customers with an active subscription.

Background

This ZenPack provides JSON API extensions commonly needed for integration with external portals. Search, identity resolution and fetching performance data, events, and status are available.

Features

The following JSON API methods are available in the IdentificationRouter router:

listResolvers()
Return the list of available device/component name resolution schemes.
resolve(id, idScheme, allowMultiple)
Return the resolved device/component for the id specification using the specified idScheme.

The following JSON API methods are available in the PortalRouter router:

fetchMetricValues(startTime, endTime, specs, allowMultiple, echoInput)
Return the raw metric values for the time range for the requested metrics.
fetchEvents(startTime, endTime, specs, allowMultiple, echoInput)
Return the event information for the time range for the requested filters.
fetchThresholds(startTime, endTime, specs, allowMultiple, echoInput)
Return the threshold status information for the time range for the requested filters.

Usage

The example scripts are located in the bin directory.

Identification

portal_id
Example utility to test the identification router.
######################################################################
#
# Copyright 2012 Zenoss, Inc.  All Rights Reserved.
#
######################################################################
 
 
__doc__ = """portal_id
Example utility to test the identification router.
"""
 
from pprint import pprint
 
import Globals
 
from ZenPacks.zenoss.PortalIntegration.RouterCaller import RouterCaller
 
 
if __name__=="__main__":
    rc = RouterCaller()
    rc.setup()
    result = rc.request('IdentificationRouter', 'id_router', 'listResolvers', data=[])
    pprint(result)
    print "=" * 40
    data={'id':{'uid': '/zport/dmd/Devices'}, 'idScheme':'uid'}
    result = rc.request('IdentificationRouter', 'id_router', 'resolve', data=[data])
    pprint(result)

Sample successful output:

{u'action': u'IdentificationRouter',
 u'method': u'listResolvers',
 u'result': {u'resolvers': [u'search', u'global_catalog', u'uid', u'uuid'],
             u'success': True},
 u'tid': 1,
 u'type': u'rpc',
 u'uuid': u'0fea939c-319b-4486-8680-d7a27a4209d7'}
========================================
{u'action': u'IdentificationRouter',
 u'method': u'resolve',
 u'result': {u'message': u'Found object <DeviceClass at Devices>',
             u'success': True},
 u'tid': 2,
 u'type': u'rpc',
 u'uuid': u'cdd8859b-8975-4333-9500-219e6a44d377'}

Sample error output:

{u'action': u'IdentificationRouter',
 u'method': u'resolve',
 u'result': {u'message': u'No device/component could be found with that id',
             u'success': False,
             u'type': u'error'},
 u'tid': 2,
 u'type': u'rpc',
 u'uuid': u'1c5b2238-f389-4ce3-b063-77feb6d4be59'}

Metrics

portal_fetch_metrics
#!/bin/bash
 
#
# cURL example to grab data
# 
 
MYUSERNAME="admin"
MYPASS="zenoss"
MYSERVER="belinda-ova:8080"
MYDEVICE="10.171.20.1"
MYMETRIC="ssCpuSystem"
MYPROTO="http"
 
MYDATA="[{\"startTime\":\"November 20, 2015 00:00:00\",\"endTime\":\"November 28, 2015 00:00:00\",\"specs\":[{\"id\":{\"uid\":\"/zport/dmd/Devices/Server/Linux/devices/$MYDEVICE\"},\"idScheme\":\"uid\",\"metricIds\":\"$MYMETRIC\"}]}]"
 
curl -u "$MYUSERNAME:$MYPASS" -X POST -H "Content-Type: application/json" -d "{\"action\":\"PortalRouter\",\"method\":\"fetchMetricValues\",\"data\":$MYDATA,\"tid\":1}" -k "$MYPROTO://$MYSERVER/zport/dmd/fetch_router"
 
echo
portal_metrics.py
Example utility to test the portal router fetch metrics calls.
######################################################################
#
# Copyright 2012 Zenoss, Inc.  All Rights Reserved.
#
######################################################################
 
 
__doc__ = """
Example utility to test the portal router fetch metric calls.
"""
 
from pprint import pprint
 
import Globals
 
from ZenPacks.zenoss.PortalIntegration.RouterCaller import RouterCaller
 
 
if __name__=="__main__":
    rc = RouterCaller()
    rc.setup()
    data={
          'startTime':'April 16, 2012 04:00:00',
          'endTime':'April 16, 2012 17:00:00',
          'specs':[
              {'id':{'uid': '/zport/dmd/Devices/Server/Linux/devices/localhost.localdomain/os/interfaces/lo'},
               'idScheme':'uid',
               #'metricIds': []
               'metricIds': 'ifOperStatus'
 
               }
          ]
    }
    result = rc.request('PortalRouter', 'fetch_router', 'fetchMetricValues', data=[data])
    pprint(result)

Sample successful output:

{u'action': u'PortalRouter',
 u'method': u'fetchMetricValues',
 u'result': {u'msg': [{u'input': {u'id': {u'uid': u'/zport/dmd/Devices/Server/Linux/devices/localhost.localdomain/os/interfaces/lo'
},
                                  u'idScheme': u'uid',
                                  u'metricIds': [u'ifOperStatus']},
                       u'success': True,
                       u'uuid': u'02d6041e-9c87-4964-8d50-005cc6c8fc76',
                       u'values': {u'ifOperStatus': [1.0,
                                                     1.0,
                                                     # Truncated
                                                     1.0,
                                                     1.0,
                                                     1.0,
                                                     1.0]}}],
             u'success': True},
 u'tid': 1,
 u'type': u'rpc',
 u'uuid': u'90ab08d5-6471-4f04-84f0-3e807ce6336d'}

Events

portal_events.py
Example utility to test the portal router event calls.
######################################################################
#
# Copyright 2012 Zenoss, Inc.  All Rights Reserved.
#
######################################################################
 
 
__doc__ = """
Example utility to test the portal router event calls.
"""
 
from pprint import pprint
 
import Globals
 
from ZenPacks.zenoss.PortalIntegration.RouterCaller import RouterCaller
 
 
if __name__=="__main__":
    rc = RouterCaller()
    rc.setup()
    data={
          'startTime':'March 4, 2012 02:00:00',
          'specs':[
              {'id':{'uid': '/zport/dmd/Devices/Server/Linux/devices/localhost'},
               'idScheme':'uid'}
          ]
    }
    result = rc.request('PortalRouter', 'fetch_router', 'fetchEvents', data=[data])
    pprint(result)

Sample successful output:

{u'action': u'PortalRouter',
 u'method': u'fetchEvents',
 u'result': {u'results': [{u'events': [
    {u'actor': {u'element_identifier': u'localhost.localdomain',
                       u'element_sub_identifier': u'lo',
                       u'element_sub_title': u'lo',
                       u'element_sub_type_id': 2,
                       u'element_sub_uuid': u'02d6041e-9c87-4964-8d50-005cc6c8fc76',
                       u'element_title': u'localhost.localdomain',
                       u'element_type_id': 1,
                       u'element_uuid': u'5dae218d-a87f-4ab3-bbe8-5bd529e49eed'},
            u'agent': u'zenperfsnmp',
            u'created_time': 1334680589542,
            u'details': [{u'name': u'max',
                          u'value': [u'6250.0']},
                         {u'name': u'current',
                          u'value': [u'8848.87908497']},
                         {u'name': u'how',
                          u'value': [u'exceeded']},
                         {u'name': u'manager',
                          u'value': [u'vm.localdomain']},
                         {u'name': u'zenoss.device.ip_address',
                          u'value': [u'127.0.0.1']},
                         {u'name': u'zenoss.device.production_state',
                          u'value': [u'1000']},
                         {u'name': u'zenoss.device.priority',
                          u'value': [u'3']},
                         {u'name': u'zenoss.device.device_class',
                          u'value': [u'/Server/Linux']}],
            u'event_class': u'/Perf/Interface',
            u'event_key': u'ifHCInOctets_ifHCInOctets|high utilization',
            u'message': u'threshold of high utilization exceeded: current value 8848.879085',
            u'monitor': u'localhost',
            u'severity': 3,
            u'summary': u'threshold of high utilization exceeded: current value 8848.879085'}],
   u'input': {u'id': {u'uid': u'/zport/dmd/Devices/Server/Linux/devices/localhost.localdomain/os/interfaces/lo'},
              u'idScheme': u'uid'},
                           u'success': True,
                           u'uuid': u'9c25fd69-5ee6-4889-bfef-2792026e7c51'}],
             u'success': True},
     u'tid': 1,
     u'type': u'rpc',
     u'uuid': u'7b163a7e-e878-4a4e-a931-97df5b69af71'}
portal_fetch_events
#!/bin/bash
 
#
# cURL example to grab data
# 
USERNAME="admin"
PASS="zenoss"
 
SERVER="127.0.0.1"
PORT="8080"
 
data='{"startTime":"March 4, 2012 02:00:00","uid":"/zport/dmd/Devices/Service/Linux/devices/localhost","specs":{}}'
 
curl -u "$USERNAME:$PASS" -X POST -H "Content-Type: application/json" -d '{"action":"PortalRouter","method":"fetchEvents","data":['${data}'], "tid":1}' "http://$SERVER:$PORT/zport/dmd/fetch_router"
 
echo

Thresholds

portal_thresholds.py
Example utility to test the portal router threshold calls.
######################################################################
#
# Copyright 2012 Zenoss, Inc.  All Rights Reserved.
#
######################################################################
 
 
__doc__ = """
Example utility to test the portal router threshold calls.
"""
 
from pprint import pprint
 
import Globals
 
from ZenPacks.zenoss.PortalIntegration.RouterCaller import RouterCaller
 
 
if __name__=="__main__":
    rc = RouterCaller()
    rc.setup()
    data={
          'startTime':'April 17, 2012 02:00:00',
          'specs':[
              {'id':{'uid': '/zport/dmd/Devices/Server/Linux/devices/localhost.localdomain/os/interfaces/lo'},
               'metricIds': 'ifHCInOctets',
               'idScheme':'uid'}
          ]
    }
    result = rc.request('PortalRouter', 'fetch_router', 'fetchThresholds', data=[data])
    pprint(result)

Sample output:

{u'action': u'PortalRouter',
 u'method': u'fetchThresholds',
 u'result': {u'msg': [{u'events': [{u'actor': {u'element_identifier': u'localhost.localdomain',
                                               u'element_sub_identifier': u'lo',
                                               u'element_sub_title': u'lo',
                                               u'element_sub_type_id': 2,
                                               u'element_sub_uuid': u'02d6041e-9c87-4964-8d50-005cc6c8fc76',
                                               u'element_title': u'localhost.localdomain',
                                               u'element_type_id': 1,
                                               u'element_uuid': u'5dae218d-a87f-4ab3-bbe8-5bd529e49eed'},
                                    u'agent': u'zenperfsnmp',
                                    u'created_time': 1334680589542,
                                    u'details': [{u'name': u'max',
                                                  u'value': [u'6250.0']},
                                                 {u'name': u'current',
                                                  u'value': [u'8848.87908497']},
                                                 {u'name': u'how',
                                                  u'value': [u'exceeded']},
                                                 {u'name': u'manager',
                                                  u'value': [u'vm.localdomain']},
                                                 {u'name': u'zenoss.device.ip_address',
                                                  u'value': [u'127.0.0.1']},
                                                 {u'name': u'zenoss.device.production_state',
                                                  u'value': [u'1000']},
                                                 {u'name': u'zenoss.device.priority',
                                                  u'value': [u'3']},
                                                 {u'name': u'zenoss.device.device_class',
                                                  u'value': [u'/Server/Linux']}],
                                    u'event_class': u'/Perf/Interface',
                                    u'event_key': u'ifHCInOctets_ifHCInOctets|high utilization',
                                    u'message': u'threshold of high utilization exceeded: current value 8848.879085',
                                    u'monitor': u'localhost',
                                    u'severity': 3,
                                    u'summary': u'threshold of high utilization exceeded: current value 8848.879085'}],
                       u'input': {u'id': {u'uid': u'/zport/dmd/Devices/Server/Linux/devices/localhost.localdomain/os/interfaces/lo'},
                                  u'idScheme': u'uid',
                                  u'metricIds': u'ifHCInOctets'},
                       u'success': True,
                       u'uuid': u'02d6041e-9c87-4964-8d50-005cc6c8fc76'}],
             u'success': True},
 u'tid': 1,
 u'type': u'rpc',
 u'uuid': u'da27c8b1-d681-4ef6-ab36-676eacecb1b6'}

Utilities

portal_list_metricIds.py
Example utility to test the identification router.
######################################################################
#
# Copyright 2012 Zenoss, Inc.  All Rights Reserved.
#
######################################################################
 
 
__doc__ = """portal_id
Example utility to test the identification router.
"""
 
from pprint import pprint
 
import Globals
 
from ZenPacks.zenoss.PortalIntegration.RouterCaller import RouterCaller
 
 
if __name__=="__main__":
    rc = RouterCaller()
    rc.setup()
    data={
              'id':{'uid': '/zport/dmd/Devices/Server/Linux/devices/localhost.localdomain'},
               'idScheme':'uid'
    }
    result = rc.request('PortalRouter', 'fetch_router', 'listMetricIds', data=[data])
    pprint(result)

Sample output:

{u'action': u'PortalRouter',
 u'method': u'listMetricIds',
 u'result': {u'metricIds': [u'laLoadInt1',
                            u'laLoadInt15',
                            u'laLoadInt5',
                            u'memAvailReal',
                            u'memAvailSwap',
                            u'memBuffer',
                            u'memCached',
                            u'ssCpuIdle',
                            u'ssCpuRawWait',
                            u'ssCpuSystem',
                            u'ssCpuUser',
                            u'ssIORawReceived',
                            u'ssIORawSent',
                            u'sysUpTime'],
             u'success': True,
             u'uuid': u'5dae218d-a87f-4ab3-bbe8-5bd529e49eed'},
 u'tid': 1,
 u'type': u'rpc',
 u'uuid': u'a6013322-b648-41ad-9d4d-1a1ca9d06e31'}

Installation

Normal Installation (packaged egg)

  1. Download the appropriate egg file for the version of Zenoss you are running.
  2. Ensure you are logged in as the zenoss user:
    $ sudo su - zenoss
  3. Install the ZenPack:
    $ zenpack --install ZenPacks.zenoss.PortalIntegration-*.egg
  4. Restart these services:
    $ zenoss restart

Commercial

This ZenPack is developed and supported by Zenoss Inc. Commercial ZenPacks are available to Zenoss commercial customers only. Contact Zenoss to request more information regarding this or any other ZenPacks. Click here to view all available Zenoss Commercial ZenPacks.