Параметры инициализации

pgbench принимает следующие аргументы командной строки для инициализации:

Параметры тестирования производительности

pgbench принимает следующие аргументы командной строки для тестирования производительности:

Общие параметры

Программа pgbench также принимает общие аргументы командой строки, определяющие параметры подключения:

Каково содержание «транзакции», которую выполняет pgbench?

Программа pgbench выполняет тестовые скрипты, выбирая их случайным образом из заданного списка. Это могут быть как встроенные скрипты, задаваемые аргументами -b, так и пользовательские, задаваемые аргументами -f. Для каждого скрипта можно задать относительный вес после @, чтобы скорректировать вероятность его выбора. По умолчанию вес считается равным 1. Скрипты с весом 0 игнорируются.

Стандартный встроенный скрипт (также вызываемый с ключом -b tpcb-like) выдаёт семь команд в транзакции со случайно выбранными aid, tid, bid и delta. Его сценарий написан по мотивам теста производительности TPC-B, но это не собственно TPC-B, потому он называется так.

При выборе встроенного скрипта simple-update (или указании -N) шаги 4 и 5 исключаются из транзакции. Это позволяет избежать конкуренции при обращении к этим таблицам, но тест становится ещё менее похожим на TPC-B.

При выборе встроенного теста select-only (или указании -S) выполняется только SELECT.

Пользовательские скрипты

Программа pgbench поддерживает запуск пользовательских сценариев оценки производительности, позволяя заменять стандартный скрипт транзакции (описанный выше) скриптом, считываемым из файла (с параметром -f). В этом случае «транзакцией» считается одно выполнение данного скрипта.

Файл скрипта содержит одну или несколько команд SQL, разделённых точкой с запятой. Пустые строки и строки, начинающиеся с --, игнорируются. В файлах скриптов также могут содержаться «метакоманды», которые обрабатывает сама программа pgbench, как описано ниже.

Для файлов скриптов реализован простой механизм подстановки переменных. Имя переменных должно состоять из букв (буквы могут быть не латинскими), подчёркиваний и цифр (но цифра не может быть первым символом). Переменные можно задать в командной строке параметрами -D, описанными выше, или метакомандами, рассматриваемыми ниже. Помимо переменных, которые можно установить параметрами командной строки -D, есть несколько автоматически устанавливаемых переменных; они перечислены в Таблице 293. Если значение этих переменных задаётся в параметре -D, оно переопределяет автоматическое значение. Когда значение переменной определено, его можно вставить в команду SQL, написав :имя_переменной. Каждый клиентский сеанс, если их несколько, получает собственный набор переменных. В одном операторе pgbench поддерживает до 255 ссылок на переменные.

Метакоманды в скрипте начинаются с обратной косой черты (\) и обычно продолжаются до конца строки, хотя их можно переносить на следующую строку последовательностью символов: обратная косая, возврат каретки. Аргументы метакоманд разделяются пробелами. Поддерживаемые метакоманды представлены ниже:

Встроенные операторы

Перечисленные в Таблице 294 арифметические, битовые и логические операторы, а также операторы сравнения встроены в pgbench и могут применяться в выражениях в \set. Эти операторы приведены в порядке возрастания их приоритета. Не считая явно отмеченных исключений, операторы с двумя числовыми аргументами будут выдавать результат в типе с плавающей точкой, если какой-либо аргумент имеет такой тип; в противном случае результат будет целочисленным.

Встроенные функции

Функции, перечисленные в Таблице 295, встроены в pgbench и могут применяться в выражениях в метакоманде \set.

Функция random выдаёт значения с равномерным распределением, то есть вероятности получения всех чисел в интервале равны. Функции random_exponential, random_gaussian и random_zipfian требуют указания дополнительного параметра типа double, определяющего точную форму распределения.

Функции хеширования hash, hash_murmur2 и hash_fnv1a принимают на вход хешируемое значение и необязательный параметр с затравкой. Если значение затравки не задаётся, используется значение переменной :default_seed, которая инициализируется случайным числом (если не задаётся явно ключом командной строки -D).

Функция permute принимает входное значение, размер и необязательный параметр с затравкой. Она получает псевдослучайную перестановку целых чисел в диапазоне [0, размер) и возвращает индекс входного значения в этой перестановке. Выбираемая перестановка зависит от затравки; по умолчанию затравкой будет значение :default_seed. В отличие от функций вычисления хеша, функция permute гарантирует отсутствие пропусков и наложений в выходных значениях. Входные значения, лежащие за границами интервала, пересчитываются по модулю размера. Если значение размера не положительное, эта функция выдаёт ошибку. Функцию permute можно использовать для выравнивания результатов функций, выдающих неравномерно распределённые случайные числа, таких как random_zipfian или random_exponential, чтобы чаще выдаваемые значения не создавали корреляции. Например, следующий скрипт pgbench эмулирует возможную реальную нагрузку, типичную для социальных медиа- и блог-платформ, где несколько пользователей генерируют львиную долю нагрузки:

\set size 1000000
\set r random_zipfian(1, :size, 1.07)
\set k 1 + permute(:r, :size)

В некоторых случаях требуются другие разнообразные распределения, не коррелирующие друг с другом, и тогда может быть полезно дополнительно указать затравку:

\set k1 1 + permute(:r, :size, :default_seed + 123)
\set k2 1 + permute(:r, :size, :default_seed + 321)

Примерно такого же эффекта можно добиться, используя функцию hash:

\set size 1000000
\set r random_zipfian(1, 100 * :size, 1.07)
\set k 1 + abs(hash(:r)) % :size

Но так как hash может порождать коллизии, некоторые значения окажутся пропущенными, а другие будут встречаться чаще других, при том что в исходном распределении этого не наблюдалось.

В качестве примера взгляните на встроенное определение транзакции типа TPC-B:

\set aid random(1, 100000 * :scale)
\set bid random(1, 1 * :scale)
\set tid random(1, 10 * :scale)
\set delta random(-5000, 5000)
BEGIN;
UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
END;

С таким скриптом транзакция на каждой итерации будет обращаться к разным, случайно выбираемым строкам. (Этот пример показывает, почему важно, чтобы в каждом клиентском сеансе были собственные переменные — в противном случае они не будут независимо обращаться к разным строкам.)

Протоколирование транзакций

С параметром -l (но без --aggregate-interval), pgbench записывает информацию о каждой транзакции в протокол. Этот файл протокола будет называться префикс.nnn, где префикс по умолчанию — pgbench_log, а nnn — PID процесса pgbench. Префикс можно сменить, воспользовавшись ключом --log-prefix. Если параметр -j равен 2 или выше, будет создано несколько рабочих потоков, и каждый будет записывать отдельный протокол. Первый рабочий процесс будет использовать файл с тем же именем, что и в стандартном случае с одним потоком, а файлы остальных потоков будут называться префикс.nnn.mmm, где mmm — порядковый номер рабочего процесса, начиная с 1.

Каждая строка в файле протокола описывает одну транзакцию. Она содержит следующие поля, разделённые пробелами:

Когда одновременно применяются параметры --rate и --latency-limit, в поле длительность для пропущенных транзакций выводится skipped. Если транзакция завершилась неудачей, в столбце длительность выводится failed. Когда применяется параметр --failures-detailed, вместо длительности для неуспешной транзакции будет указано serialization или deadlock в зависимости от типа ошибки (за дополнительными сведениями обратитесь к Повторы и отказы из-за ошибок сериализации/взаимоблокировки).

Фрагмент протокола, полученного при выполнении с одним клиентом:

0 199 2241 0 1175850568 995598
0 200 2465 0 1175850568 998079
0 201 2513 0 1175850569 608
0 202 2038 0 1175850569 2663

Ещё один пример с --rate=100 и --latency-limit=5 (обратите внимание на дополнительный столбец отставание_от_графика):

0 81 4621 0 1412881037 912698 3005
0 82 6173 0 1412881037 914578 4304
0 83 skipped 0 1412881037 914578 5217
0 83 skipped 0 1412881037 914578 5099
0 83 4722 0 1412881037 916203 3108
0 84 4142 0 1412881037 918023 2333
0 85 2465 0 1412881037 919759 740

В этом примере транзакция 82 опоздала, так как её длительность (6.173 мс) превысила ограничение в 5 мс. Следующие две транзакции были пропущены, так как было слишком поздно их начинать.

Ниже показан фрагмент протокола с отказами и повторными попытками при максимальном числе попыток, равном 10 (обратите внимание на дополнительный столбец повторные_попытки):

3 0 47423 0 1499414498 34501 3
3 1 8333 0 1499414498 42848 0
3 2 8358 0 1499414498 51219 0
4 0 72345 0 1499414498 59433 6
1 3 41718 0 1499414498 67879 4
1 4 8416 0 1499414498 76311 0
3 3 33235 0 1499414498 84469 3
0 0 failed 0 1499414498 84905 9
2 0 failed 0 1499414498 86248 9
3 4 8307 0 1499414498 92788 0

Если применяется параметр --failures-detailed, в графе длительность выводится тип ошибки:

3 0 47423 0 1499414498 34501 3
3 1 8333 0 1499414498 42848 0
3 2 8358 0 1499414498 51219 0
4 0 72345 0 1499414498 59433 6
1 3 41718 0 1499414498 67879 4
1 4 8416 0 1499414498 76311 0
3 3 33235 0 1499414498 84469 3
0 0 serialization 0 1499414498 84905 9
2 0 serialization 0 1499414498 86248 9
3 4 8307 0 1499414498 92788 0

Когда проводится длительное тестирование с большим количеством транзакций, файлы протоколов могут быть очень объёмными. Чтобы в них записывалась только случайная выборка транзакций, можно запустить команду с параметром --sampling-rate.

Протоколирование с агрегированием

С параметром --aggregate-interval для файлов протоколов используется другой формат. Каждая строка протокола описывает один интервал агрегации. Она содержит следующие поля, разделённые пробелами:

Ниже представлен пример вывода с этим параметром:

pgbench --aggregate-interval=10 --time=20 --client=10 --log --rate=1000 --latency-limit=10 --failures-detailed --max-tries=10 test

1650260552 5178 26171317 177284491527 1136 44462 2647617 7321113867 0 9866 64 7564 28340 4148 0
1650260562 4808 25573984 220121792172 1171 62083 3037380 9666800914 0 9998 598 7392 26621 4527 0

Заметьте, что простой формат протокола (без агрегирования) показывает, какой скрипт использовался для каждой транзакции, в отличие от формата с агрегированием. Таким образом, если вам нужны подобные сведения, но в разрезе скриптов, вам придётся агрегировать данные самостоятельно.

Отчёт по операторам

С параметром -r программа pgbench собирает следующую статистику по каждому оператору:

В отчёте отображается статистика повторов, только если параметр --max-tries не равен 1.

Все эти значения вычисляются для каждого оператора, выполняемого каждым клиентом, и выдаются после завершения теста.

Для скрипта по умолчанию вывод будет выглядеть примерно так:

starting vacuum...end.
transaction type: <builtin: TPC-B (sort of)>
scaling factor: 1
query mode: simple
number of clients: 10
number of threads: 1
maximum number of tries: 1
number of transactions per client: 1000
number of transactions actually processed: 10000/10000
number of failed transactions: 0 (0.000%)
number of transactions above the 50.0 ms latency limit: 1311/10000 (13.110 %)
latency average = 28.488 ms
latency stddev = 21.009 ms
initial connection time = 69.068 ms
tps = 346.224794 (without initial connection time)
statement latencies in milliseconds and failures:
   0.012  0  \set aid random(1, 100000 * :scale)
   0.002  0  \set bid random(1, 1 * :scale)
   0.002  0  \set tid random(1, 10 * :scale)
   0.002  0  \set delta random(-5000, 5000)
   0.319  0  BEGIN;
   0.834  0  UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
   0.641  0  SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
  11.126  0  UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
  12.961  0  UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
   0.634  0  INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
   1.957  0  END;

Ещё один пример вывода для скрипта по умолчанию с выбором сериализуемого уровня изоляции (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...):

starting vacuum...end.
transaction type: <builtin: TPC-B (sort of)>
scaling factor: 1
query mode: simple
number of clients: 10
number of threads: 1
maximum number of tries: 10
number of transactions per client: 1000
number of transactions actually processed: 6317/10000
number of failed transactions: 3683 (36.830%)
number of transactions retried: 7667 (76.670%)
total number of retries: 45339
number of transactions above the 50.0 ms latency limit: 106/6317 (1.678 %)
latency average = 17.016 ms
latency stddev = 13.283 ms
initial connection time = 45.017 ms
tps = 186.792667 (without initial connection time)
statement latencies in milliseconds, failures and retries:
  0.006     0      0  \set aid random(1, 100000 * :scale)
  0.001     0      0  \set bid random(1, 1 * :scale)
  0.001     0      0  \set tid random(1, 10 * :scale)
  0.001     0      0  \set delta random(-5000, 5000)
  0.385     0      0  BEGIN;
  0.773     0      1  UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
  0.624     0      0  SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
  1.098   320   3762  UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
  0.582  3363  41576  UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
  0.465     0      0  INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
  1.933     0      0  END;

Если задействуется несколько файлов скриптов, все статистические данные выводятся отдельно для каждого файла.

Учтите, что сбор дополнительных временных показателей влечёт некоторые издержки и приводит к снижению средней скорости и, как результат, падению TPS. На сколько именно снизится скорость, во многом зависит от платформы и оборудования. Хороший способ оценить, каковы эти издержки — сравнить средние значения TPS, получаемые с подсчётом времени операторов и без такого подсчёта.

Повторы и отказы из-за ошибок сериализации/взаимоблокировки

При выполнении pgbench могут возникать ошибки трёх основных типов:

Работа клиента прерывается в случае серьёзной ошибки; например, если было потеряно соединение с сервером баз данных или достигнут конец скрипта, а последняя транзакция не завершена. Кроме того, работа клиента прерывается, если выполнение команды SQL или метакоманды завершается сбоем по причинам, отличным от ошибок сериализации или взаимоблокировки. Если же команда SQL завершается ошибкой сериализации или взаимоблокировки, работа клиента продолжается. В таких случаях текущая транзакция откатывается, при этом клиентские переменные получают значения, которые они имели до начала этой транзакции (предполагается, что один скрипт транзакции содержит только одну транзакцию; за подробностями обратитесь к Каково содержание «транзакции», которую выполняет pgbench?). Транзакции с ошибками сериализации или взаимоблокировки повторяются после отката до успешного завершения либо до максимального числа повторений (которое задаётся параметром --max-tries), максимальной длительности повторений (которая задаётся параметром --latency-limit) или до истечения времени теста (это время задаётся параметром --time). Если последняя попытка завершается неудачей, транзакция считается неудачной, но работа клиента не прерывается.

Длительность успешной транзакции включает общее время выполнения транзакции с учётом откатов и повторов. Измеряется длительность только для успешных транзакций и команд.

Количество неуспешных транзакций выводится в основном отчёте. Если параметр --max-tries не равен 1, основной отчёт также содержит статистику повторов: общее число транзакций, которые повторялись, и общее число повторов всех транзакций. Отчёт по скриптам наследует все эти поля от основного отчёта. Если параметр --max-tries не равен 1, статистика повторных попыток также отображается в отчёте по операторам.

Если вы хотите, чтобы в протоколе c агрегированием, а также в основном отчёте, отчёте по транзакциям и отчёте по скриптам сбои группировались по базовым типам, используйте параметр --failures-detailed. Если же вы хотите видеть все отдельные ошибки и отказы (ошибки, после которых транзакция не повторяется), а также видеть, как ограничиваются повторения и насколько достигается ограничение, используйте параметр --verbose-errors.

Табличные методы доступа

Можно определить табличный метод доступа к таблицам pgbench. В переменной окружения PGOPTIONS задаются конфигурационные параметры БД, которые передаются в PostgreSQL через командную строку (см. Подраздел 20.1.4). Например, табличный метод доступа по умолчанию к таблицам, создаваемым pgbench, под названием wuzza можно определить так:

PGOPTIONS='-c default_table_access_method=wuzza'

Полезные советы

Используя pgbench, можно без особого труда получить абсолютно бессмысленные числа. Последуйте приведённым советам, чтобы получить полезные результаты.

Во-первых, никогда не доверяйте тестам, которые выполняются всего несколько секунд. Воспользуйтесь параметром -t и -T и установите время выполнения не меньше нескольких минут, чтобы избавиться от шума в средних значениях. В некоторых случаях для получения воспроизводимых результатов тестирование должно продолжаться несколько часов. Чтобы понять, были ли получены воспроизводимые значения, имеет смысл запустить тестирование несколько раз.

Для стандартного сценария по типу TPC-B начальный коэффициент масштаба (-s) должен быть не меньше числа клиентов, с каким вы намерены проводить тестирование (-c); в противном случае вы, по большому счёту, будете замерять время конкурентных изменений. Таблица pgbench_branches содержит всего -s строк, а каждая транзакция хочет изменить одну из них, так что если значение -c превышает -s, это несомненно приведёт к тому, что многие транзакции будут блокироваться другими.

Стандартный сценарий тестирования также довольно сильно зависит от того, сколько времени прошло с момента инициализации таблиц: накопление неактуальных строк и «мёртвого» пространства в таблицах влияет на результаты. Чтобы правильно оценить результаты, необходимо учитывать, сколько всего изменений было произведено и когда выполнялась очистка. Если же включена автоочистка, это может быть чревато непредсказуемыми изменениями оценок производительности.

Полезность результатов pgbench также может ограничиваться тем, что тестирование с большим числом клиентских сеансов само по себе нагружает систему. Этого можно избежать, запуская pgbench на другом компьютере, не на сервере баз данных, хотя при этом большое значение имеет скорость сети. Иногда, оценивая производительность одного сервера, полезно запускать даже несколько экземпляров pgbench параллельно, на отдельных клиентских компьютерах.

Безопасность

Если к базе данных, которая не приведена в соответствие шаблону безопасного использования схем, имеют доступ недоверенные пользователи, не запускайте pgbench в этой базе. Программа pgbench использует неполные имена и не настраивает для себя путь поиска.