#!/usr/bin/env python3 """Generate the numeric research appendix from completed, inspected measurements.""" import json from pathlib import Path ROOT = Path(__file__).resolve().parents[1] def main(): path = ROOT / 'evidence/scaling' rows = json.loads((path / 'aggregate.json').read_text(encoding='utf-8')) raw = json.loads((path / 'summary.json').read_text(encoding='utf-8')) labels = {'fixed': 'Фиксированный бюджет API', 'growing': 'Рост бюджета API', 'pool-one': 'DB .25 CPU, pool=1 на API', 'pool-four': 'DB .25 CPU, pool=4 (парный контроль)', 'lb-unbounded': 'LB без ограничения активных запросов', 'lb-bounded': 'LB maxconn=1 на API', 'db-improved': 'Увеличен CPU БД', 'saturation-baseline': 'Насыщение: DB .25 CPU', 'saturation-improved': 'Насыщение: DB 1 CPU'} lines = ['# Исследование: цена масштабирования', '', 'Черненко, БПИ2301. Лабораторная 3, трек 1. Реальные локальные измерения 6 ноября 2026 года.', '', 'Методика, запуск и ограничения: [REPORT.md](REPORT.md) и [RUNBOOK.md](RUNBOOK.md).', 'Числа ниже автоматически рассчитаны из [summary.json](evidence/scaling/summary.json)', 'и [aggregate.json](evidence/scaling/aggregate.json), а не введены вручную.', '', '## Гипотеза и условия', '', 'Добавление API при неизменном общем ресурсе не обязано ускорять запись.', 'Общая PostgreSQL ограничивает масштабирование; увеличение её CPU-квоты', 'проверяется как отдельное улучшение при тех же API, LB и запросах.', '', 'Каждый прогон: 5 секунд прогрева, затем 20 секунд измерения. Три повтора.', 'POST текстового сообщения, уникальный ключ, постоянные HTTP-соединения, без retry.', 'Генератор: стандартный http.client, по одному независимому постоянному', 'соединению на поток. Closed loop; bootstrap вне измерений; новый чат на прогон.', 'Размер текста 18 ASCII code points. Перцентили только успешных запросов.', 'RPS включает время завершения последних измеренных запросов.', '', 'Fixed: суммарно API 1 CPU / 512 MiB, делится на 1/2/4 процесса.', 'Growing: каждой API 0.5 CPU / 256 MiB. В обеих сериях DB .25 CPU / 512 MiB,', 'LB .5 CPU / 128 MiB, пул по 4 соединения на API.', 'Суммарный серверный бюджет fixed: 1.75 CPU / 1152 MiB, плюс неизменный', 'генератор 2 CPU / 512 MiB. Число возможных DB-соединений растёт с N.', 'В improved меняется только DB CPU .25→1; API 4×.5 CPU / 256 MiB. Увеличение CPU БД —', 'улучшение распределения ресурсов, а не оптимизация SQL при том же бюджете.', '', '## Исходные измерения и агрегирование', '', f'Завершённых прогонов в основной серии: **{len(raw)}**. ' 'Для каждой строки показана медиана трёх run-level результатов; диапазон — min/max RPS.', 'Ошибки суммируются по всем повторам, поэтому не скрываются медианой.', '', '| Серия | API | Конкуренция | Медиана RPS [min; max] | Ошибки / попытки | p50 / p95 / p99, ms |', '| --- | ---: | ---: | ---: | ---: | ---: |'] for r in rows: latency = r['median_success_latency_ms'] lines.append('| %s | %d | %d | %.3f [%.3f; %.3f] | %d / %d | %.3f / %.3f / %.3f |' % ( labels[r['series']], r['replicas'], r['concurrency'], r['median_rps'], r['min_rps'], r['max_rps'], r['failed_requests_total'], r['attempts_total'], latency['p50'], latency['p95'], latency['p99'])) lines += ['', '![Масштабирование API](evidence/scaling/scaling.png)', '', '![Насыщение общей зависимости](evidence/scaling/saturation.png)', '', '## Ресурсы', '', 'Docker stats CPU: 100% = один CPU. Сэмплы охватывают bootstrap, прогрев', 'и измерение; среднее не взвешено по времени. API — значение одной реплики,', 'не сумма всех API. RAM — максимальный наблюдавшийся Docker MemUsage', 'одного контейнера. Это наблюдения, а не замена квот из inspect.', '', '| Серия / N / C | CPU API mean/max, % | CPU DB mean/max, % | CPU LB mean/max, % | RAM API/DB/LB max, MiB |', '| --- | ---: | ---: | ---: | ---: |'] for r in rows: def cpu(service): v = r['sampled_cpu_percent_one_core'].get(service) return 'нет сэмпла' if not v else '%.2f / %.2f' % (v['mean'], v['max']) ram = r['sampled_ram_mib_max_per_container'] lines.append('| %s / %d / %d | %s | %s | %s | %s |' % ( labels[r['series']], r['replicas'], r['concurrency'], cpu('api'), cpu('db'), cpu('lb'), ' / '.join(str(ram.get(s, 'нет сэмпла')) for s in ('api', 'db', 'lb')))) base = next(r for r in rows if r['series'] == 'growing' and r['replicas'] == 4) improved = next(r for r in rows if r['series'] == 'db-improved') ratio = improved['median_rps'] / base['median_rps'] lines += ['', '## Проверка улучшения', '', 'При тех же четырёх API, конкуренции 32 и пуле 4 увеличение только CPU БД', 'с .25 до 1 изменило медианный successful throughput с **%.3f** до **%.3f RPS**: ' '**%.3f× (%+.1f%%)**.' % (base['median_rps'], improved['median_rps'], ratio, (ratio - 1) * 100), 'p95 успешных запросов: **%.3f → %.3f ms**. Ошибки по трём повторам: **%d → %d**.' % ( base['median_success_latency_ms']['p95'], improved['median_success_latency_ms']['p95'], base['failed_requests_total'], improved['failed_requests_total']), '', 'Это контролируемое сравнение одного параметра. Его нельзя переносить', 'на произвольное оборудование или считать доказательством линейной масштабируемости.', ''] pool_one = next((r for r in rows if r['series'] == 'pool-one'), None) if pool_one: control = next(r for r in rows if r['series'] == 'pool-four') lines += ['### Контроль размера пула', '', 'При DB .25 CPU и тех же 4 API, бюджете CPU/RAM и конкуренции 32', 'изменён только максимум соединений на API: 4→1. Условия чередовались', '4/1/4/1/4/1, по три повтора, чтобы уменьшить влияние временного дрейфа.', 'Медиана throughput: **%.3f → %.3f RPS**, отношение **%.3f×**.' % ( control['median_rps'], pool_one['median_rps'], pool_one['median_rps'] / control['median_rps']), 'p95: **%.3f → %.3f ms**; ошибок **%d → %d**.' % ( control['median_success_latency_ms']['p95'], pool_one['median_success_latency_ms']['p95'], control['failed_requests_total'], pool_one['failed_requests_total']), 'Это проверка настройки пула, а не изменение API-контракта или надёжности COMMIT.', ''] paired = [] for repeat in range(1, 4): a = next(r for r in raw if r['series'] == 'pool-four' and r['repeat'] == repeat) b = next(r for r in raw if r['series'] == 'pool-one' and r['repeat'] == repeat) paired.append('%.3f×' % (b['successful_rps'] / a['successful_rps'])) lines += ['Отношение RPS pool=1/pool=4 в трёх последовательных парах: ' + ', '.join(paired) + '.', ''] lines += ['![Парный контроль пула](evidence/scaling/pool.png)', ''] back = next(r for r in rows if r['series'] == 'saturation-baseline' and r['concurrency'] == 32) lines += ['### Обратная проверка гипотезы о CPU', '', 'После возврата DB к .25 CPU в отдельной серии C=32 наблюдалось **%.3f RPS**,' % back['median_rps'], 'тогда как в серии DB 1 CPU — **%.3f RPS**. Первоначальное увеличение CPU' % improved['median_rps'], 'проверяется этим возвратом, а не только одной лучшей попыткой.', ''] if back['median_rps'] >= .9 * improved['median_rps']: lines += ['Возврат к меньшему CPU почти не снижает throughput: гипотеза о CPU', 'как единственной причине не подтверждена устойчиво. Нужен другой', 'контролируемый опыт; одна разница медиан не доказывает улучшение.', ''] else: lines += ['После возврата меньшей CPU-квоты throughput снова снизился.', 'Вместе с контролем остальных ресурсов это поддерживает влияние', 'общей БД на наблюдаемую ёмкость. Это вывод для данного профиля,', 'не утверждение, что DB CPU — единственное ограничение при любых настройках.', ''] lines += ['### Наблюдение за общей зависимостью', '', '| Настройка БД | CPU time на вставленное сообщение, µs | Throttled periods / все periods |', '| --- | ---: | ---: |'] for series, label in [('growing', '0.25 CPU, 4 API'), ('db-improved', '1 CPU, 4 API')]: usage, messages, periods, throttled = 0, 0, 0, 0 for run in raw: if run['series'] != series or run['replicas'] != 4: continue resource = json.loads((path / (run['name'] + '.resources.json')).read_text(encoding='utf-8')) a, b = resource['dataset_before'], resource['dataset_after'] if 'db_cgroup_cpu_stat' not in a: continue usage += b['db_cgroup_cpu_stat']['usage_usec'] - a['db_cgroup_cpu_stat']['usage_usec'] periods += b['db_cgroup_cpu_stat']['nr_periods'] - a['db_cgroup_cpu_stat']['nr_periods'] throttled += b['db_cgroup_cpu_stat']['nr_throttled'] - a['db_cgroup_cpu_stat']['nr_throttled'] messages += b['messages'] - a['messages'] if messages and periods: lines.append('| %s | %.3f | %d / %d (%.2f%%) |' % ( label, usage / messages, throttled, periods, 100 * throttled / periods)) lines += ['', 'Счётчики cgroup охватывают bootstrap/прогрев/измерение и служебные проверки;', 'это диагностическое приближение, не чистая стоимость одной SQL-операции.', ''] for series in ('saturation-baseline', 'saturation-improved'): sweep = sorted((r for r in rows if r['series'] == series), key=lambda r: r['concurrency']) maximum = max(r['median_rps'] for r in sweep) knee = next(r for r in sweep if r['median_rps'] >= .9 * maximum) lines += ['### ' + labels[series], '', 'Рабочее определение наблюдаемого насыщения: наименьшая проверенная', 'конкуренция, достигшая 90% наибольшей медианы RPS в данной сетке.', 'По этому критерию: **C=%d**, медиана **%.3f RPS**, максимум в сетке **%.3f RPS**.' % ( knee['concurrency'], knee['median_rps'], maximum), 'Это оценка по дискретной сетке, а не точная физическая граница.', ''] before = min(json.loads((path / (r['name'] + '.resources.json')).read_text(encoding='utf-8'))['dataset_before']['messages'] for r in raw) after = max(json.loads((path / (r['name'] + '.resources.json')).read_text(encoding='utf-8'))['dataset_after']['messages'] for r in raw) lines += ['## Данные, воспроизводимость и ограничения', '', f'Общий набор сообщений БД за серию вырос примерно с {before} до {after}.', 'Точные users/chats/messages/sessions до и после каждого прогона — в', '`*.resources.json`; данные прогрева остаются в БД. Начальная история каждого', 'нового чата пустая. Порядок серий последовательный, без рандомизации;', 'рост индексов и прогрев cache могут влиять на сравнение.', '', 'Серия возобновлялась после остановки Docker: 11 завершённых прогонов', 'сохранены, недостающие выполнены с --resume. Перерыв между прогонами', 'мог изменить состояние cache/температуру host; внутри измеренного прогона', 'перезапуск Docker не выполнялся. Это дополнительное ограничение сравнения.', '', 'Raw `*.jsonl` хранит старт запроса, latency, status и alias. Credentials,', 'Bearer и body не записываются. `*.json` содержит итог отдельного прогона,', '`*.resources.json` — реальные квоты, container ID, CPU/RAM и объём данных.', 'sampling_error означает пропущенный telemetry sample при исчезновении', 'одноразового/заменяемого контейнера; это не нулевое потребление ресурса.', '', 'CPU/RAM клиента также записаны в raw resources; клиент имеет лимит 2 CPU /', '512 MiB и может стать ограничением. Closed loop имеет coordinated omission.', 'Неизолированный host, короткие прогоны и три повтора не дают доверительного', 'интервала для production SLA. Ошибки и timeouts не входят в успешные', 'latency-перцентили; successful RPS — подтверждения HTTP, не точный счётчик COMMIT.', '', 'Увеличение реплик не устраняет единственные DB, LB, диск и Docker-host как SPOF.', 'Исследование касается отказа API-процесса и локального масштабирования,', 'а не отказоустойчивости к потере узла.', '', '## Почему предварительные опыты не смешаны с основными', '', 'В предварительной серии использовался общий async HTTPX-клиент. Проверка', 'другим генератором на том же стенде показала 270.793 вместо 61.529 RPS.', 'Поэтому прежние низкие значения не приняты за saturation point сервера:', 'вся основная серия полностью повторена текущим независимым генератором.', 'Это диагностический контроль, не универсальное утверждение о HTTPX.', 'Предварительные 57 опытов, включая отрицательные настройки пула и LB,', 'сохранены отдельно: [архив и пояснения](evidence/exploratory-httpx/README.md).', 'Причины внутри библиотеки не профилировались. Их нельзя приписывать БД.', '', 'Перестроить числовое приложение и графики без повторной нагрузки:', '', '```sh', 'docker compose run --rm -T tester python scripts/plot_results.py', 'python3 scripts/write_research.py', '```', ''] (ROOT / 'RESEARCH.md').write_text('\n'.join(lines), encoding='utf-8') print('Wrote RESEARCH.md from', len(raw), 'measured runs; DB CPU RPS ratio:', round(ratio, 3)) if __name__ == '__main__': main()