Описание API QoE EcoQoE Documentation / Описание API QoE
Базовые принципы
Данные по RTT
Для доступа к измерениям, касающимся задержек в сети оператора (задержки между SYNACK-ACK) используется метод API rtt. Данный метод аналогичен блоку «Распределение RTT» в Web-интерфейсе (см. рисунок ниже).
URL-PATH: /api/v1/rtt
На входе можно задать фильтр по абоненту, группе абонентов, периоду времени. В следующей таблице дано описание допустимых входных параметров.
Параметр | Примеры значений и допустимые значения | Описание |
start_date end_date | start_date=01.04.19%2014:00 end_date=15.04.19 | Начальная и конечная дата периода, за который выводится статистика. Допустимый формат: DD.MM.YY HH:MM – дата и время, DD.MM.YY – только дата. Эти параметры можно также передавать с целочисленными значениями, которые обрабатываются как unixtimestamp. Если параметры не заданы, то будет выведена статистика за сутки |
host | host=10.1.0.2 | Фильтрация по абоненту или по IP-адресу. В качестве значения можно задать номер договора, IP-адрес абонента или подсеть. Если параметр не задан, то выводится статистика по всем абонентам сети |
filter_group filter_value | filter_group=district&filter_value=Московский Допустимые значения параметра filter_group задаются в конфигурационном файле /opt/econat_qoe/econat_qoe/local_settings.py и могут отличаться в каждом отдельном случае. Пример критериев: · crc – количество ошибок CRC · switch – коммутатор доступа · service – услуга · mag_device – магистральный коммутатор · num_contract – номер договора · district – район · router_type – тип Wi-Fi · mac_vendor – вендор абонентского устройства · router_model – модель роутера · cable_length – длина кабеля Внимание! Указанные критерии – это набор признаков со строковыми значениями. Эти признаки необходимы для фильтрации и группировки больших объёмов записей с ключевыми полями ip или num_contract. Смысл признаков определяется оператором на этапе разработки телекоммуникационных услуг | Фильтрация по группе абонентов. В параметре filter_group задаётся критерий, по которому должны быть сгруппированы данные (например, город, услуга или модель маршрутизатора абонента), а в параметре filter_value – значение, по которому необходимо отфильтровать результаты (например, только активные пользователи или величина RTT). Если параметры не заданы, то выводится статистика по всем абонентам сети |
В ответ на запрос функция возвращает ключевые параметры распределения задержек в сети оператора в формате JSON. Ключ response содержит следующие параметры:
- average_rtt – среднее значение RTT,
- median_rtt – медианное значение RTT (половина сессий быстрее данного значения, половина – медленнее),
- total_sessions – количество TCP-сессий,
- long_sessions – количество сессий с RTT более 5 мс,
- quantiles – массив квантилей: время для 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90% самых быстрых сессий.
Из массива квантилей можно, например, рассчитать ширину разброса RTT, отбросив 10% самых быстрых и 10% самых медленных сессий, или построить график частотного распределения задержек (плотности вероятности RTT). На следующем рисунке показан пример построения графика в Excel.
На вышеприведённом графике по оси X откладываются значения RTT, по оси Y – плотность вероятности ΔP/Δrtt = 10/Δrtt (шаг вероятности для последующих квантилей – 10%). Вероятность того, что измеренное значение RTT окажется в промежутке между rtt1 и rtt2 равна площади трапеции, ограниченной графиком и прямыми x=rtt1, x=rtt2, y=0. Таким образом, площадь под всем графиком равна 90%.
При успешном выполнении запроса тело ответа, помимо response, может содержать ключ filters, в котором указаны применённые параметры фильтрации (диапазон времени, IP-адрес, группы абонентов и др.). В таблице ниже даны примеры содержимого ключа filters.
Запрос | Ответ |
start_date=07.04.19&end date=08.04.19&host=10.210.0.0/16 | «filters»: { |
host=rdp | «filters»: { |
filter_group=district&filter_value=Люберцы | «filters»: { |
Кроме того, в ответе присутствует параметр available_filter_groups, в котором указаны заданные в системе допустимые значения входного параметра filter_group.
Пример запрашиваемого URL:
https://10.10.10.10/api/v1/rtt?start_date=16.04.19+10%3A05&end_date=17.04.19+10%3A05&filter_group=district&filter_value=%D0%9A%D0%BE%D0%BC%D0%BC%D1%83%D0%BD%D0%B0%D1%80%D0%BA%D0%B0&groupby=mac_vendor
Пример запроса и ответа на уровне HTTP:
GET /api/v1/rtt?;host=10.1.0.2 HTTP/1.1
Host: 192.168.251.114
Connection: keep-alive
Cache-Control: max-age=0
Authorization: Basic XXXXXXXXXXXXXXXXXXX=
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3
Accept-Encoding: gzip, deflate
Accept-Language: ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7
Cookie: csrftoken=AD3paWVCjfh1d663mbjaGhVQEMZv6V8Z
HTTP/1.1 200 OK
Server: nginx/1.10.3 (Ubuntu)
Date: Wed, 17 Apr 2019 07:29:59 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Language, Cookie
X-Frame-Options: SAMEORIGIN
Content-Language: ru
2f6
{«available_filter_groups»: [{«group»: «switch», «title»: «\u041a\u043e\u043c\u043c\u0443\u0442\u0430\u0442\u043e\u0440 \u0434\u043e\u0441\u0442\u0443\u043f\u0430»}, {«group»: «agg_switch», «title»: «\u0423\u0437\u0435\u043b-\u0430\u0433\u0440\u0435\u0433\u0430\u0446\u0438\u0438»}, {«group»: «num_contract», «title»: «\u0414\u043e\u0433\u043e\u0432\u043e\u0440»}, {«group»: «district», «title»: «\u0420\u0430\u0439\u043e\u043d»}], «response»: {«total_sessions»: 1895, «median_rtt»: 10.0, «long_sessions»: 1414, «average_rtt»: 12.396569920844328, «quantiles»: [1.7000000000000002, 4.2, 6.4, 8.4, 10.0, 12.0, 14.0, 18.8, 31.3]}, «filters»: {«start_timestamp»: 1555399500, «start_ipn»: 167837698, «end_ipn»: 167837698, «end_timestamp»: 1555485900}, «error»: 0}
0
Пример JSON-ответа (для удобства текст декодирован):
{»available_filter_groups»:[ {«group»:»crc», «title»:»Количество ошибок CRC» }, {«group»:»switch», «title»:»Коммутатор доступа» }, {«group»:»service», «title»:»Услуга» }, {«group»:»mag_device», «title»:»Магистральный коммутатор» }, {«group»:»num_contract», «title»:»Договор» }, {«group»:»district», «title»:»Район» }, {«group»:»router_type», «title»:»Тип Wifi» }, {«group»:»mac_vendor», «title»:»Вендор абонентского устройства» }, {«group»:»router_model», «title»:»Модель роутера» }, {»group»:»cable_length», «title»:»Длина кабеля» } ], | Структура «available_filter_groups» содержит допустимые значения для filter_group |
«error»:0, «filters»:{«end_timestamp»:1555484700, «filter_group»:»district», »filter_value»:»Коммунарка», «start_timestamp»:1555398300 }, | Структура «filters» содержит примененные фильтры |
«response»:{ | Структура «response» содержит данные по QoE |
Если по заданным критериям в базе данных ничего не найдено, то придёт ответ с ошибкой:
{
«error»: 1,
«message»: «No matched data»
}Информация об абонентах
Для доступа к данным по абонентам используется API-метод qoe_table. Данный метод реализует аналог таблицы «Аналитика QoE» в Web-интерфейсе (см. рисунок ниже).
URL-PATH: /api/v1/qoe_table
Входные параметры те же, что и для API-метода rtt (см. раздел «Данные по RTT» выше).
В ответ на запрос функция возвращает данные в формате JSON. Ключ response содержит таблицу состояния абонентов в виде массива, где каждый элемент массива – словарь с различными параметрами абонента. Помимо response, ответ может содержать ключ filters, в котором указаны применённые параметры фильтрации (диапазон времени, IP-адрес, группы абонентов и др.). Кроме того, в ответе присутствует параметр available_filter_groups, в котором указаны заданные в системе допустимые значения входного параметра filter_group. Подробные примеры filters и available_filter_groups приведены и разобраны в описании API-метода rtt (см. раздел «Данные по RTT»). В этом разделе для краткости приведён только пример структуры response. Конкретный список ключей-параметров абонента в response зависит от настроек системы; в первую очередь от того, какие критерии группировки в неё загружены.
Пример запроса:
/api/v1/qoe_table?host=rdp
Ответ:
«response»:[
{
«avg_rtt_width»:21.150000000000002,
«cable_length»:»«,
«crc»:»«,
«district»:»Ядро»,
«empty_ses»:0,
«fp_count»:2,
«ip»:»10.210.10.2»,
«ipn»:181537282,
«mac_vendor»:»«,
«mag_device»:»«,
«max_time»:1555419900,
«median_rtt»:6.5,
«min_time»:1555419600,
«num_contract»:»rdp»,
«pkt_per_ses»:146.2857142857143,
«router_model»:»«,
«router_type»:»«,
«rtt_avg»:11.608333333333334,
«rtt_width»:21.150000000000002,
«rx_retr_percent»:0.19607843137254902,
«service»:»Телефония»,
«ses_per_sec»:0.0001388888888888889,
«session_count»:12,
«switch»:»«,
«tx_retr_percent»:2.307692307692308,
«tx_retr_quantile»:1.2448132780082988
},
{
«avg_rtt_width»:0.30000000000000004,
«cable_length»:»«,
«crc»:»«,
«district»:»Ядро»,
«empty_ses»:0,
«fp_count»:1,
«ip»:»10.210.9.98»,
«ipn»:181537122,
«mac_vendor»:»Intel Corporate»,
«mag_device»:»«,
«max_time»:1555455000,
«median_rtt»:0.4,
«min_time»:1555455000,
«num_contract»:»rdp»,
«pkt_per_ses»:87.875,
«router_model»:»«,
«router_type»:»«,
«rtt_avg»:0.38571428571428573,
«rtt_width»:0.30000000000000004,
«rx_retr_percent»:0,
«service»:»Телефония»,
«ses_per_sec»:0.00008101851851851852,
«session_count»:7,
«switch»:»«,
«tx_retr_percent»:0,
«tx_retr_quantile»:0
},
...
]
Загрузка критериев через API
Для загрузки словарей со списком признаков, привязанных к ip или num_contract абонента, используется API-метод upload_groups.
URL-PATH: /api/v1/upload_groups
Этот метод является аналогом страницы «Загрузка критериев» в Web-интерфейсе (см. рисунок ниже) и позволяет загрузить в систему данные о привязке абонентов к району, услугам, коммутаторам и т. п.
Загружаемые данные перезаписывают текущие данные полностью, поэтому нужно всегда загружать полную таблицу данных. Пример содержимого CSV-файла:
Подготовленный CSV-файл передаётся в POST в «сыром» виде.
Пример вызова из командной строки:
root@qoe:~# wget --post-file=dict.csv -q -O – http://login:password@server.address/api/v1/upload_groups
{
«response»: {
«service»: 510,
«primary_key»: «ip»,
«primary_key_index»: 0,
«undescribed_columns»: [
«router_type»,
«router_model»,
«cable_length»],
«valid_cells»: 2550,
«switch»: 510,
«invalid_length_rows»: 1,
«mag_device»: 510,
«num_contract»: 510,
«district»: 510,
«valid_columns»: 5
},
«error»: 0
}
На выходе система передаёт в ключе response информацию о количестве загруженных записей. Если формат CSV-файла не был распознан, то значение ключа error будет не ноль, а ключ message будет содержать сообщение об ошибке.