177 lines
7.2 KiB
ReStructuredText
177 lines
7.2 KiB
ReStructuredText
# Overview
|
|
|
|
`broadview-lib` is a library that provides an interface to Broadcom's
|
|
BroadView instrumentation functionality.
|
|
|
|
## What is BroadView?
|
|
|
|
BroadView is an open source software suite that enables advanced analytics in
|
|
next-generation networks. Troubleshooting network problems and ensuring
|
|
application SLAs are very complex tasks. In cloud networks, overlay
|
|
technologies reduce visibility into packet flows, thereby making it even more
|
|
difficult to analyze issues and ensure SLAs. OpenStack projects such as
|
|
Monasca provide monitoring-as-a-service to deliver usage metrics from
|
|
applications and tenant networks; however, underlay monitoring is not
|
|
supported. Ensuring application SLAs requires overlay mapping to the underlay,
|
|
and optimal performance of underlay infrastructure is essential.
|
|
|
|
BroadView-based solutions enable programmable access to underlay monitoring,
|
|
facilitating applications to gather advanced analytics in a highly scalable
|
|
manner.
|
|
|
|
Buffer Statistics Tracking (BST) is one of the most important features for
|
|
enabling rich congestion analytics. Network Traffic is bursty by nature and
|
|
microbursts occur when there is transient congestion. Microbursts are difficult
|
|
to detect using traditional port drop counts. Broadcom silicon provides the
|
|
ability to monitor MMU buffer utilization counts as part of the BST feature.
|
|
It provides network administrators and applications improved telemetry on
|
|
the usage of various ingress and egress buffers, without disrupting regular
|
|
packet forwarding operations. There are thousands of counters available across
|
|
various ports, port groups, and service pools that can be utilized by the
|
|
applications for instantaneous monitoring in a scalable way. BST tracks
|
|
ingress-, egress-, and device-based use-counts for both unicast and multicast
|
|
flows. The actual use-counts vary depending on the chip set.
|
|
|
|
More information on BroadView, BST, and what they provide can be found at:
|
|
|
|
Code and documentation: https://github.com/Broadcom-Switch/BroadView-Instrumentation
|
|
Product information: https://www.broadcom.com/products/ethernet-communication-and-switching/switching/broadview
|
|
|
|
## BroadView Agent and broadview-lib
|
|
|
|
A BroadView agent is software running on platforms that support BroadView. It
|
|
exposes a JSON-RPC, REST-like API for configuring the agent to report statistics
|
|
such a BST. It also report statistics to agents or collectors that are designed
|
|
to receive these reports. These reports are also transmitted using JSON-RPC.
|
|
All connections to and from the agent are based on HTTP 1.1.
|
|
|
|
broadview-lib is designed to provide the underlying infrastructure that is
|
|
needed for the development of Python applications that interact with a
|
|
BroadView agent. Using broadview-lib, a Python application can configure a
|
|
BroadView agent and make calls on the agent to perform various tasks.
|
|
broadview-lib also provides classes that can parse notifications and data sent
|
|
to an application by a BroadView agent. broadview-lib can be thought of as
|
|
presenting an object-model above the JSON-RPC protocol of the BroadView agent.
|
|
|
|
As such, broadview-lib forms the basis of other contributions that integrate
|
|
BroadView functionality into OpenStack, and represents an OpenStack-neutral
|
|
view of BroadView's API. The library can be used by other projects outside of
|
|
OpenStack, if desired.
|
|
|
|
broadview-lib consists of two components. One is a set of classes that can
|
|
be used to configure BroadView. The other is an API that parses content
|
|
sent by BroadView agents and presents it as Python objects.
|
|
|
|
broadview-lib is, like BroadView itself, designed to be extensible. In this
|
|
release, the BroadView BST component is supported. Future releases will add
|
|
support for additional BroadView components as they become available.
|
|
|
|
# Tools
|
|
|
|
broadview-lib includes bv-bstctl.py, which is a command line application that
|
|
can be used to configure BroadView BST. It also provides an example usage of
|
|
both the configuration and BST parsing APIs in broadview-lib. For usage
|
|
information, please type:
|
|
|
|
python bv-bstcfg.py help
|
|
|
|
|
|
bv-bstctl.py writes its output to stdout in JSON format.
|
|
|
|
The file examples.sh in the tools directory contains usage example for the
|
|
bv-bstcfg application and can be used to exercise bv-bsctl.
|
|
|
|
# Classes
|
|
|
|
The following describes the major classes in the library.
|
|
|
|
## BST Configuration and Data Gathering
|
|
|
|
The bst.py file in config contains various configuration and data gathering
|
|
classes.
|
|
|
|
The following briefly summarizes these classes. For example usage, see the
|
|
unit test code in bst.py, or the bv-bstctl.py application.
|
|
|
|
### ConfigureBSTFeature
|
|
|
|
This class can be used to provide general configuration of the BroadView BST
|
|
component.
|
|
|
|
### ConfigureBSTTracking
|
|
|
|
This class is used to enable or disable the tracking of various BST statistics.
|
|
|
|
### ConfigureBSTThresholds
|
|
|
|
This base class is inherited by the several subclasses, each which allow for
|
|
the configuration of thresholds for the various statistics (realms) that
|
|
are supported by BST. The following is a list of these subclasses, one for
|
|
each supported BST realm:
|
|
|
|
device - ConfigureDeviceThreshold
|
|
egress-cpu-queue - ConfigureEgressCpuQueueThreshold
|
|
egress-rqe-queue - ConfigureEgressRqeQueueThreshold
|
|
egress-port-service-pool - ConfigureEgressPortServicePoolThreshold
|
|
egress-service-pool - ConfigureEgressServicePoolThreshold
|
|
egress-uc-queue - ConfigureEgressUcQueueThreshold
|
|
egress-uc-queue-group - ConfigureEgressUcQueueGroupThreshold
|
|
egress-mc-queue - ConfigureEgressMcQueueThreshold
|
|
ingress-port-priority-group - ConfigureIngressPortPriorityGroupThreshold
|
|
ingress-port-service-pool - ConfigureIngressPortServicePoolThreshold
|
|
ingress-service-pool - ConfigureIngressServicePoolThreshold
|
|
|
|
### ClearBSTStatistics
|
|
|
|
This class supports the resetting of all BST statistics in the agent.
|
|
|
|
### ClearBSTThresholds
|
|
|
|
This class supports the resetting of all BST thresholds in the agent.
|
|
|
|
### GetBSTFeature
|
|
|
|
This class reports the various settings of the BroadView BST component.
|
|
|
|
### GetBSTTracking
|
|
|
|
This class reports the tracking settings for the BroadView BST component.
|
|
The tracking status of each supported realm is reported.
|
|
|
|
### GetBSTThresholds
|
|
|
|
This class reports the threshold settings for the various BST realms.
|
|
|
|
### GetBSTReport
|
|
|
|
This class reports the current buffer statistics for the specified realms.
|
|
|
|
## BST Object
|
|
|
|
The class BSTParser (found in bst/bst_parser.py) accepts the JSON payload
|
|
that is sent by a BroadView agent for BST notifications and responses that
|
|
contain BST threshold reports.
|
|
|
|
## Unit tests
|
|
|
|
To ensure that broadview-lib is decoupled from any (and all) OpenStack
|
|
dependencies, unit tests are implemented by each of the individual Python
|
|
modules using the Python unittest framework.
|
|
|
|
# License
|
|
|
|
(C) Copyright Broadcom Corporation 2016
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
|
|
You may obtain a copy of the License at
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|