확장 가능한 텔레메트리 가이드
확장 가능한 텔레메트리 개요
Apstra 디바이스 드라이버와 텔레메트리 수집기를 설치하여 분석 프로브에 사용할 수 있는 추가 텔레메트리를 수집합니다. 디바이스 드라이버를 사용하면 Apstra가 NOS에 연결하고 텔레메트리를 수집할 수 있습니다. Apstra는 EOS, NX-OS, Ubuntu 및 CentOS용 드라이버와 함께 제공됩니다. 여기에 나열되지 않은 운영 체제용 드라이버를 추가하려면 주니퍼 지원에 문의하십시오.
원격 분석 수집기는 확장된 원격 분석을 수집하는 데 도움이 되는 Python 모듈입니다. 다음 섹션에서는 텔레메트리 수집기를 생성하고 새 수집기로 Apstra를 확장하기 위한 파이프라인에 대해 설명합니다. 수집기를 개발하려면 Python에 익숙해야 합니다.
개발 환경 설정
텔레메트리 수집기( aos_developer_sdk 저장소에 보관되어 있음)에 액세스하려면 주니퍼 지원에 문의하십시오. 개발하는 모든 새 수집기를 저장소에 기여합니다.
시스템 환경을 그대로 유지하려면 가상 환경을 사용하여 필요한 Python 패키지(개발 및 테스트용)를 격리하는 것이 좋습니다. https://support.juniper.net/support/downloads/?p=apstra/ 에서 기본 개발 환경 aos_developer_sdk.run을 다운로드할 수 있습니다. 환경을 로드하려면 다음을 실행합니다.
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
================================================================================
이 명령은 aos_developer_sdk Docker 이미지를 로드합니다. 이미지 로드가 완료되면 환경을 시작하는 명령이 인쇄됩니다. 명령에 지정된 대로 컨테이너 환경을 시작합니다. 종속성을 설치하려면 다음을 실행합니다.
root@f2ece48bb2f1:/# cd /aos_developer_sdk/ root@f2ece48bb2f1:/aos_developer_sdk# make setup_env ...
이제 수집기를 개발하고 테스트하기 위한 환경이 설정되었습니다. 디바이스 드라이버 및 REST 클라이언트와 같은 Apstra SDK 패키지도 환경에 설치됩니다.
Collector 개발
텔레메트리 수집기를 개발하려면 다음을 순서대로 지정합니다.
쓰기 수집기
Collector는 aos.sdk.system_agent.base_telemetry_collector에서 파생되어야 하는 클래스입니다. BaseTelemetryCollector입니다. 수집기의 collect 메서드를 다음과 같은 논리로 재정의합니다.
장치에서 데이터 수집
수집기 내의 장치 드라이버 인스턴스는 장치에 대해 명령을 실행하는 메서드를 제공합니다. 예를 들어, 대부분의 Apstra 디바이스 드라이버는 명령을 실행하고 출력을 반환하는 메서드 get_json 와 get_text 메소드를 제공합니다.
aos_developer_sdk 환경을 위한 장치 드라이버가 사전 설치되어 있습니다. 데이터를 수집하는 데 사용할 수 있는 방법을 탐색할 수 있습니다. 예를 들어:
>>> 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']
데이터 구문 분석
수집된 데이터는 위에서 식별된 Apstra 프레임워크 및 서비스 스키마에 따라 구문 분석하고 다시 포맷해야 합니다. 일반 저장소 스키마가 있는 수집기는 다음 구조를 따릅니다.
{
"items": [
{
"identity": <key goes here>,
"value": <value goes here>,
},
{
"identity": <key goes here>,
"value": <value goes here>,
},
...
]
}
IBA 기반 스키마가 있는 수집기는 다음 구조를 따릅니다.
[
{
"key": <key goes here>,
"value": <value goes here>,
},
{
"key": <key goes here>,
"value": <value goes here>,
},
...
]
위의 구조에서 게시된 데이터에는 여러 항목이 있습니다. 각 항목에는 키와 값이 있습니다. 예를 들어 인터페이스별 정보를 게시하려면 프레임워크에 게시하려는 각 인터페이스에 대한 ID/키-값 쌍이 있어야 합니다.
타사 패키지를 사용하여 디바이스에서 가져온 데이터를 구문 분석하려는 경우 경로에 Python 패키지 및 버전을 나열합니다.
<aos_developer_sdk>/aosstdcollectors/requirements_<NOS>.txt. 종속성에 의해 설치된 패키지는 Apstra 소프트웨어가 사용하는 패키지와 충돌하지 않습니다. Apstra가 설치한 패키지는 개발 환경에서 사용할 수 /etc/aos/python_dependency.txt 있습니다.
Framework에 데이터 게시
필요한 스키마에 따라 데이터가 수집되고 구문 분석되면 데이터를 프레임워크에 게시합니다. 컬렉터에서 post_data 사용할 수 있는 방법을 사용할 수 있습니다. 그것은 하나의 인수를 받아들이고, 그것은 프레임 워크에 게시되어야하는 데이터입니다.
저장소의 폴더 aos_developer_sdk/aosstdcollectors/aosstdcollectors 에는 각 NOS에 대한 폴더가 포함되어 있습니다. NOS와 일치하는 폴더에 컬렉터를 추가합니다. Cumulus는 Apstra 버전 4.1.0부터 더 이상 지원되지 않지만, 이 예시는 설명을 위해 유지됩니다. 예를 들어 Cumulus에 대한 수집기를 작성하려면 수집기를 aos_developer_sdk/aosstdcollectors/aosstdcollectors/cumulus에 추가하고 서비스 이름을 따서 파일 이름을 지정합니다. 예를 들어 서비스 이름이 interface_in_out_bytes인 경우 파일 interface_in_out_bytes.py이름을 .
collector 클래스를 정의하는 것 외에도 collector 파일에서 함수를 collector_plugin 정의합니다. 이 함수는 하나의 인수를 사용하고 구현된 수집기 클래스를 반환합니다.
예를 들어 일반 저장소 스키마 기반 수집기는 다음과 같습니다.
"""
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
IBA 저장소 스키마 기반 수집기는 다음과 같습니다.
"""
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
단위 테스트 수집기
저장소의 폴더 aos_developer_sdk/aosstdcollectors/test 에는 NOS를 기반으로 하는 폴더가 포함되어 있습니다. NOS와 일치하는 폴더에 테스트를 추가합니다. 예를 들어, Cumulus에 대한 컬렉터에 대한 테스트가 에 추가됩니다 aos_developer_sdk/aosstdcollectors/test/cumulus. 단위 테스트의 이름은 접두사 test_를 사용하여 지정하는 것이 좋습니다.
기존 인프라는 장치 드라이버 명령 응답을 모의하는 데 사용되는 Pytest 픽스처 collector_factory 를 구현합니다. 테스트 개발을 위한 일반적인 흐름은 다음과 같습니다.
- 수집기 팩토리를 사용하여 수집기 인스턴스와 모의 Apstra 프레임워크를 가져옵니다. 수집기 팩토리는 사용자가 작성한 수집기 클래스를 입력으로 사용합니다.
- 디바이스 응답을 모의합니다.
- collect 메서드를 호출합니다.
- 모의 Apstra 프레임워크에 게시된 데이터를 검증합니다.
예를 들어 테스트는 다음과 같습니다.
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"])
테스트를 실행하려면 다음을 실행합니다.
root@1df9bf89aeaf:/aos_developer_sdk# make test root@1df9bf89aeaf:/aos_developer_sdk# make test
이 명령은 리포지토리의 모든 테스트를 실행합니다.
패키지 수집기
모든 수집기는 NOS를 기준으로 포장됩니다. 모든 패키지를 생성하려면 에서 make를 aos_develop_sdk실행합니다. 빌드 패키지는 에서 찾을 수 있습니다 aos_developer_sdk/dist. 패키지 빌드는 크게 다음과 같이 분류할 수 있습니다.
| 패키지 | 설명 |
|---|---|
| 빌트인 컬렉터 패키지 | 이러한 패키지에는 접두사 aosstdcollectors_builtin_가 있습니다. 레퍼런스 설계에 따라 디바이스에서 텔레메트리를 수집하려면 Apstra에 섹션에 <deviceblah> 나열된 서비스가 필요합니다. 기본 제공 수집기 패키지에는 이러한 서비스에 대한 수집기가 포함되어 있습니다. 패키지는 NOS 기준으로 생성됩니다. |
| 사용자 지정 수집기 패키지 | 이러한 패키지의 이름에는 접두사 aosstdcollectors_custom_ 있습니다. 패키지는 NOS 기준으로 생성됩니다. aosstdcollectors_custom_<NOS>-0.1.0-py2-none-any.whl 이라는 패키지에는 개발된 수집기가 포함되어 있습니다. |
| Apstra SDK 디바이스 드라이버 패키지 | 이러한 패키지에는 접두사 apstra_devicedriver_ 있습니다. 이러한 패키지는 NOS 기준으로 생성됩니다. 패키지는 Apstra에서 기본적으로 사용할 수 없는 NOS에 대해 생성됩니다. |
패키지 업로드
빌트인 컬렉터 패키지 및 장치 운영 체제(NOS)용 Apstra SDK 디바이스 드라이버가 Apstra 소프트웨어와 함께 제공되지 않은 경우 Apstra 서버에 업로드해야 합니다.
오프박스 솔루션을 사용 중이고 NOS가 EOS가 아닌 경우 기본 제공 수집기 패키지를 업로드해야 합니다.
수집기가 포함된 패키지를 업로드하고 디바이스 시스템 에이전트 또는 시스템 에이전트 프로필에 할당합니다.
Telemetry Collector 사용
Telemetry Service Registry 설정
레지스트리는 서비스를 해당 응용 프로그램 스키마 및 저장소 스키마 경로에 매핑합니다. REST 끝점 /api/telemetry-service-registry을 사용하여 텔레메트리 서비스 레지스트리를 관리할 수 있습니다 . 특정 서비스에 대한 레지스트리 항목을 추가하지 않고는 서비스에 대해 수집기를 사용하도록 설정할 수 없습니다. 서비스를 사용하는 동안에는 서비스에 대한 레지스트리 항목을 수정할 수 없습니다.
를 실행하면 make모든 응용 프로그램 스키마가 dist 폴더의 tar 파일(json_schemas.tgz)에 함께 패키징됩니다. apstra-cli를 사용하면 .tgz 파일에 있는 모든 스키마를 임포트할 수 있습니다.
Collector 시작
서비스를 시작하려면 다음 세 가지 인수와 함께 POST API /api/systems/<system_id>/services 를 사용합니다.
| 인수 | |
|---|---|
| Input_data | 수집기에 대한 입력으로 제공되는 데이터입니다. 기본값은 없음입니다. |
| 간격 | 서비스를 실행할 간격입니다. 기본값은 120초입니다. |
| 이름 | 서비스의 이름입니다. |
apstra-cli 유틸리티를 통해 컬렉터를 관리할 수도 있습니다.
수집기 삭제
서비스를 삭제하려면 DELETE API /api/systems/<system_id>/services/<service_name>를 사용합니다.
수집된 데이터 가져오기
수집된 데이터를 검색하려면 GET API /api/systems/<system_id>/services/<service_name>/data를 사용합니다 . 마지막 반복에서 수집된 데이터만 저장됩니다. Apstra 재시작 시에도 데이터가 유지되지 않습니다.
실행 중인 수집기 서비스 나열
디바이스에서 활성화된 서비스 목록을 검색하려면 GET API /api/systems/<system_id>/services를 사용합니다.