Пороги & Оповещения

Пороги помогают фиксировать ухудшения производительности с Bencher. Порог назначается уникальной комбинации: ветка, тестовый стенд и показатель. Порог использует конкретный тест для обнаружения ухудшений производительности. Комбинация теста и его параметров называется моделью. Модель должна иметь нижнюю границу, верхнюю границу или обе.

• Нижняя граница
  • Нижняя граница используется, когда меньшее значение указывает на ухудшение производительности, например, с показателем пропускной способности.
• Верхняя граница
  • Верхняя граница используется, когда большее значение указывает на ухудшение производительности, например, с показателем задержки.

Каждая граница используется для расчета предельного значения границы. Затем каждый новый метрика проверяется на соответствие каждому предельному значению границы. Оповещение создается, когда новая метрика ниже предельного значения нижней границы или выше предельного значения верхней границы.

При [непрерывном тестировании производительности] (то есть при тестировании в CI) вам нужно будет создать пороги. Используя подкоманду CLI bencher run, вы уже указываете ветку с опцией --branch и тестовый стенд с опцией --testbed. Таким образом, единственное измерение, которое вам нужно указать, — это показатель с опцией --threshold-measure. Затем вы можете использовать опцию --threshold-test для указания теста, который будет использоваться для этого показателя. Опции --threshold-min-sample-size, --threshold-max-sample-size и --threshold-window позволяют вам контролировать, какие данные используются в тесте. Наконец, опции --threshold-lower-boundary и --threshold-upper-boundary позволяют вам установить нижнюю и верхнюю границы. Если вы хотите удалить все модели, которые не указаны, вы можете сделать это с помощью флага --thresholds-reset.

• Если порог не существует, он будет создан для вас.
• Если порог существует, и указанная модель та же, то модель игнорируется.
• Если порог существует, и указанная модель другая, тогда для порога создается новая модель.
• Если порог существует и сброшен, текущая модель удаляется из порога.

Например, чтобы использовать только порог для показателя задержки, используя тест Стьюдента с максимальным размером выборки 64 и верхней границей 0.99, вы можете написать что-то подобное:

bencher run \
--project save-walter-white-1234abcd \
--branch main \
--testbed localhost \
--threshold-measure latency \
--threshold-test t_test \
--threshold-max-sample-size 64 \
--threshold-upper-boundary 0.99 \
--thresholds-reset \
--err \
--adapter json \
bencher mock

🐰 При работе с функциональными ветками вы можете захотеть скопировать существующие пороги из базовой, начальной ветки. Это возможно с помощью флага --start-point-clone-thresholds. Обратите внимание, что флаг --thresholds-reset все равно удалит все склонированные пороги, которые не указаны явно.

Несколько порогов

Возможно создать несколько порогов с одним вызовом bencher run. При указании нескольких порогов обязательно использовать одинаковые параметры для каждого порога. Чтобы игнорировать параметр для конкретного порога, используйте подчеркивание (_).

Например, если вы хотите использовать только два порога, один для измерения задержки и другой для измерения пропускной способности, то, вероятно, вы захотите установить верхнюю границу для измерения задержки и нижнюю границу для измерения пропускной способности. Поэтому вы будете использовать --threshold-lower-boundary _ для измерения задержки и --threshold-upper-boundary _ для измерения пропускной способности. Это можно записать следующим образом:

bencher run \
--project save-walter-white-1234abcd \
--branch main \
--testbed localhost \
--threshold-measure latency \
--threshold-test t_test \
--threshold-max-sample-size 64 \
--threshold-lower-boundary _ \
--threshold-upper-boundary 0.99 \
--threshold-measure throughput \
--threshold-test t_test \
--threshold-max-sample-size 64 \
--threshold-lower-boundary 0.99 \
--threshold-upper-boundary _ \
--thresholds-reset \
--err \
--adapter json \
bencher mock --measure latency --measure throughput

--threshold-measure <MEASURE>

Используйте указанное Measure имя, слаг или UUID для порога. Если указанное значение представляет собой имя или слаг и Measure еще не существует, оно будет создано для вас. Однако, если указанное значение является UUID, то Measure уже должен существовать.

Например, чтобы использовать порог для Measure задержки, вы могли бы написать --threshold-measure latency.

--threshold-test <TEST>

Используйте указанный тест для обнаружения регрессий производительности.

Доступно несколько различных тестов:

• Static (static)
• Percentage (percentage)
• z-score (z_score)
• t-test (t_test)
• Log Normal (log_normal)
• Interquartile Range (iqr)
• Delta Interquartile Range (delta_iqr)

Например, чтобы использовать порог с t-тестом Стьюдента, вы можете написать --threshold-test t_test.

Статический

Статический тест (static) является самым простым тестом. Если новая метрика ниже установленной нижней границы или выше установленной верхней границы, генерируется оповещение. То есть, нижняя/верхняя граница является явным ограничением нижней/верхней границы. Должна быть установлена либо нижняя граница, верхняя граница, либо обе границы. Статические тесты лучше всего работают, когда значение метрики должно оставаться в постоянном диапазоне по всем эталонам, таким как покрытие кода.

• Статическая нижняя граница

  • Статическая нижняя граница теста может быть любым числом с плавающей запятой. Она используется, когда меньшее значение указывало бы на регрессию производительности. Нижняя граница должна быть меньше или равна верхней границе, если обе указаны.
  • Например, если у вас есть статический тест с нижней границей, установленной на 100, тогда нижнее ограничение будет также 100, и любое значение меньше 100 будет генерировать оповещение.

• Статическая верхняя граница

  • Статическая верхняя граница теста может быть любым числом с плавающей запятой. Она используется, когда большее значение указывало бы на регрессию производительности. Верхняя граница должна быть больше или равна нижней границе, если обе указаны.
  • Например, если у вас есть статический тест с верхней границей, установленной на 100, тогда верхнее ограничение будет также 100, и любое значение больше 100 будет генерировать оповещение.

Процент

Тест на процентное соотношение (percentage) — это самый простой статистический тест. Если новая метрика ниже определенного процента от среднего значения (Нижняя Граница) или выше определенного процента от среднего значения (Верхняя Граница) ваших исторических метрик, срабатывает оповещение. Необходимо задать либо Нижнюю Границу, либо Верхнюю Границу, либо обе. Тесты на процентное соотношение работают лучше всего, когда значение метрики должно оставаться в пределах известного допустимого диапазона.

• Нижняя граница процента

  • Нижняя граница теста на процентное соотношение может быть любым процентом, равным или большим нуля в десятичной форме (например, использовать 0,10 для 10%). Она используется, когда меньшее значение будет указывать на ухудшение производительности.
  • Например, если у вас есть тест на процентное соотношение с Нижней Границей, установленной на 0,10, а среднее значение ваших исторических метрик равно 100, предел нижней границы будет 90, и любое значение меньше 90 вызовет срабатывание оповещения.

• Верхняя граница процента

  • Верхняя граница теста на процентное соотношение может быть любым процентом, равным или большим нуля в десятичной форме (например, использовать 0,10 для 10%). Она используется, когда большее значение будет указывать на ухудшение производительности.
  • Например, если у вас есть тест на процентное соотношение с Верхней Границей, установленной на 0,10, а среднее значение ваших исторических метрик равно 100, предел верхней границы будет 110, и любое значение больше 110 вызовет срабатывание оповещения.

z-score

Тест z-score (z_score) измеряет количество стандартных отклонений (σ), на которое новая метрика отличается от среднего значения ваших исторических метрик, используя z-score.

Тесты z-score работают лучше всего, когда:

• Нет экстремальных различий между эталонными запусками
• Эталонные запуски полностью независимы друг от друга
• Количество итераций для одного эталонного запуска составляет менее 10% от исторических метрик
• Есть как минимум 30 исторических метрик (минимальный размер выборки >= 30)

Для тестов z-score стандартные отклонения выражаются в виде десятичного накопительного процента. Если новая метрика оказывается ниже определенного левого накопительного процента (нижняя граница) или выше определенного правого накопительного процента (верхняя граница) ваших исторических метрик, генерируется предупреждение. Должна быть установлена либо нижняя граница, либо верхняя граница, либо обе.

• Нижняя граница z-score

  • Нижняя граница теста z-score может быть любым положительным десятичным числом между 0.5 и 1.0. Где 0.5 представляет среднее значение, а 1.0 — все возможные левые значения (-∞). Она используется, когда меньшее значение указывает на регрессию производительности.
  • Например, если вы использовали тест z-score с нижней границей 0.977 и ваши исторические метрики имели среднее 100 и стандартное отклонение 10, предел нижней границы составил бы 80.05, и любое значение менее 80.05 генерировало бы предупреждение.

• Верхняя граница z-score

  • Верхняя граница теста z-score может быть любым положительным десятичным числом между 0.5 и 1.0. Где 0.5 представляет среднее значение, а 1.0 — все возможные правые значения (∞). Она используется, когда большее значение указывает на регрессию производительности.
  • Например, если вы использовали тест z-score с верхней границей 0.977 и ваши исторические метрики имели среднее 100 и стандартное отклонение 10, предел верхней границы составил бы 119.95, и любое значение больше 119.95 генерировало бы предупреждение.

t-test

Т-тест (t_test) измеряет доверительный интервал (CI) для вероятности того, что новая Метрика выше или ниже среднего ваших исторических Метрик, используя т-тест Стьюдента.

Тесты т-теста лучше всего работают, когда:

• Нет резких различий между контрольными запусками
• Контрольные запуски полностью независимы друг от друга
• Число итераций для одного контрольного запуска составляет менее 10% от исторических Метрик

Для тестов т-теста доверительные интервалы выражаются в виде десятичной процента уверенности. Если новая Метрика ниже определенной левой границы доверия (Нижняя Граница) или выше определенной правой границы доверия (Верхняя Граница) для ваших исторических Метрик, генерируется Оповещение. Должна быть установлена хотя бы одна из границ: Нижняя, Верхняя или обе.

• t-test Нижняя Граница

  • Нижняя Граница теста т-теста может быть любым положительным десятичным числом между 0.5 и 1.0. Где 0.5 представляет среднее значение, а 1.0 — все возможные значения с левой стороны (-∞). Используется, когда меньшее значение указывает на ухудшение производительности.
  • Например, если вы использовали тест т-теста с Нижней Границей 0.977 и у вас было 25 исторических Метрик со средним 100 и стандартным отклонением 10, лимит Нижней Границы составил бы 78.96, и любое значение меньше 78.96 вызвало бы Оповещение.

• t-test Верхняя Граница

  • Верхняя Граница теста т-теста может быть любым положительным десятичным числом между 0.5 и 1.0. Где 0.5 представляет среднее значение, а 1.0 — все возможные значения с правой стороны (∞). Используется, когда большее значение указывает на ухудшение производительности.
  • Например, если вы использовали тест т-теста с Верхней Границей 0.977 и у вас было 25 исторических Метрик со средним 100 и стандартным отклонением 10, лимит Верхней Границы составил бы 121.04, и любое значение больше 121.04 вызвало бы Оповещение.

Лог-нормальное распределение

Тест на лог-нормальное распределение (log_normal) измеряет, насколько вероятно, что новая метрика выше или ниже центрального положения ваших исторических метрик, используя лог-нормальное распределение.

Тесты на лог-нормальное распределение лучше всего работают, когда:

• Запуски эталонов полностью независимы друг от друга
• Количество итераций для одного запуска эталона составляет менее 10% от исторических метрик
• Все данные положительные (натуральный логарифм отрицательного числа неопределен)

Для тестов на лог-нормальное распределение вероятность выражается в виде десятичного процента. Если новая метрика ниже определенного процентного значения слева (нижняя граница) или выше определенного процентного значения справа (верхняя граница) для ваших исторических метрик, генерируется предупреждение. Должна быть установлена либо нижняя граница, верхняя граница, либо обе.

• Нижняя граница лог-нормального распределения

  • Нижняя граница теста на лог-нормальное распределение может быть любым положительным десятичным значением между 0.5 и 1.0. Где 0.5 представляет центральное положение, а 1.0 — все возможные значения слева (-∞). Она используется, когда меньшее значение будет указывать на ухудшение производительности.
  • Например, если вы использовали тест на лог-нормальное распределение с нижней границей 0.977, и у вас было 25 исторических метрик, сосредоточенных вокруг 100, и один предыдущий выброс на 200, граница нижнего предела составила бы 71.20, и любое значение меньше 71.20 вызовет предупреждение.

• Верхняя граница лог-нормального распределения

  • Верхняя граница теста на лог-нормальное распределение может быть любым положительным десятичным значением между 0.5 и 1.0. Где 0.5 представляет центральное положение, а 1.0 — все возможные значения справа (∞). Она используется, когда большее значение будет указывать на ухудшение производительности.
  • Например, если вы использовали тест на лог-нормальное распределение с верхней границей 0.977, и у вас было 25 исторических метрик, сосредоточенных вокруг 100, и один предыдущий выброс на 200, граница верхнего предела составила бы 134.18, и любое значение больше 134.18 вызовет предупреждение.

Межквартильный диапазон

Тест на межквартильный диапазон (iqr) измеряет, сколько крат межквартильного диапазона (IQR) новый показатель превышает или ниже медианы ваших исторических показателей. Если новый показатель ниже определенного числа IQR от медианы (Нижняя граница) или выше определенного числа IQR от медианы (Верхняя граница) ваших исторических показателей, создается предупреждение. Необходимо задать либо Нижнюю границу, либо Верхнюю границу, либо обе.

• Нижняя граница межквартильного диапазона

  • Нижняя граница теста на межквартильный диапазон может быть любым множителем, большим или равным нулю (например, используйте 2.0 для 2x). Используется, когда меньшее значение указывает на регрессию производительности.
  • Например, если у вас есть тест на межквартильный диапазон с нижней границей, установленной на 2.0, и ваши исторические показатели имеют медиану 100 и межквартильный диапазон 10, нижний предельный лимит будет 80, и любое значение меньше 80 вызовет предупреждение.

• Верхняя граница межквартильного диапазона

  • Верхняя граница теста на межквартильный диапазон может быть любым множителем, большим или равным нулю (например, используйте 2.0 для 2x). Используется, когда большее значение указывает на регрессию производительности.
  • Например, если у вас есть тест на межквартильный диапазон с верхней границей, установленной на 2.0, и ваши исторические показатели имеют медиану 100 и межквартильный диапазон 10, верхний предельный лимит будет 120, и любое значение больше 120 вызовет предупреждение.

Delta Interquartile Range

Тест Дельта Межквартильного Размаха (delta_iqr) измеряет, во сколько раз новый показатель выше или ниже медианы ваших исторических показателей, используя среднее значение изменения процента (Δ) межквартильного размаха (IQR). Если новый показатель находится ниже определенного множителя ΔIQR от медианы (Нижняя Граница) или выше определенного множителя ΔIQR от медианы (Верхняя Граница) ваших исторических показателей, генерируется предупреждение. Необходимо установить либо Нижнюю Границу, либо Верхнюю Границу, либо обе.

• Нижняя Граница Дельта Межквартильного Размаха

  • Нижняя Граница Теста Дельта Межквартильного Размаха может быть любым множителем, равным или большим нуля (например, используйте 2.0 для 2x). Она используется, когда меньшее значение указывает на регресс производительности.
  • Например, если у вас был тест Дельта Межквартильного Размаха с установленной Нижней Границей 2.0, и ваши исторические показатели имели медиану 100, межквартильный размах 10, и средний дельта межквартильный размах 0.2 (20%), то Предел Нижней Границы будет 60, и любое значение меньше 60 будет генерировать предупреждение.

• Верхняя Граница Дельта Межквартильного Размаха

  • Верхняя Граница Теста Дельта Межквартильного Размаха может быть любым множителем, равным или большим нуля (например, используйте 2.0 для 2x). Она используется, когда большее значение указывает на регресс производительности.
  • Например, если у вас был тест Дельта Межквартильного Размаха с установленной Верхней Границей 2.0, и ваши исторические показатели имели медиану 100, межквартильный размах 10, и средний дельта межквартильный размах 0.2 (20%), то Предел Верхней Границы будет 140, и любое значение больше 140 будет генерировать предупреждение.

--threshold-min-sample-size <SAMPLE_SIZE>

При необходимости укажите минимальное количество метрик, требуемое для запуска теста. Если это минимальное количество не будет достигнуто, тест не запустится. Указанный размер выборки должен быть больше или равен 2. Если установлен также параметр --threshold-max-sample-size, то указанный размер выборки должен быть меньше или равен значению --threshold-max-sample-size. Этот параметр не может использоваться с статическим (static) тестом.

Например, чтобы использовать порог с минимальным размером выборки 10, вы можете написать --threshold-min-sample-size 10. Если метрик будет меньше чем 10, тест не запустится. Напротив, если метрик будет 10 или больше, тест будет выполнен.

--threshold-max-sample-size <SAMPLE_SIZE>

При необходимости укажите максимальное количество Метрик, используемых для проведения Теста. Если это количество превышено, самые старые Метрики будут игнорироваться. Указанный размер выборки должен быть больше или равен 2. Если также задана опция --threshold-min-sample-size, то указанный размер выборки должен быть больше или равен значению --threshold-min-sample-size. Эта опция не может использоваться с Статическим (static) Тестом.

Например, чтобы использовать Порог с максимальным размером выборки 100, можно написать --threshold-max-sample-size 100. Если бы было больше чем 100 Метрик, были бы включены только самые последние 100 Метрик. Наоборот, если бы Метрик было 100 или меньше, все Метрики были бы включены.

--threshold-window <WINDOW>

При необходимости укажите временной интервал для метрик, используемый для выполнения теста, в секундах. Указанное окно должно быть больше 0. Эта опция не может использоваться с статическим (static) тестом.

Например, чтобы использовать порог с интервалом в четыре недели или 2419200 секунд, можно указать --threshold-window 2419200. Если существуют какие-либо метрики, которые старше четырех недель, они будут исключены. Наоборот, если все метрики находятся в пределах последних четырех недель, они будут включены.

--threshold-lower-boundary <BOUNDARY>

Укажите нижнюю границу. Ограничения на нижнюю границу зависят от используемого теста. Либо нижняя граница, верхняя граница, либо обе должны быть указаны.

Для деталей смотрите документацию по конкретному тесту, который вы используете:

• Статическая нижняя граница
• Процентная нижняя граница
• Нижняя граница по z-оценке
• Нижняя граница по t-тесту
• Нижняя граница логнормального распределения
• Нижняя граница межквартильного размаха
• Нижняя граница дельта межквартильного размаха

--threshold-upper-boundary <BOUNDARY>

Укажите Верхнюю Границу. Ограничения на Верхнюю Границу зависят от используемого Теста. Необходимо указать либо Нижнюю Границу, либо Верхнюю Границу, либо обе.

Для получения подробной информации ознакомьтесь с документацией по конкретному используемому Тесту:

• Статическая Верхняя Граница
• Процентная Верхняя Граница
• z-оценка Верхняя Граница
• t-тест Верхняя Граница
• Логнормальная Верхняя Граница
• Интерквартильный Размах Верхняя Граница
• Дельта Интерквартильный Размах Верхняя Граница

---thresholds-reset

Сбросьте все неуказанные Пороги для данного Ветки и Тестового окружения. Если Порог уже существует и не указан, его текущая Модель будет удалена.

Например, если для Ветки main и Тестового окружения localhost было два Порога:

• Ветка main, Тестовое окружение localhost, latency Мера
• Ветка main, Тестовое окружение localhost, throughput Мера

Если указана только Мера latency в подкоманде bencher run и используется --thresholds-reset, тогда Мера throughput будет очищена от своей Модели.

--err

При необходимости генерирует ошибку при создании оповещения. Оповещение создается, когда новая метрика находится ниже нижнего предела или выше верхнего предела.

Подавление оповещений

Иногда бывает полезно подавлять оповещения для определенного эталона. Лучший способ сделать это — добавить один из этих специальных суффиксов к имени данного эталона:

• _bencher_ignore
• BencherIgnore
• -bencher-ignore

Например, если ваш эталон называется my_flaky_benchmark, то переименование его в my_flaky_benchmark_bencher_ignore позволит игнорировать именно этот эталон в будущем. Игнорируемые эталоны всё же проверяются на существующие пороговые значения. Однако для них не будет генерироваться оповещение. Метрики для игнорируемых эталонов все равно сохраняются. Результаты из my_flaky_benchmark_bencher_ignore все равно будут сохранены как эталон my_flaky_benchmark. Если убрать суффикс и вернуться к оригинальному имени эталона, то процесс продолжит с того места, где был остановлен.

🐰 Поздравляем! Вы узнали все о Порогах и Оповещениях! 🎉

Продолжайте: Адаптеры обвязки бенчмарков ➡