10.2. SteelScript SCC Tutorial¶

This tutorial presents a step-by-step description of how to use SteelScript SCC package to develop scripts to retrieve data from target SCC device.

10.2.1. Background¶

SCC provides centralized reporting and analysis of the states of other connected riverbed appliances (i.e., SteelHead). SteelScript for SCC makes this wealth of data easily accessible via Python.

10.2.2. SCC Objects¶

Interacting with a SCC leverages two key classes:

SCC - provides the primary interface to the appliance, handling initialization, setup and communication via REST API calls.
BaseStatsReport - leverages the SCC object to pull data and create new reports.

In most cases you will not use BaseStatsReport directly – your scripts will use a more helpful object tailored to the desired report, such as a BWTimeSeriesStatsReport or a ThroughputStatsReport. We will cover those shortly.

10.2.3. Startup¶

As with any Python code, the first step is to import the modules involved. The SteelScript code for working with SCC appliances resides in a module steelscript.scc.core. The main class in this module is SCC. This object represents a connection to an SCC appliance. Let’s see how easy it is to create an SCC object.

>>> from steelscript.scc.core import SCC
>>> from steelscript.common.service import OAuth
>>> scc = SCC(host='$hostname', auth=OAuth('$access_code'))

Replace the first argument $hostname with the hostname or IP address of the SCC appliance. The second argument is an access code, which is required for OAuth 2.0 authentication. The access code is usually obtained on the web UI of the SCC appliance (See the “Enabling REST API Access” section in your SCC documentation for more information).

10.2.4. Generating Reports¶

After an SCC object has been instantiated, now it is time to use it to retrieve some data from the SCC appliance. Good news is that SteelScript-SCC comes with a comprehensive coverage of all resources underneath the cmc.stats service. One just needs to browse through classes defined in the steelscript.scc.core module to use the report class matching current needs. For example, in order to get optimized bandwidth at different times of all devices associated with the SCC appliance, BWTimeSeriesStatsReport is the one to use.

>>> from steelscript.scc.core import BWTimeSeriesStatsReport
>>> import pprint
>>> report = BWTimeSeriesStatsReport(scc)
>>> report.run(timefilter="last 1 hour", traffic_type='optimized')

Note that timefilter specifies the time range of the query and traffic_type determines the type of traffic to query.

Now that the report has been run, we can fetch the data by accessing the data attribute:

>>> pprint.pprint(report.data)
[{u'data': [7308580.0, 16571400.0, 13216600.0, 68872900.0],
  u'timestamp': 1440780000},
 {u'data': [6002410.0, 23606000.0, 10935900.0, 52749800.0],
  u'timestamp': 1440780300},
 {u'data': [4056250.0, 16865900.0, 6394300.0, 37789200.0],
  u'timestamp': 1440780600},
 {u'data': [5850490.0, 44258800.0, 11690500.0, 104962000.0],
  u'timestamp': 1440780900},
 {u'data': [7468290.0, 24188900.0, 12829400.0, 84234000.0],
  u'timestamp': 1440781200},
 {u'data': [13041800.0, 34822600.0, 17672900.0, 77343300.0],
  u'timestamp': 1440781500},
 {u'data': [182396000.0, 206378000.0, 195764000.0, 261148000.0],
  u'timestamp': 1440781800},
 {u'data': [178387000.0, 194976000.0, 199298000.0, 235883000.0],
  u'timestamp': 1440782100},
 {u'data': [177016000.0, 203324000.0, 190545000.0, 261889000.0],
  u'timestamp': 1440782400},
 {u'data': [187747000.0, 416022000.0, 197363000.0, 450196000.0],
  u'timestamp': 1440782700},
 {u'data': [151403000.0, 334982000.0, 216453000.0, 422683000.0],
  u'timestamp': 1440783000},
 {u'data': [159875000.0, 409043000.0, 190787000.0, 451655000.0],
  u'timestamp': 1440783300}]

10.2.5. Extending the Example¶

As a last item to help get started with your own scripts, we will extend our example with command-line options.

Below is an example script with ability to accept command-line options and present data in a table-like format.

#!/usr/bin/env python

import pprint

from steelscript.scc.core.app import SCCApp
from steelscript.scc.core import BWTimeSeriesStatsReport


class BWTimeSeriesStatsReportApp(SCCApp):

    traffic_types = ['optimized', 'passthrough']

    def add_options(self, parser):
        super(BWTimeSeriesStatsReportApp, self).add_options(parser)

        parser.add_option(
            '--timefilter', dest='timefilter', default='last 1 hour',
            help='Time range to analyze (defaults to "last 1 hour") '
            'other valid formats are: "4/21/13 4:00 to 4/21/13 5:00" '
            'or "16:00:00 to 21:00:04.546"')

        parser.add_option(
            '--traffic_type', dest='traffic_type', default='optimized',
            help='Type of traffic to query, either optimized or passthrough')

        parser.add_option(
            '--devices', dest='devices', default=None,
            help='An array of devices being queried on. None implies all '
            'devices. If multiple devices are queried on, the data points '
            'are the sum across all the devices.')

        parser.add_option('--port', dest='port', default=None)

    def main(self):
        report = BWTimeSeriesStatsReport(self.scc)
        report.run(traffic_type=self.options.traffic_type,
                   timefilter=self.options.timefilter,
                   devices=self.options.devices,
                   port=self.options.port)
        pprint.pprint(report.data)

if __name__ == '__main__':
    BWTimeSeriesStatsReportApp().run()

Copy the above code into a new file, and now you can run the file to display the data.

> python myreport.py $hostname $access_code --devices $serial_numbers --traffic_type 'optimized' --timefilter 'last 1 hour'
 [{u'data': [7308580.0, 16571400.0, 13216600.0, 68872900.0],
   u'timestamp': 1440780000},
  {u'data': [6002410.0, 23606000.0, 10935900.0, 52749800.0],
   u'timestamp': 1440780300},
  {u'data': [4056250.0, 16865900.0, 6394300.0, 37789200.0],
   u'timestamp': 1440780600},
  {u'data': [5850490.0, 44258800.0, 11690500.0, 104962000.0],
   u'timestamp': 1440780900},
  {u'data': [7468290.0, 24188900.0, 12829400.0, 84234000.0],
   u'timestamp': 1440781200},
  {u'data': [13041800.0, 34822600.0, 17672900.0, 77343300.0],
   u'timestamp': 1440781500},
  {u'data': [182396000.0, 206378000.0, 195764000.0, 261148000.0],
   u'timestamp': 1440781800},
  {u'data': [178387000.0, 194976000.0, 199298000.0, 235883000.0],
   u'timestamp': 1440782100},
  {u'data': [177016000.0, 203324000.0, 190545000.0, 261889000.0],
   u'timestamp': 1440782400},
  {u'data': [187747000.0, 416022000.0, 197363000.0, 450196000.0],
   u'timestamp': 1440782700},
  {u'data': [151403000.0, 334982000.0, 216453000.0, 422683000.0],
   u'timestamp': 1440783000},
  {u'data': [159875000.0, 409043000.0, 190787000.0, 451655000.0],
   u'timestamp': 1440783300}]

Now let us walk through the above script in detail.

First we need to import some modules.

#!/usr/bin/env python

import pprint

from steelscript.scc.core.app import SCCApp
from steelscript.scc.core import BWTimeSeriesStatsReport

The first line is called a shebang, it tells the system that the script should be executed using the program after ‘#!’. The SCCApp is imported for ease of writing scripts to generate reports for SCC. The BWTimeSeriesStatsReport is imported to facilitate reporting data retrieved at resource bw_timeseries, which belongs to the cmc.stats service on a SCC device.

class BWTimeSeriesStatsReportApp(SCCApp):

    def add_options(self, parser):
        super(BWTimeSeriesStatsReportApp, self).add_options(parser)

        parser.add_option(
            '--timefilter', dest='timefilter', default='last 1 hour',
            help='Time range to analyze (defaults to "last 1 hour") '
            'other valid formats are: "4/21/13 4:00 to 4/21/13 5:00" '
            'or "16:00:00 to 21:00:04.546"')

        parser.add_option(
            '--traffic_type', dest='traffic_type', default='optimized',
            help='Type of traffic to query, either optimized or passthrough')

        parser.add_option(
            '--devices', dest='devices', default=None,
            help='An array of devices being queried on. None implies all '
            'devices. If multiple devices are queried on, the data points '
            'are the sum across all the devices.')

        parser.add_option('--port', dest='port', default=None)

This section begins with definition of the BWTimeSeriesStatsReportApp class, which inherits from the class SCCApp. The inheritence saves work of adding hostname option as well as access code option, both of which are required for fetching data from SCC device.

The add_options method introduces options to the report, including time filter, traffic type, devices and port. The help text for each option can be seen using the ‘–help’ option.

    def main(self):
        report = BWTimeSeriesStatsReport(self.scc)
        report.run(traffic_type=self.options.traffic_type,
                   timefilter=self.options.timefilter,
                   devices=self.options.devices,
                   port=self.options.port)
        pprint.pprint(report.data)

if __name__ == '__main__':
    BWTimeSeriesStatsReportApp().run()

This is the main part of the script. The run method of the BWTimeSeriesStatsReport class will execute its main method. In the main method, self.scc represents the SCC object, which has been created by SCCApp class. report.run will use all the input options and retrieve data via the SCC object.