Uruchamianie scenariusza testowego

Przed przystąpieniem do uruchomienia testu należy pobrać z api potrzebne dane, które będą służyły do stworzenia poprawnej struktury wiadomości wysłanej do serwera przez api w celu uruchomienia scenariusza testowego.

Pobranie listy możliwych testów do uruchomienia

Aby pobrać listę testów, które można uruchomić na test agencie należy wysłać wiadomość GET na adres /api/task_types/.
Powinniśmy otrzymać wiadomość o takiej strukturze danych:
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 20,
            "subcategories": [
                {
                    "id": 9,
                    "category": 4
                }
            ],
            "options": {
                "params": [
                    {
                        "name": "address",
                        "type": "text",
                        "label": "Destination address",
                        "tooltip": {
                            "color": "blue",
                            "value": "Destination hostname which ping will travel to",
                            "placement": "top"
                        },
                        "attributes": {
                            "initial": "8.8.8.8",
                            "required": 1
                        },
                        "validators": [
                            {
                                "type": "hostname",
                                "message": "Enter a valid hostname",
                                "regex": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9])$"
                            }
                        ]
                    },
                    {
                        "name": "count",
                        "type": "slider",
                        "label": "Number of ICMP Requests",
                        "tooltip": {
                            "color": "blue",
                            "value": "Send more than 5 ICMP requests to analyze jiter",
                            "placement": "top"
                        },
                        "attributes": {
                            "step": 1,
                            "initial": 1,
                            "max_value": 10,
                            "min_value": 1
                        }
                    },
                    {
                        "name": "interval",
                        "type": "slider",
                        "label": "Interval between consecutive ICMP Requests",
                        "attributes": {
                            "step": 1,
                            "initial": 1,
                            "max_value": 10,
                            "min_value": 1
                        }
                    }
                ],
                "additional_options": {
                    "thresholds": {
                        "params": [
                            {
                                "name": "Mean RTT of ping test",
                                "param": "mean_rtt"
                            },
                            {
                                "name": "Max RTT of ping test",
                                "param": "max_rtt"
                            },
                            {
                                "name": "Min RTT of ping test",
                                "param": "min_rtt"
                            }
                        ],
                        "enabled": true
                    },
                    "dedicated_instances": {
                        "enabled": true
                    }
                }
            },
            "permitted": true,
            "command": "network_ping",
            "name": "network_ping",
            "display_name": "Ping",
            "description": "Simple ping test extended with jiter analysis.",
            "on_premises_available": true,
            "cloud_available": true,
            "cost": 0,
            "sort_priority": 0
        },
        {
            "id": 21,
            "subcategories": [
                {
                    "id": 9,
                    "category": 4
                }
            ],
            "options": {
                "params": [
                    {
                        "name": "address",
                        "type": "text",
                        "label": "Destination address",
                        "attributes": {
                            "initial": "8.8.8.8",
                            "required": 1
                        },
                        "validators": [
                            {
                                "type": "hostname",
                                "message": "Enter a valid hostname",
                                "regex": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9])$"
                            }
                        ]
                    }
                ],
                "additional_options": {}
            },
            "permitted": true,
            "command": "traceroute_test",
            "name": "traceroute_test",
            "display_name": "Traceroute",
            "description": "Traceroute test.",
            "on_premises_available": true,
            "cloud_available": true,
            "cost": 0,
            "sort_priority": 0
        }
    ]
}
Z otrzymanej wiadomości z api wynika, że dostępne są 2 testy: Ping – id 20 oraz Traceroute – id 21. Identyfikatory pobranych testów oraz ich parametry przydadzą się później nam do budowy struktury danych potrzebnej do uruchomienia scenariusza.

Pobranie danych dostępnych test agentów

Aby móc uruchomić scenariusz testowy musimy wiedzieć, na którym z dostępnych test agentów chcemy go uruchomić. W tym celu możemy pobrać listę test agentów opisaną w rozdziale o Test Agentach lub jeśli znamy już id test agenta możemy pobrać tylko jego dane i upewnić się, że jest on autoryzowany i jest online w naszej sieci. W tym celu powinniśmy wysłać wiadomość GET na adres /api/user/test_agents/1/, ponieważ 1 to id test agenta, którego omawialiśmy w poprzednim rozdziale dokumentacji. W odpowiedzi powinniśmy otrzymać strukturę danych test agenta:
{
    "id": 1,
    "uuid": "bb70540b-d2b0-4867-b10f-3b2e5b20c50f",
    "name": "new-test-agent",
    "ip_local": "172.30.10.1",
    "ip_external": "172.30.10.1",
    "status": 3,
    "last_status_change": "2021-04-28T12:15:31.578153+02:00",
    "authorized": true,
    "timestamp_created": "2021-04-28T12:11:22.356223+02:00",
    "version": "2020.12",
    "geo_location_lon": 19.8972702026367,
    "geo_location_lat": 50.0760912565959,
    "running_monitoring_count": 0,
    "release": "0.2.0.dev146",
    "additional_data": {
        "interfaces": {
            "lo": {
                "ip": [
                    "127.0.0.1",
                    "::1"
                ],
                "mac": "00:00:00:00:00:00",
                "name": "lo"
            },
            "ens3": {
                "ip": [
                    "172.30.10.1",
                    "fe80::f816:3eff:fe39:8fcb%ens3"
                ],
                "mac": "fa:16:3e:39:8f:cb",
                "name": "ens3"
            }
        },
        "network_config": "network:\n    ethernets:\n        ens3:\n            dhcp4: true\n            match:\n                macaddress: fa:16:3e:39:8f:cb\n            set-name: ens3\n    version: 2\n    renderer: networkd"
    },
}
Zgodnie z tymi danymi możemy stwierdzić, że test agent został już autoryzowany oraz, że jest online, na co wskazuje status równy liczbie 3 (status = 2 oznacza, że test agent jest offline). Powinniśmy się również upewnić czy wersja test agenta (pole version) oraz ip urządzenia (pole ip) jest zgodne z naszymi oczekiwaniami. Po ustaleniu, że jest to test agent, na którym chcemy uruchomić nasz scenariusz możemy przystąpić do budowy wiadomości, po której wysłaniu będzie można uruchomić nasz scenariusz.

Budowa wiadomości potrzebnej do uruchomienia scenariusza testowego

Załóżmy, że chcemy w ramach scenariusza wykonywać 2 testy, których dane pobraliśmy w punkcie 1., czyli test Ping oraz test Traceroute.
W pierwszej kolejności należy uzupełnić podstawowe dane dotyczące uruchomienia testu:

  • name – nazwa scenariusza testowego,

  • on_premise_test_agents – globalna lista id wszystkich test agentów, na których chcemy uruchomić wszystkie testy, dla których nie określono test agentów w strukturze danych poszczególnych testów scenariusza w polu test_blocks,

  • cloud_locations – globalna lista id wszystkich lokalizacji chmurowych, na których chcemy uruchomić wszystkie testy, dla których nie określono lokalizacji chmurowych w strukturze danych poszczególnych testów scenariusza w polu test_blocks,

  • repeat_interval – liczba wyrażona w sekundach oznaczająca czas pomiędzy kolejnymi uruchomieniami scenariusza, w przypadku gdy chcemy go uruchomić tylko raz należy podać 0,

  • repeat_start – czas uruchomienia pierwszego cyklu scenariusza (dozwolone są jedynie pełne minuty oraz 0, 15, 30 lub 45 minuta każdej godziny), w przypadku gdy chcemy go uruchomić tylko raz należy podać null,

  • repeat_end – czas zakończenia działania scenariusza (dozwolone są jedynie pełne minuty oraz 0, 15, 30 lub 45 minuta każdej godziny), w przypadku gdy chcemy go uruchomić tylko raz należy podać null,

  • options - dodatkowe opcje scenariusza (jeśli chcemy użyć globalnych opcji należy w tym polu podać {}, lub wcale nie podawać tego pola w strukturze wiadomości):

    • notifications - lokalne ustawienia powiadomień dla scenariusza,

    • priority_limit - wartość progowa oznaczająca to, że bloki testowe mające ustalony priorytet poniżej tej wartości nie będą generowały powiadomień po przekroczoneniu progu alarmowego,

    • thresholds - zaawansowana opcja ustalania progów alarmowych poprzez treść kodu napisanego w języku Python:

      • enabled - informacja o tym, czy konfiguracja ma być włączona (dozwolone wartości: true oraz false),

      • code - treść kodu w języku Python,

    • 5g_config - konfiguracja połączenia z rdzeniem sieci 5G:

      • mme_address - adres modułu MME będącego częścią rdzenia 5G,

      • imsi - akceptowalny przez sieć 5G numer IMSI,

      • opc - akceptowalny przez sieć 5G klucz operatora,

      • k - akceptowalny przez sieć 5G klucz abonenta,

  • test_blocks – lista wszystkich bloczków testowych, które chcemy uruchomić (ten sam test można wykonać w ramach scenariusza dowolną ilość razy).

Aby uruchomić konkretne testy na test agencie należy dodać ich strukturę do parametru test_blocks. Parametr ten przyjmuje wartości listy obiektów. Każdy z tych obiektów to jeden bloczek testu w naszym scenariuszu. Każdy obiekt tej listy powinien zawierać pola:

  • name – nazwa bloczka (pole wymagane),

  • stage_no – numer kroku scenariusza (pierwszy krok to 1), ustawienie tego samego numeru kroku dla kilku testów spowoduje uruchomienie tych testów równolegle wobec siebie,

  • task_type – id testu zgodne z wiadomością z /api/task_types/ lub /api/task_types/<id> (Opis pobierania typów testów),

  • on_premise_test_agents – lista test agentów, na których ma być uruchomiony ten test, w przypadku pustej listy test zostanie wykonany na test agentach znajdujących się na globalnej liście dla całego scenariusza,

  • cloud_locations – lista lokalizacji chmurowych na których ma być uruchomiony ten test, w przypadku pustej listy test zostanie wykonany w lokalizacjach znajdujących się na globalnej liście dla całego scenariusza,

  • options – obiekt zawierający opcje bloczka takie jak parametry testu czy konfiguracja progów alarmowych:

    • params - lista parametrów unikalnych dla danego typu testu, zgodna z wiadomością z /api/task_types/ lub /api/task_types/<id> (Pobieranie parametrów testu),

    • priority - ważność bloczka określony wartością liczbową,

    • thresholds – konfiguracja progów alarmowych:

      • enabled - informacja, czy progi dla tego bloczka mają być włączone (dozwolone wartości: true oraz false),

      • mode - tryb podawania konfiguracji progów (dozwolone wartości: „python” dla konfiguracji w języku Python oraz „json” dla konfiguracji w formacie JSON),

      • configuration - konfiguracja progów alarmowych w trybie „json”, wartością powinien być obiekt zawierający pola podane poniżej,

      • code - konfiguracja progów alarmowych w trybie „python”, wartością powinien być kod napisany w języku Python,

    • 5g_enabled - flaga oznaczająca, czy dany test ma być przeprowadzony przez skonfigurowaną w scenariuszu sieć 5G.

Obiekt „configuration” powinien zawierać podane pola:

  • type – typ informacji, dozwolone pola: threshold i operator,

  • threshold_type (tylko dla typu threshold) – informacja o tym, czy próg został przekroczony powyżej, czy poniżej danej wartości, możliwe typy progów:

    • gte – próg zostanie przekroczony jeśli wartość parametru będzie większa lub równa niż wartość zadeklarowana,

    • gt - próg zostanie przekroczony jeśli wartość parametru będzie większa niż wartość zadeklarowana,

    • lte – próg zostanie przekroczony jeśli wartość parametru będzie mniejsza lub równa niż wartość zadeklarowana,

    • lt - próg zostanie przekroczony jeśli wartość parametru będzie mniejsza niż wartość zadeklarowana,

  • value (tylko dla typu threshold) – wartość progu alarmowego,

  • variable (tylko dla typu threshold) – nazwa mierzonego parametru testu, do którego ma być przypisany próg alarmowy, dostępne parametry znajdują się w /api/task_types/ lub /api/task_types/<id> (Pobieranie parametrów testu),

  • operator_type (tylko dla typu operator) – łącznik między thresholdami, możliwe wartości „and” lub „or”,

  • thresholds (tylko dla typu operator) - lista thresholdów wg powyższego opisu.

Aby ustawić lokalne powiadomienia, należy w polu options dodać obiekt notifications zawierający pola:

  • „1” - oznaczający powiadomienia na start testu,

  • „2” - oznaczający powiadomienia na koniec testu,

  • „3” - oznaczający powiadomienia, gdy test nie został wykonany poprawnie,

  • „4” - oznaczający powiadomienia na przekroczenie progu alarmowego,

  • „5” - oznaczający powiadomienia na uruchomienie całego scenariusza,

  • „6” - oznaczający powiadomienia na zakończenie całego scenariusza.

Wartością każdego z tych pól powinna być tablica identyfikatorów punktów dostarczania powiadomień. Przykładowo zapis „1”: [1,2] oznaczać będzie, że powiadomienia na start testu będą wysyłane do punktów o id równym 1 i id równym 2. Opis konfiguracji punktów dostarczania powiadomień znajduje się tutaj.
W przypadku braku pola options lub braku konkretnego pola w notifications, będą brane pod uwagę globalne ustawienia dla danego typu powiadomienia, które można zmienić poprzez edycję globalnych ustawień powiadomień (Opis włączania/wyłączania powiadomień).
Poniższy przykład przedstawia wiadomość wysłaną do serwera po której zostanie uruchomiony scenariusz testowy zawierający jedno wykonanie testu Ping, a po nim jedno wykonanie testu Traceroute, a całość tej sekwencji będzie powtarzana:

  • pierwszy test scenariusza zostanie uruchomiony dnia 22.04.2021 o godzinie 15:15,

  • scenariusz testowy zostanie zakończony dnia 22.04.2021 o godzinie 16:15,

  • sekwencje testów będą odbywać się co 60 sekund,

  • zostaną wygenerowane powiadomienia tylko w sytuacji, gdy progi alarmowe skonfigurowane w bloczku testowym zostaną przekroczone,

  • wszystkie testy scenariusza zostaną wykonane na test agencie z id 1,

  • dla całego scenariusza zostaną ustawione progi alarmowe wg których próg będzie przekroczony jeśli średnia z RTT przekracza 20 ms lub odchylenie standardowe przekracza 0.1 wartości średniej,

  • do scenariusza dodana została konfiguracja dostępu do sieci 5G, ale żaden test nie będzie wykonywał takich testów,

  • w pierwszym kroku scenariusza zostanie wykonany test Ping (id: 20),

  • test Ping zostanie wykonany z parametrami:

    • adres docelowy: www.netrsr.com,

    • liczba żądań ICMP: 1,

    • interwał między żądaniami ICMP: 1,

  • dla testu Ping zostaną ustawione progi, które będą alarmować w przypadku wartości min_rtt mniejszej niż 10 lub wartości max_rtt wyższej niż 100,

  • dla testu Ping nie zostaną wygenerowane powiadomienia w przypadku przekroczenia progu, ponieważ wartość parametr priority dla tego bloczka jest mniejszy niż ustalony priority_limit dla całego scenariusza,

  • w drugim kroku scenariusza zostanie wykonany test Traceroute (id: 21),

  • test Traceroute zostanie wykonany z parametrami:

    • adres docelowy: www.netrsr.com,

  • do testu Traceroute nie zostaną dodane progi alarmowe.

{
    "name":"Ping",
    "repeat_interval":60,
    "repeat_start":"2021-04-22T15:15:00.000Z",
    "repeat_end":"2021-04-22T16:15:00.000Z",
    "cloud_locations":[],
    "on_premise_test_agents":[1],
    "options": {
        "notifications": {
            "1": [],
            "2": [],
            "3": [],
            "4": [1],
            "5": [],
            "6": []
        },
        "priority_limit": 20,
        "thresholds": {
            "enabled": true,
            "code": "exceeded = False\r\nfor ta, ta_data in data.items():\r\n\r\n    rtts = [row['rtt'] for row in ta_data['ping_block']['results'][-1]['result'][-1]['list']]\r\n    rtts_mean = statistics.mean(rtts)\r\n    rtts_std = statistics.stdev(rtts)\r\n    \r\n    ta_exceeded = rtts_mean > 20 or rtts_std < 0.1 * rtts_mean\r\n    exceeded != ta_exceeded  \r\n"
        },
        "5g_config": {
            "k": "00112233445566778899aabbccddeeff",
            "opc": "63BFA50EE6523365FF14C1F45F88737D",
            "imsi": "999700123456780",
            "mme_address": "172.30.30.209"
        }
    },
    "test_blocks": [
        {
            "name":"Ping1",
            "stage_no":1,
            "task_type":20,
            "cloud_locations":[],
            "on_premise_test_agents":[],
            "options": {
                "params": {
                    "address":"www.netrsr.com",
                    "count":1,
                    "interval":1
                },
                "priority": 10,
                "5g_enabled": false,
                "thresholds": {
                    "enabled": true,
                    "mode": "json",
                    "configuration": {
                        "type": "operator",
                        "operator_type": "or",
                        "thresholds": [
                            {
                                "type":"threshold",
                                "threshold_type":"lt",
                                "value":10,
                                "variable":"min_rtt"
                            },
                            {
                                "type":"threshold",
                                "threshold_type":"gte",
                                "value":100,
                                "variable":"max_rtt"
                            }
                        ]
                    }
                }
            }
        },
        {
            "name":"Traceroute1",
            "stage_no":2,
            "task_type":21,
            "cloud_locations":[],
            "on_premise_test_agents":[],
            "options": {
                "params": {
                    "address":"www.netrsr.com"
                },
                "priority": 10,
                "5g_enabled": false,
                "thresholds": {}
            }
        }
    ]
}

Pobranie id scenariusza

W odpowiedzi na powyższą wiadomość powinniśmy otrzymać odpowiedź z taką samą treścią, która została wysłana przez nas wraz z dodatkowymi parametrami:

  • id - identyfikator scenariusza, który posłuży nam do łatwiejszego znalezienia wyników wszystkich testów wykonanych w ramach dodanego w poprzednim kroku scenariusza testowego,

  • timestamp_created – datę utworzenia scenariusza,

  • paused (true lub false) – informację o tym, czy scenariusz jest obecnie wstrzymany, czy normalnie wykonuje testy,

  • status – status scenariusza:

    • 1 – zaplanowany,

    • 2 – uruchomiony,

    • 3 – wstrzymany,

    • 4 – zakończony.

W strukturze test_blocks przy każdym z bloczków testowych powinno się pojawić jeszcze nadane przez serwer jego id, dzięki któremu można potem w łatwy sposób znaleźć wyniki tylko dla danego bloczka.
{
    "id": 1,
    "timestamp_created":"2021-04-22T15:07:49.276522+02:00",
    "paused":false,
    "name":"Ping",
    "repeat_interval":60,
    "repeat_start":"2021-04-22T15:15:00.000Z",
    "repeat_end":"2021-04-22T16:15:00.000Z",
    "cloud_locations":[],
    "on_premise_test_agents":[1],
    "options": {
        "notifications": {
            "1": [],
            "2": [],
            "3": [],
            "4": [1],
            "5": [],
            "6": []
        },
        "priority_limit": 20,
        "thresholds": {
            "enabled": true,
            "code": "exceeded = False\r\nfor ta, ta_data in data.items():\r\n\r\n    rtts = [row['rtt'] for row in ta_data['ping_block']['results'][-1]['result'][-1]['list']]\r\n    rtts_mean = statistics.mean(rtts)\r\n    rtts_std = statistics.stdev(rtts)\r\n    \r\n    ta_exceeded = rtts_mean > 20 or rtts_std < 0.1 * rtts_mean\r\n    exceeded != ta_exceeded  \r\n"
        },
        "5g_config": {
            "k": "00112233445566778899aabbccddeeff",
            "opc": "63BFA50EE6523365FF14C1F45F88737D",
            "imsi": "999700123456780",
            "mme_address": "172.30.30.209"
        }
    },
    "test_blocks": [
        {
            "id":6,
            "name":"Ping1",
            "stage_no":1,
            "task_type":20,
            "cloud_locations":[],
            "on_premise_test_agents":[],
            "options": {
                "params": {
                    "address":"www.netrsr.com",
                    "count":1,
                    "interval":1
                },
                "priority": 10,
                "5g_enabled": false,
                "thresholds": {
                    "enabled": true,
                    "mode": "json",
                    "configuration": {
                        "type": "operator",
                        "operator_type": "or",
                        "thresholds": [
                            {
                                "type":"threshold",
                                "threshold_type":"lt",
                                "value":10,
                                "variable":"min_rtt"
                            },
                            {
                                "type":"threshold",
                                "threshold_type":"gte",
                                "value":100,
                                "variable":"max_rtt"
                            }
                        ]
                    }
                }
            }
        },
        {
            "id":7,
            "name":"Traceroute1",
            "stage_no":2,
            "task_type":21,
            "cloud_locations":[],
            "on_premise_test_agents":[],
            "options": {
                "params": {
                    "address":"www.netrsr.com"
                },
                "priority": 10,
                "5g_enabled": false,
                "thresholds": {}
            }
        }
    ]
}