benchs

docs/index.rst

@@ -64,6 +64,7 @@ Argenta предназначена для создания приложений,
 
     root/contributing
     root/code_of_conduct
+    root/metrics
 
 .. toctree::
     :hidden:

docs/root/metrics.rst

@@ -0,0 +1,181 @@
+Метрики
+=======
+
+Система метрик ``Argenta`` предоставляет инструменты для измерения производительности ключевых компонентов библиотеки. Это позволяет отслеживать регрессию/прогрессию производительности между релизами и оптимизировать критические участки кода.
+
+-----
+
+Запуск метрик
+-------------
+
+Для работы с метриками необходимо склонировать репозиторий и установить зависимости:
+
+.. code-block:: bash
+
+   git clone https://github.com/koloideal/Argenta.git
+   cd Argenta
+   uv sync --group metrics
+
+Запуск системы метрик:
+
+.. code-block:: bash
+
+   python -m metrics
+
+После запуска откроется интерактивная сессия с доступными командами для работы с бенчмарками.
+
+-----
+
+Доступные команды
+-----------------
+
+run-all
+~~~~~~~
+
+Запускает все зарегистрированные бенчмарки и выводит результаты в виде таблиц.
+
+**Синтаксис:**
+
+.. code-block:: shell
+
+   run-all [--without-gc] [--without-system-info]
+
+**Флаги:**
+
+- ``--without-gc`` — отключает сборщик мусора во время выполнения бенчмарков для более стабильных результатов
+- ``--without-system-info`` — скрывает информацию о системе в выводе
+
+-----
+
+list-types
+~~~~~~~~~~
+
+Выводит список всех доступных типов бенчмарков с количеством тестов в каждой категории.
+
+**Синтаксис:**
+
+.. code-block:: shell
+
+   list-types
+
+**Пример вывода:**
+
+.. code-block:: text
+
+   Available benchmark types:
+
+     • flag_validation (9 benchmarks)
+     • input_command_parse (7 benchmarks)
+     • finds_appropriate_handler (5 benchmarks)
+
+-----
+
+run-type
+~~~~~~~~
+
+Запускает бенчмарки определённого типа.
+
+**Синтаксис:**
+
+.. code-block:: shell
+
+   run-type --type <type_name> [--without-gc] [--without-system-info]
+
+**Флаги:**
+
+- ``--type`` — тип бенчмарков для запуска (обязательный)
+- ``--without-gc`` — отключает сборщик мусора
+- ``--without-system-info`` — скрывает информацию о системе
+
+-----
+
+diagrams-generate
+~~~~~~~~~~~~~~~~~
+
+Генерирует визуальные диаграммы сравнения производительности для всех бенчмарков.
+
+**Синтаксис:**
+
+.. code-block:: shell
+
+   diagrams-generate [--iterations <number>] [--without-gc]
+
+**Флаги:**
+
+- ``--iterations`` — количество итераций для каждого бенчмарка (по умолчанию 100)
+- ``--without-gc`` — отключает сборщик мусора
+
+Диаграммы сохраняются в директорию ``metrics/reports/diagrams/<timestamp>/``.
+
+-----
+
+release-generate
+~~~~~~~~~~~~~~~~
+
+Генерирует полный отчёт о производительности для текущей версии библиотеки. Используется при подготовке релизов.
+
+**Синтаксис:**
+
+.. code-block:: shell
+
+   release-generate
+
+Команда автоматически:
+
+1. Определяет текущую версию библиотеки
+2. Запускает все бенчмарки с 1000 итераций и отключённым GC
+3. Генерирует JSON-отчёты и диаграммы сравнения
+4. Сохраняет результаты в ``metrics/reports/releases/<version>/``
+
+-----
+
+Интерпретация результатов
+-------------------------
+
+Результаты бенчмарков включают следующие метрики:
+
+**Среднее время (mean)**
+  Среднее время выполнения операции. Основная метрика для сравнения производительности.
+
+**Медиана (median)**
+  Медианное значение времени выполнения. Менее чувствительна к выбросам, чем среднее.
+
+**Стандартное отклонение (std)**
+  Показывает стабильность измерений. Меньшее значение означает более предсказуемую производительность.
+
+-----
+
+Рекомендации по использованию
+------------------------------
+
+**Для оптимизации**
+  Используйте ``run-type`` для фокусировки на конкретной области и ``--without-gc`` для более точных измерений.
+
+**Для визуализации**
+  Команда ``diagrams-generate`` создаёт наглядные графики, удобные для презентаций и документации.
+
+**Для стабильных результатов**
+  Закройте ресурсоёмкие приложения, используйте флаг ``--without-gc`` и увеличивайте количество итераций через ``--iterations``.
+
+-----
+
+Добавление новых бенчмарков
+----------------------------
+
+Вы можете реализовать свои бенчмарки для тестирования специфичных юнитов библиотеки. Новые бенчмарки добавляются через декоратор ``@benchmarks.register``:
+
+.. code-block:: python
+
+   from metrics.benchmarks.entity import benchmarks
+
+   @benchmarks.register(
+       type_="my_category",
+       description="Description of what is being measured"
+   )
+   def benchmark_my_operation() -> None:
+       # Код, производительность которого измеряется
+       pass
+
+.. important::
+
+  Бенчмарк должен быть импортирован в ``metrics/benchmarks/__init__.py`` для автоматической регистрации.