Guía de telemetría extensible
Descripción general de la telemetría extensible
Instale los controladores de dispositivos Apstra y los recolectores de telemetría para recopilar telemetría adicional que se pueda usar en las sondas IBA. Los controladores de dispositivo permiten que Apstra se conecte a un NOS y recopile telemetría. Apstra se envía con controladores para EOS, NX-OS, Ubuntu y CentOS. Para agregar un controlador para un sistema operativo que no se enumera aquí, póngase en contacto con el soporte de Juniper.
Los recolectores de telemetría son módulos de Python que ayudan a recopilar telemetría extendida. En las siguientes secciones se describe la canalización para crear recolectores de telemetría y extender Apstra con nuevos recolectores. Necesita estar familiarizado con Python para poder desarrollar recolectores.
Configurar un entorno de desarrollo
Para obtener acceso a los recolectores de telemetría (que se alojan en el depósito de aos_developer_sdk ), póngase en contacto con el soporte de Juniper. Aporte al repositorio cualquier recopilador nuevo que desarrolle.
Para mantener intacto el entorno del sistema, recomendamos que use un entorno virtual para aislar los paquetes de Python necesarios (para el desarrollo y las pruebas). Puede descargar el entorno de desarrollo base , aos_developer_sdk.run, desde https://support.juniper.net/support/downloads/?p=apstra/. Para cargar el entorno, ejecute lo siguiente:
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
================================================================================
Este comando carga el aos_developer_sdk imagen de Docker. Después de completar la carga de la imagen, se imprime el comando para iniciar el entorno. Inicie el entorno de contenedor según lo especificado por el comando. Para instalar las dependencias, ejecute lo siguiente:
root@f2ece48bb2f1:/# cd /aos_developer_sdk/ root@f2ece48bb2f1:/aos_developer_sdk# make setup_env ...
El entorno está configurado para desarrollar y probar los recolectores. Los paquetes del SDK de Apstra, como los controladores de dispositivo y el cliente REST, también se instalan en el entorno.
Desarrollar recolector
Para desarrollar un recopilador de telemetría, especifique lo siguiente en orden.
Recolector de escritura
Recopilador es una clase que debe derivar de aos.sdk.system_agent.base_telemetry_collector. Colelector basetelemetría. Reemplazar el método collect del recopilador con la lógica para:
Recopile datos desde el dispositivo
La instancia de controlador de dispositivo dentro del recopilador proporciona métodos para ejecutar comandos en los dispositivos. Por ejemplo, la mayoría de los controladores de dispositivos de Apstra proporcionan métodos get_json y get_text para ejecutar comandos y devolver la salida.
Los controladores de dispositivo para aos_developer_sdk entorno están preinstalados. Puede explorar los métodos disponibles para recopilar datos. Por ejemplo:
>>> 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']
Análisis de datos
Los datos recopilados deben analizarse y formatearse de acuerdo con el marco de trabajo de Apstra y el esquema de servicio identificado anteriormente. Los recolectores con esquema de almacenamiento genérico siguen la siguiente estructura:
{
"items": [
{
"identity": <key goes here>,
"value": <value goes here>,
},
{
"identity": <key goes here>,
"value": <value goes here>,
},
...
]
}
Los recolectores con esquema basado en IBA siguen la siguiente estructura:
[
{
"key": <key goes here>,
"value": <value goes here>,
},
{
"key": <key goes here>,
"value": <value goes here>,
},
...
]
En las estructuras anteriores, los datos publicados tienen varios elementos. Cada elemento tiene una clave y un valor. Por ejemplo, para publicar información específica de interfaz, habría un par identidad/clave-valor para cada interfaz que desea publicar en el marco.
En el caso de que desee usar un paquete de terceros para analizar los datos obtenidos de un dispositivo, indique el paquete y la versión de Python en la ruta de acceso.
<aos_developer_sdk>/aosstdcollectors/requirements_<NOS>.txt. Los paquetes instalados por la dependencia no entran en conflicto con los paquetes que usa el software de Apstra. Los paquetes instalados por Apstra están disponibles /etc/aos/python_dependency.txt en el entorno de desarrollo.
Enviar datos al marco de trabajo
Cuando los datos se recopilan y se analiza según el esquema necesario, publique los datos en el marco. Puede usar el post_data método disponible en el recopilador. Acepta un argumento, y ese es los datos que se deben publicar en el marco.
La carpeta aos_developer_sdk/aosstdcollectors/aosstdcollectors del repositorio contiene carpetas para cada NOS. Agregue el recopilador a la carpeta que coincida con el NOS. Cumulus ya no es compatible con Apstra versión 4.1.0, aunque este ejemplo sigue siendo ilustrativo. Por ejemplo, para escribir un recopilador para Cumulus, agregue el recopilador a , y asigne un nombre al aos_developer_sdk/aosstdcollectors/aosstdcollectors/cumulusarchivo después del nombre de servicio. Por ejemplo, si el nombre del servicio es interface_in_out_bytes, asigne un nombre al archivo interface_in_out_bytes.py.
Además de definir la clase del recopilador, defina la función collector_plugin en el archivo del recopilador. La función toma un argumento y devuelve la clase de recopilador que se implementa.
Por ejemplo, un recopilador genérico basado en esquemas de almacenamiento tiene el siguiente aspecto:
"""
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 InterfaceRxTxCollector
Un recopilador basado en esquemas de almacenamiento IBA tiene el siguiente aspecto:
"""
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 IbaBgpCollector
Recolector de pruebas unitarias
La carpeta aos_developer_sdk/aosstdcollectors/test del repositorio contiene carpetas basadas en el NOS. Agregue la prueba a la carpeta que coincida con el NOS. Por ejemplo, se agrega una prueba a un recopilador para Cumulus a aos_developer_sdk/aosstdcollectors/test/cumulus. Recomendamos que nombre la prueba unitaria con el prefijo test_.
La infraestructura existente implementa un dispositivo collector_factory Pytest que se utiliza para simular la respuesta de comando del controlador del dispositivo. El flujo general para el desarrollo de pruebas es el siguiente.
- Use la fábrica de recolector para obtener una instancia de recopilador y se burló del marco de Trabajo de Apstra. La fábrica del recopilador toma la clase del recopilador que ha escrito como entrada.
- Simulación de la respuesta del dispositivo.
- Método Invoke collect.
- Valide los datos publicados en el marco simulado de Apstra.
Por ejemplo, una prueba tiene el siguiente aspecto:
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"])
Para ejecutar la prueba, ejecute lo siguiente:
root@1df9bf89aeaf:/aos_developer_sdk# make test root@1df9bf89aeaf:/aos_developer_sdk# make test
Este comando ejecuta todas las pruebas en el repositorio.
Recolector de paquetes
Todos los recolectores están empaquetados en base al NOS. Para generar todos los paquetes, ejecute make en aos_develop_sdk. Puede encontrar los paquetes de compilación en aos_developer_sdk/dist. La compilación de paquetes se puede clasificar en términos generales como:
| Descripción | del paquete |
|---|---|
| Paquetes de recolector integrados | Estos paquetes tienen el prefijo aosstdcollectors_builtin_. Para recopilar telemetría desde un dispositivo según el diseño de referencia, Apstra requiere servicios como se enumeran en la <deviceblah> sección. Los paquetes de recolección integrados contienen recolectores para estos servicios. Los paquetes se generan por NOS. |
| Paquetes de recolección personalizados | Estos paquetes tienen el prefijo aosstdcollectors_custom_ en sus nombres. Los paquetes se generan por NOS. El paquete denominado aosstdcollectors_custom_<NOS>-0.1.0-py2-none-any.whl contiene el recopilador desarrollado. |
| Paquetes de controladores de dispositivos de Apstra SDK | Estos paquetes tienen un prefijo apstra_devicedriver_. Estos paquetes se generan por NOS. Los paquetes se generan para NOS que no están disponibles de forma predeterminada en Apstra. |
Cargar paquetes
Si los paquetes de recolección integrados y el controlador de dispositivo del SDK de Apstra para su sistema operativo de dispositivo (NOS) no se proporcionaron con el software Apstra, debe cargarlos en el servidor de Apstra.
Si está utilizando una solución offbox y su NOS no es EOS, debe cargar el paquete del recolector integrado.
Cargue el paquete que contiene los recolectores y asígnelos a un agente de sistema de dispositivos o a un perfil de agente de sistema.
Usar recolector de telemetría
- Configurar el registro del servicio de telemetría
- Iniciar recopilador
- Eliminar recopilador
- Obtener datos recopilados
- Servicios de recolector en ejecución de lista
Configurar el registro del servicio de telemetría
El Registro asigna el servicio a su esquema de aplicación y a la ruta de esquema de almacenamiento. Puede administrar el registro del servicio de telemetría con el punto de conexión /api/telemetry-service-registryREST. No puede habilitar el recopilador para un servicio sin agregar una entrada del Registro para el servicio en particular. La entrada del Registro de un servicio no se puede modificar mientras el servicio está en uso.
Al ejecutar make, todos los esquemas de aplicación se empaquetan en un archivo tar (json_schemas.tgz) en la carpeta dist. Con apstra-cli, tiene la opción de importar todos los esquemas en el archivo .tgz.
Iniciar recopilador
Para iniciar un servicio, use la API /api/systems/<system_id>/services POST con los tres argumentos siguientes:
| Argumentos | |
|---|---|
| Input_data | Los datos proporcionados como entrada al recopilador. Valores predeterminados a Ninguno. |
| Intervalo | Intervalo en el que se ejecutará el servicio. Los valores predeterminados son de 120 segundos. |
| Nombre | Nombre del servicio. |
También puede administrar recolectores a través de la utilidad apstra-cli.
Eliminar recopilador
Para eliminar un servicio, utilice la API /api/systems/<system_id>/services/<service_name>DELETE .
Obtener datos recopilados
Para recuperar los datos recopilados, utilice la API /api/systems/<system_id>/services/<service_name>/dataGET . Solo se guardan los datos recopilados en la última iteración. Los datos no persisten durante el reinicio de Apstra.
Servicios de recolector en ejecución de lista
Para recuperar la lista de servicios habilitados en un dispositivo, utilice la API /api/systems/<system_id>/servicesGET .