Метрики
=======

Система метрик ``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`` для автоматической регистрации.