Extensible Telemetry Guide
Extensible Telemetry Overview
Install Apstra device drivers and telemetry collectors to collect additional telemetry that can be used in analytics probes. The device drivers enable Apstra to connect to a NOS and collect telemetry. Apstra ships with drivers for EOS, NX-OS, Ubuntu, and CentOS. To add a driver for an operating system not listed here, contact Juniper Support.
Telemetry collectors are Python modules that help collect extended telemetry. The following sections describe the pipeline for creating telemetry collectors and extending Apstra with new collectors. You need familiarity with Python to be able to develop collectors.
Set Up Development Environment
To get access to telemetry collectors (which are housed in the aos_developer_sdk repository) contact Juniper Support. Contribute any new collectors that you develop to the repository.
To keep your system environment intact, we recommend that you use a virtual environment to isolate the required Python packages (for development and testing). You can download the base development environment, aos_developer_sdk.run, from https://support.juniper.net/support/downloads/?p=apstra/. To load the environment, execute:
aos_developer_sdk$ bash aos_development_sdk.run
4d8bbfb90ba8: Loading layer [==================================================>] 217.6kB/217.6kB
7d54ea05a373: Loading layer [==================================================>] 4.096kB/4.096kB
e2e40f457231: Loading layer [==================================================>] 1.771MB/1.771MB
Loaded image: aos-developer-sdk:2.3.1-129
================================================================================
Loaded AOS Developer SDK Environment Container Image
aos-developer-sdk:2.3.1-129.
Container can be run by
docker run -it \
-v <path to aos developer_sdk cloned repo>:/aos_developer_sdk \
--name <container name> \
aos-developer-sdk:2.3.1-129
================================================================================This command loads the aos_developer_sdk Docker image. After the image load is complete, the command to start the environment is printed. Start the container environment as specified by the command. To install the dependencies, execute:
root@f2ece48bb2f1:/# cd /aos_developer_sdk/ root@f2ece48bb2f1:/aos_developer_sdk# make setup_env ...
The environment is now set up for developing and testing the collectors. Apstra SDK packages, such as device drivers and REST client, are also installed in the environment.
Develop Collector
To develop a telemetry collector, specify the following in order.
Write Collector
Collector is a class that must derive from aos.sdk.system_agent.base_telemetry_collector.BaseTelemetryCollector. Override the collect method of the collector with the logic to:
Collect Data from Device
The device driver instance inside the collector provides methods to execute
commands against the devices. For example, most Apstra device drivers provide
methods get_json and get_text to execute
commands and return the output.
The device drivers for aos_developer_sdk environment are preinstalled. You can explore the methods available to collect data. For example:
>>> from aos.sdk.driver.eos import Device
>>> device = Device('172.20.180.10', 'admin', 'admin')
>>> device.open()
>>> pprint.pprint(device.get_json('show version'))
{u'architecture': u'i386',
u'bootupTimestamp': 1548302664.0,
u'hardwareRevision': u'',
u'internalBuildId': u'68f3ae78-65cb-4ed3-8675-0ff2219bf118',
u'internalVersion': u'4.20.10M-10040268.42010M',
u'isIntlVersion': False,
u'memFree': 3003648,
u'memTotal': 4011060,
u'modelName': u'vEOS',
u'serialNumber': u'',
u'systemMacAddress': u'52:54:00:ce:87:37',
u'uptime': 62620.55,
u'version': u'4.20.10M'}
>>> dir(device)
['AOS_VERSION_FILE', '__class__', '__delattr__', '__dict__', '__doc__',
'__format__', '__getattribute__', '__hash__', '__init__', '__module__',
'__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__',
'__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'close',
'device_info', 'driver', 'execute', 'get_aos_server_ip',
'get_aos_version_related_info', 'get_device_aos_version',
'get_device_aos_version_number', 'get_device_info', 'get_json',
'get_text', 'ip_address', 'onbox', 'open', 'open_options', 'password',
'probe', 'set_device_info', 'upload_file', 'username']Parse Data
The collected data needs to be parsed and re-formatted per the Apstra framework and the service schema identified above. Collectors with generic storage schema follow the following structure:
{
"items": [
{
"identity": <key goes here>,
"value": <value goes here>,
},
{
"identity": <key goes here>,
"value": <value goes here>,
},
...
]
}Collectors with IBA-based schema follow the following structure:
[
{
"key": <key goes here>,
"value": <value goes here>,
},
{
"key": <key goes here>,
"value": <value goes here>,
},
...
]
In the structures above, the data posted has multiple items. Each item has a key and a value. For example, to post interface specific information, there would be an identity/key-value pair for each interface you want to post to the framework.
In the case when you want to use a third party package to parse data obtained from a device, list the Python package and version in the path.
<aos_developer_sdk>/aosstdcollectors/requirements_<NOS>.txt.
The packages installed by the dependency do not conflict with packages that
Apstra software uses. The Apstra-installed packages are available at
/etc/aos/python_dependency.txt in the development
environment.
Post Data to Framework
When data is collected and parsed as per the required schema, post the data to
the framework. You can use the post_data method available in
the collector. It accepts one argument, and that is the data that should be
posted to the framework.
The folder aos_developer_sdk/aosstdcollectors/aosstdcollectors
in the repository contains folders for each NOS. Add your collector to the
folder that matches the NOS. Cumulus is no longer supported as of Apstra version
4.1.0, although this example remains for illustrative purposes. For example, to
write a collector for Cumulus, add the collector to
aos_developer_sdk/aosstdcollectors/aosstdcollectors/cumulus,
and name the file after the service name. For example, if the service name is
interface_in_out_bytes, then name the file
interface_in_out_bytes.py.
In addition to defining the collector class, define the function
collector_plugin in the collector file. The function takes
one argument and returns the collector class that is implemented.
For example, a generic storage schema based collector looks like:
"""
Service Name: interface_in_out_bytes
Schema:
Key: String, represents interface name.
Value: Json String with two possible keys:
rx: integer value, represents received bytes.
tx: integer value, represents transmitted bytes.
DOS: eos
Data collected using command: 'show interfaces'
Type of Collector: BaseTelemetryCollector
Storage Schema Path: aos.sdk.telemetry.schemas.generic
Application Schema: {
'type': 'object',
'properties': {
'identity': {
'type': 'string',
},
'value': {
'type': 'object',
'properties': {
'rx': {
'type': 'number',
},
'tx': {
'type': 'number',
}
},
'required': ['rx', 'tx'],
}
}
}
"""
import json
from aos.sdk.system_agent.base_telemetry_collector import BaseTelemetryCollector
# Inheriting from BaseTelemetryCollector
class InterfaceRxTxCollector(BaseTelemetryCollector):
# Overriding collect method
def collect(self):
# Obtaining the command output using the device instance.
collected_data = self.device.get_json('show interfaces')
# Data is in the format
# "interfaces": {
# "<interface_name>": {
# ....
# "interfaceCounters": {
# ....
# "inOctets": int
# "outOctets": int
# ....
# }
# }
# ...
# }
# Parse the data as per the schema and structure required.
parsed_data = json.dumps({
'items': [
{
'identity': intf_name,
'value': json.dumps({
'rx': intf_stats['interfaceCounters'].get('inOctets'),
'tx': intf_stats['interfaceCounters'].get('outOctets'),
})
} for intf_name, intf_stats in collected_data['interfaces'].iteritems()
if 'interfaceCounters' in intf_stats
]
})
# Post the data to the framework
self.post_data(parsed_data)
# Define collector_plugin class to return the Collector
def collector_plugin(_device):
return InterfaceRxTxCollectorAn IBA storage schema based collector looks like:
"""
Service Name: iba_bgp
Schema:
Key: JSON String, specifies local IP and peer IP.
Value: String. ‘1’ if state is established ‘2’ otherwise
DOS: eos
Data collected using command: 'show ip bgp summary vrf all'
Storage Schema Path: aos.sdk.telemetry.schemas.iba_string_data
Application Schema: {
'type': 'object',
'properties': {
key: {
'type': 'object',
'properties': {
'local_ip': {
'type': 'string',
},
'peer_ip': {
'type': 'string',
}
},
'required': ['local_ip', 'peer_ip'],
},
'value': {
'type': 'string',
}
}
}
"""
from aos.sdk.system_agent.base_telemetry_collector import IBATelemetryCollector
def parse_text_output(collected):
result = [
{'key': {'local_ip': str(vrf_info['routerId']), 'peer_ip': str(peer_ip)},
'value': str(
1 if session_info['peerState'] == 'Established' else 2)}
for vrf_info in collected['vrfs'].itervalues()
for peer_ip, session_info in vrf_info['peers'].iteritems()]
return result
# Inheriting from BaseTelemetryCollector
class IbaBgpCollector(BaseTelemetryCollector):
# Overriding collect method
def collect(self):
# Obtaining the command output using the device instance.
collected_data = self.device.get_json('show ip bgp summary vrf all')
# Parse the data as per the schema and structure required and
# post to framework.
self.post_data(parse_text_output(collected_data))
# Define collector_plugin class to return the Collector
def collector_plugin(device):
return IbaBgpCollectorUnit Test Collector
The folder aos_developer_sdk/aosstdcollectors/test in the repository
contains folders based on the NOS. Add your test to the folder that matches the NOS.
For example, a test to a collector for Cumulus is added to
aos_developer_sdk/aosstdcollectors/test/cumulus. We recommend
that you name the unit test with the prefix test_.
The existing infrastructure implements a Pytest fixture
collector_factory that is used to mock the device driver
command response. The general flow for test development is as follows.
- Use the collector factory to get a collector instance and mocked Apstra framework. The collector factory takes the collector class that you have written as input.
- Mock the device response.
- Invoke collect method.
- Validate the data posted to the mocked Apstra framework.
For example, a test looks like:
import json
from aosstdcollectors.eos.interface_in_out_bytes import InterfaceRxTxCollector
# Test method with prefix 'test_'
def test_sanity(collector_factory):
# Using collector factory to retrieve the collector instance and mocked
# Apstra framework.
collector, mock_framework = collector_factory(InterfaceRxTxCollector)
command_response = {
'interfaces': {
'Ethernet1': {
'interfaceCounters': {
'inOctets': 10,
'outOctets': 20,
}
},
'Ethernet2': {
'interfaceCounters': {
'inOctets': 30,
'outOctets': 40,
}
}
}
}
# Set the device get_json method to retrieve the command response.
collector.device.get_json.side_effect = lambda _: command_response
# Invoke the collect method
collector.collect()
expected_data = [
{
'identity': 'Ethernet1',
'value': json.dumps({
'rx': 10,
'tx': 20,
}),
},
{
'identity': 'Ethernet2',
'value': json.dumps({
'rx': 30,
'tx': 40,
})
}
]
# validate the data posted by the collector
data_posted_by_collector = json.loads(mock_framework.post_data.call_args[0][0])
assert sorted(expected_data) == sorted(data_posted_by_collector["items"])To run the test, execute:
root@1df9bf89aeaf:/aos_developer_sdk# make test root@1df9bf89aeaf:/aos_developer_sdk# make test
This command executes all the tests in the repository.
Package Collector
All the collectors are packaged based on the NOS. To generate all packages, execute
make at aos_develop_sdk. You can find the build packages at
aos_developer_sdk/dist. The packages build can be broadly
classified as:
| Package | Description |
|---|---|
| Built-In Collector Packages | These packages have the prefix aosstdcollectors_builtin_.
To collect telemetry from a device per the reference design, Apstra
requires services as listed in the <deviceblah>
section. Built-In collector packages contain collectors for these
services. The packages are generated on a per NOS basis. |
| Custom Collector Packages |
These package have the prefix aosstdcollectors_custom_ in their names. The packages are generated on a per NOS basis. The package named aosstdcollectors_custom_<NOS>-0.1.0-py2-none-any.whl contains the developed collector. |
| Apstra SDK Device Driver Packages |
These packages have a prefix apstra_devicedriver_. These packages are generated on a per NOS basis. Packages are generated for NOS that are not available by default in Apstra. |
Upload Packages
If the built-in collector packages and the Apstra SDK Device Driver for your Device Operating System (NOS) were not provided with the Apstra software, you must upload them to the Apstra server.
If you are using an offbox solution and your NOS is not EOS, you must upload the built-in collector package.
Upload the package containing your collector(s) and assign them to a Device System Agent or System Agent Profile.
Use Telemetry Collector
- Set up Telemetry Service Registry
- Start Collector
- Delete Collector
- Get Collected Data
- List Running Collector Services
Set up Telemetry Service Registry
The registry maps the service to its application schema and the storage schema
path. You can manage the telemetry service registry with the REST endpoint
/api/telemetry-service-registry. You can't enable the
collector for a service without adding a registry entry for the particular
service. The registry entry for a service cannot be modified while the service
is in use.
When executing make, all application schemas are packaged
together to a tar file (json_schemas.tgz) in the dist folder. With
apstra-cli, you have the option of importing all the schemas in the .tgz
file.
Start Collector
To start a service, use the POST API
/api/systems/<system_id>/services with the following
three arguments:
| Arguments | |
|---|---|
| Input_data | The data provided as input to the collector. Defaults to None. |
| Interval | Interval at which to run the service. Defaults to 120 seconds. |
| Name | Name of the service. |
You can also manage collectors via the apstra-cli utility.
Delete Collector
To delete a service, use the DELETE API
/api/systems/<system_id>/services/<service_name>.
Get Collected Data
To retrieve collected data, use the GET API
/api/systems/<system_id>/services/<service_name>/data.
Only the data collected in the last iteration is saved. Data does not persist
over Apstra restart.
List Running Collector Services
To retrieve the list of services enabled on a device, use the GET API
/api/systems/<system_id>/services.