확장형 텔레메트리 가이드
확장 가능한 텔레메트리 개요
IBA 프로브에서 사용할 수 있는 추가 텔레메트리를 수집하기 위해 Apstra 디바이스 드라이버 및 텔레메트리 수집기를 설치합니다. 디바이스 드라이버 덕분에 Apstra는 NOS에 연결하고 텔레메트리를 수집할 수 있습니다. Apstra는 EOS, NX-OS, Ubuntu 및 CentOS의 드라이버와 함께 제공합니다. 여기에 나열되지 않은 운영 체제에 대한 드라이버를 추가하려면 Juniper Support에 문의하십시오.
텔레메트리 수집기는 확장된 텔레메트리를 수집하는 데 도움이 되는 Python 모듈입니다. 다음 섹션에서는 텔레메트리 수집기 생성 및 새로운 수집기로 Apstra를 확장하기 위한 파이프라인에 대해 설명합니다. 수집기를 개발할 수 있으려면 Python에 익숙해져야 합니다.
개발 환경 설정
텔레메트리 수집기( aos_developer_sdk 리포지토리에 보관되어 있는)에 액세스하려면 Juniper Support에 문의하십시오. 개발한 모든 새로운 수집기를 리포지토리에 기여하십시오.
시스템 환경을 그대로 유지하기 위해 가상 환경을 사용하여 필요한 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 패키지도 환경에 설치됩니다.
컬렉터 개발
텔레메트리 수집기를 개발하려면 다음을 순서대로 지정해야 합니다.
쓰기 수집기
컬렉터는 aos.sdk.system_agent.base_telemetry_collector에서 파생되어야 하는 클래스입니다. BaseTelemetryCollector. 로직으로 수집기의 수집 방법을 재정의:
디바이스에서 데이터 수집
수집기 내의 디바이스 드라이버 인스턴스는 디바이스에 대한 명령을 실행하는 방법을 제공합니다. 예를 들어, 대부분의 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 .
데이터를 프레임워크에 게시
필요한 스키마에 따라 데이터가 수집되고 구문 분석되면 프레임워크에 데이터를 게시합니다. 수집기에서 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_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 프레임워크를 다운로드합니다. 수집기 공장은 입력으로 작성한 수집기 클래스를 사용합니다.
- 디바이스 응답을 조롱합니다.
- 수집 방법을 호출합니다.
- 조롱된 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가 아닌 경우 내장 컬렉터 패키지를 업로드해야 합니다.
수집기가 포함된 패키지를 업로드하고 디바이스 시스템 에이전트 또는 시스템 에이전트 프로필에 할당합니다.
텔레메트리 수집기 사용
텔레메트리 서비스 레지스트리 설정
레지스트리는 서비스를 애플리케이션 스키마 및 스토리지 스키마 경로에 매핑합니다. REST 엔드포인트 /api/telemetry-service-registry로 텔레메트리 서비스 레지스트리를 관리할 수 있습니다. 특정 서비스에 대한 레지스트리 항목을 추가하지 않고는 서비스에 대한 수집기 활성화할 수 없습니다. 서비스를 사용하는 동안 서비스에 대한 레지스트리 항목을 수정할 수 없습니다.
실행할 make때 모든 애플리케이션 스키마는 dist 폴더의 tar 파일(json_schemas.tgz)으로 함께 패키징됩니다. apstra-cli를 사용하면 .tgz 파일의 모든 스키마를 가져올 수 있습니다.
시작 컬렉터
서비스를 시작하려면 다음 세 가지 인수와 함께 POST API /api/systems/<system_id>/services 를 사용합니다.
| 인수 | |
|---|---|
| Input_data | 수집기 에 대한 입력으로 제공된 데이터. 기본값은 없음입니다. |
| 간격 | 서비스를 실행할 간격. 기본값은 120초입니다. |
| 이름 | 서비스 이름입니다. |
Apstra-cli 유틸리티를 통해 수집기도 관리할 수 있습니다.
수집기 삭제
서비스를 삭제하려면 API /api/systems/<system_id>/services/<service_name>삭제 을(를) 사용합니다.
데이터 수집
수집된 데이터를 검색하려면 GET API /api/systems/<system_id>/services/<service_name>/data를 사용합니다. 마지막 반복에서 수집된 데이터만 저장됩니다. Apstra Restart를 통해 데이터는 지속되지 않습니다.
실행 중인 수집기 서비스 목록
디바이스에서 활성화된 서비스 목록을 검색하려면 GET API /api/systems/<system_id>/services를 사용합니다.