deno bench, инструмент для бенчмаркинга

deno bench [OPTIONS] [files]... [-- [SCRIPT_ARG]...]

deno bench src/fetch_bench.ts src/signal_bench.ts

deno bench src/

Параметры проверки типов

--check

Установите поведение проверки типов. По умолчанию этот подкоманда проверяет типы локальных модулей, поэтому добавление --check излишне. Если указано значение "all", будут включены и удалённые модули. В качестве альтернативы можно использовать подкоманду 'deno check'.

--no-check

Пропустить проверку типов. Если указано значение "remote", диагностические ошибки удалённых модулей будут проигнорированы.

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

--cached-only

Требуется, чтобы удалённые зависимости уже были кэшированы.

--frozen

Выдавать ошибку, если файл блокировки устарел.

--import-map

Загрузить файл карты импорта из локального файла или удалённого URL.

--lock

Проверить указанный файл блокировки. (Если значение не указано, используется по умолчанию "./deno.lock").

--no-lock

Отключить автоматическое обнаружение файла блокировки.

--no-npm

Не разрешать модули npm.

--no-remote

Не разрешать удалённые модули.

--node-modules-dir

Устанавливает режим управления node_modules для пакетов npm.

--reload

Короткая форма: -r

Перезагрузить кэш исходного кода (перекомпилировать TypeScript). Без значения — перегрузить всё. Например: jsr:@std/http/file-server,jsr:@std/assert/assert-equals Перезагружает определённые модули. npm: Перезагрузить все модули npm. npm:chalk Перезагрузить определённый модуль npm.

--vendor

Включает или отключает использование локальной папки vendor для удалённых модулей и папки node_modules для пакетов npm.

Параметры

--allow-scripts

Разрешить выполнение скриптов жизненного цикла npm для заданных пакетов. Примечание: скрипты будут выполняться только при использовании директории node_modules (--node-modules-dir).

--cert

Загрузить центр сертификации из файла в формате PEM.

--config

Короткая форма: -c

Настроить различные аспекты deno, включая TypeScript, проверки на соответствие стилю кода и форматирование кода. Обычно файл конфигурации называется deno.json или deno.jsonc и автоматически обнаруживается; в этом случае этот флаг не нужен.

--env-file

Загрузить переменные окружения из локального файла. Используется только первая переменная окружения с заданным ключом. Существующие переменные окружения процесса не перезаписываются, поэтому, если переменные с одинаковыми именами уже существуют в среде, их значения сохранятся. Если в вашем файле .env существует несколько объявлений одной и той же переменной среды, используется первое встреченное. Это определяется порядком файлов, которые вы передаёте в качестве аргументов.

--ext

Установить тип содержимого предоставленного файла.

--filter

Запустить бенчмарки с этим строковым или регулярным выражением в имени бенчмарка.

--ignore

Игнорировать файлы.

--json

НЕСТАБИЛЬНО: Вывод результатов бенчмарка в формате JSON.

--location

Значение globalThis.location, используемое некоторыми веб-API.

--no-config

Отключить автоматическую загрузку файла конфигурации.

--no-run

Кэшировать модули бенчмарка, но не запускать бенчмарки.

--seed

Установить начальное значение генератора псевдослучайных чисел.

--v8-flags

Чтобы увидеть список всех доступных флагов, используйте --v8-flags=--help Флаги также можно установить через переменную среды DENO_V8_FLAGS. Любые флаги, установленные с помощью этого флага, добавляются после переменной среды DENO_V8_FLAGS.

Параметры отслеживания файлов

--no-clear-screen

Не очищать экран терминала при работе в режиме отслеживания.

--watch

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

--watch-exclude

Исключить указанные файлы/шаблоны из режима отслеживания.

Быстрый старт

Сначала, давайте создадим файл url_bench.ts и зарегистрируем стенд с помощью функции Deno.bench().

// url_bench.ts
Deno.bench("URL parsing", () => {
  new URL("https://deno.land");
});

Во-вторых, запустите бенчмарк, используя подкоманду deno bench.

deno bench url_bench.ts
cpu: Apple M1 Max
runtime: deno 1.21.0 (aarch64-apple-darwin)

file:///dev/deno/url_bench.ts
benchmark        time (avg)             (min … max)       p75       p99      p995
--------------------------------------------------- -----------------------------
URL parsing   17.29 µs/iter  (16.67 µs … 153.62 µs)  17.25 µs  18.92 µs  22.25 µs

Написание бенчмарков

Чтобы определить бенчмарк, необходимо зарегистрировать его вызовом API Deno.bench. Существует множество перегрузок этого API, чтобы обеспечить максимальную гибкость и лёгкое переключение между формами (например, когда вам нужно быстро сфокусироваться на одном стенде для отладки, используя опцию only: true):

// Compact form: name and function
Deno.bench("hello world #1", () => {
  new URL("https://deno.land");
});

// Compact form: named function.
Deno.bench(function helloWorld3() {
  new URL("https://deno.land");
});

// Longer form: bench definition.
Deno.bench({
  name: "hello world #2",
  fn: () => {
    new URL("https://deno.land");
  },
});

// Similar to compact form, with additional configuration as a second argument.
Deno.bench("hello world #4", { permissions: { read: true } }, () => {
  new URL("https://deno.land");
});

// Similar to longer form, with bench function as a second argument.
Deno.bench(
  { name: "hello world #5", permissions: { read: true } },
  () => {
    new URL("https://deno.land");
  },
);

// Similar to longer form, with a named bench function as a second argument.
Deno.bench({ permissions: { read: true } }, function helloWorld6() {
  new URL("https://deno.land");
});

Асинхронные функции

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

Deno.bench("async hello world", async () => {
  await 1;
});

Критические секции

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

Чтобы помочь в таких ситуациях, вы можете использовать Deno.BenchContext.start и Deno.BenchContext.end для того, чтобы сообщить инструменту для бенчмаркинга о критической секции, которую вы хотите измерить. Всё вне секции между этими двумя вызовами будет исключено из измерения.

Deno.bench("foo", async (b) => {
  // Open a file that we will act upon.
  const file = await Deno.open("a_big_data_file.txt");

  // Tell the benchmarking tool that this is the only section you want
  // to measure.
  b.start();

  // Now let's measure how long it takes to read all of the data from the file.
  await new Response(file.readable).arrayBuffer();

  // End measurement here.
  b.end();

  // Now we can perform some potentially time-consuming teardown that will not
  // taint out benchmark results.
  file.close();
});

Группировка и эталонные значения

При регистрации бенчмарк-кейса, он может быть назначен группе, используя опцию Deno.BenchDefinition.group:

// url_bench.ts
Deno.bench("url parse", { group: "url" }, () => {
  new URL("https://deno.land");
});

Полезно назначить несколько кейсов одной группе и сравнить их производительность с "эталонным" кейсом.

В этом примере мы проверим, насколько эффективен Date.now() по сравнению с performance.now(), для этого мы обозначим первый кейс как "эталонный" с помощью опции Deno.BenchDefinition.baseline:

// time_bench.ts
Deno.bench("Date.now()", { group: "timing", baseline: true }, () => {
  Date.now();
});

Deno.bench("performance.now()", { group: "timing" }, () => {
  performance.now();
});

$ deno bench time_bench.ts
cpu: Apple M1 Max
runtime: deno 1.21.0 (aarch64-apple-darwin)

file:///dev/deno/time_bench.ts
benchmark              time (avg)             (min … max)       p75       p99      p995
--------------------------------------------------------- -----------------------------
Date.now()         125.24 ns/iter (118.98 ns … 559.95 ns) 123.62 ns 150.69 ns 156.63 ns
performance.now()    2.67 µs/iter     (2.64 µs … 2.82 µs)   2.67 µs   2.82 µs   2.82 µs

summary
  Date.now()
   21.29x times faster than performance.now()

Вы можете указать несколько групп в одном файле.

Запуск бенчмарков

Чтобы запустить бенчмарк, вызовите deno bench с файлом, содержащим вашу функцию бенчмарка. Вы также можете опустить имя файла, в этом случае будут запущены все бенчмарки в текущей директории (рекурсивно), которые соответствуют шаблону {*_,*.,}bench.{ts, tsx, mts, js, mjs, jsx}. Если вы передаёте директорию, будут запущены все файлы в этой директории, которые соответствуют шаблону.

Шаблон расширяется до:

• файлов с именем bench.{ts, tsx, mts, js, mjs, jsx},
• или файлов, заканчивающихся на .bench.{ts, tsx, mts, js, mjs, jsx},
• или файлов, заканчивающихся на _bench.{ts, tsx, mts, js, mjs, jsx}

# Run all benches in the current directory and all sub-directories
deno bench

# Run all benches in the util directory
deno bench util/

# Run just my_bench.ts
deno bench my_bench.ts

⚠️ Если вы хотите передать дополнительные аргументы командной строки файлам бенчмарков, используйте --, чтобы проинформировать Deno о том, что оставшиеся аргументы являются аргументами скрипта.

# Pass additional arguments to the bench file
deno bench my_bench.ts -- -e --foo --bar

deno bench использует ту же модель разрешений, что и deno run, и поэтому потребует, например, --allow-write, для записи в файловую систему во время бенчмаркинга.

Чтобы увидеть все параметры выполнения с deno bench, вы можете обратиться к справке командной строки:

deno help bench

Фильтрация

Существует ряд вариантов для фильтрации запускаемых бенчмарков.

Фильтрация командной строки

Бенчмарки можно запускать индивидуально или группами, используя опцию командной строки --filter.

Флаги фильтра принимают строку или шаблон в качестве значения.

Предположим следующие бенчмарки:

Deno.bench({
  name: "my-bench",
  fn: () => {/* bench function zero */},
});
Deno.bench({
  name: "bench-1",
  fn: () => {/* bench function one */},
});
Deno.bench({
  name: "bench2",
  fn: () => {/* bench function two */},
});

Эта команда запустит все эти бенчмарки, так как все они содержат слово "bench".

deno bench --filter "bench" benchmarks/

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

deno bench --filter "/bench-*\d/" benchmarks/

Чтобы сообщить Deno о том, что вы хотите использовать шаблон, оберните свой фильтр слешами, как в JavaScript для синтаксического сахара regex.

Фильтрация определения бенчмарка

Фильтрация исключения (пропуск этих бенчмарков)

Иногда вам нужно пропустить бенчмарки, основанные на каких-либо условиях (например, вы хотите, чтобы бенчмарк запускался только на Windows). Для этого вы можете использовать булеву переменную ignore в определении бенчмарка. Если она установлена в true, бенчмарк будет пропущен.

Deno.bench({
  name: "bench windows feature",
  ignore: Deno.build.os !== "windows",
  fn() {
    // do windows feature
  },
});

Фильтрация включения (запуск только этих бенчмарков)

Иногда вы можете быть в центре проблемы производительности внутри большого класса бенчмарков и захотите сфокусироваться только на одном бенчмарке и пропустить остальные на данный момент. Для этого вы можете использовать опцию only для того, чтобы сообщить инструменту для бенчмаркинга о запуске только тех бенчмарков, у которых это значение установлено в true. Несколько бенчмарков могут установить этот параметр. Хотя запуск бенчмарка будет сообщать об успехе или неудаче каждого бенчмарка, общий запуск бенчмарка всегда завершится неудачей, если какой-либо бенчмарк отмечен only, так как это временная мера, которая отключает почти все ваши бенчмарки.

Deno.bench({
  name: "Focus on this bench only",
  only: true,
  fn() {
    // bench complicated stuff
  },
});

Вывод в формате JSON

Чтобы получить вывод в формате JSON, используйте флаг --json:

$ deno bench --json bench_me.js
{
  "runtime": "Deno/1.31.0 x86_64-apple-darwin",
  "cpu": "Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz",
  "benches": [
    "origin": "file:///dev/bench_me.js",
    "group": null,
    "name": "Deno.UnsafePointerView#getUint32",
    "baseline": false,
    "result": {
      "ok": {
        "n": 49,
        "min": 1251.9348,
        "max": 1441.2696,
        "avg": 1308.7523755102038,
        "p75": 1324.1055,
        "p99": 1441.2696,
        "p995": 1441.2696,
        "p999": 1441.2696
      }
    }
  ]
}