Отладка

Deno поддерживает протокол V8 Inspector, используемый Chrome, Edge и Node.js. Благодаря этому отлаживать программы Deno можно с помощью Chrome DevTools или других клиентов, поддерживающих этот протокол (например, VSCode).

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

• --inspect
• --inspect-wait
• --inspect-brk

--inspect

Использование флага --inspect запустит программу с сервером инспектора, который позволяет подключаться клиентам, поддерживающим протокол V8 Inspector, например Chrome DevTools.

Перейдите по адресу chrome://inspect в браузере на базе Chromium, чтобы подключить Deno к серверу инспектора. Это позволяет исследовать код, добавлять точки останова и пошагово выполнять код.

deno run --inspect your_script.ts

При необходимости можно указать хост и порт сервера инспектора. Допускается указывать как полный адрес, так и только номер порта:

# Default: listen on 127.0.0.1:9229
deno run --inspect your_script.ts

# Custom port
deno run --inspect=9230 your_script.ts

# Custom host and port
deno run --inspect=0.0.0.0:9229 your_script.ts

--inspect-publish-uid

По умолчанию Deno выводит URL WebSocket инспектора в stderr, когда начинает принимать подключения. Управлять этим можно с помощью --inspect-publish-uid:

• stderr (по умолчанию) — выводит URL в stderr при запуске
• http — предоставляет URL через HTTP-конечную точку /json/list на порту инспектора вместо его вывода; полезно для программных инструментов, которые периодически проверяют наличие доступных целей

deno run --inspect --inspect-publish-uid=http your_script.ts

--inspect-wait

Флаг --inspect-wait будет ждать подключения отладчика, прежде чем выполнить код.

deno run --inspect-wait your_script.ts

--inspect-brk

Флаг --inspect-brk будет ждать подключения отладчика, прежде чем выполнить код, а затем установит точку останова в программе сразу после подключения. Это позволит добавить дополнительные точки останова или вычислить выражения, прежде чем продолжить выполнение.

Это наиболее часто используемый флаг инспектора. IDE JetBrains и VSCode используют его по умолчанию.

deno run --inspect-brk your_script.ts

Активация инспектора во время выполнения

Флаги --inspect запускают сервер инспектора при запуске процесса. Если вместо этого нужно запустить его по запросу в уже работающей программе, это можно сделать из самой программы с помощью модуля node:inspector или извне, отправив процессу сигнал SIGUSR1. Это удобно для длительно работающих процессов, например серверов, когда нужно, чтобы отладчик принимал подключения только после выполнения определённого условия, а не в течение всего времени работы процесса.

inspector.open([port][, host][, wait]) запускает сервер инспектора. По умолчанию используется порт 9229 и хост 127.0.0.1. Поскольку программа открывает сетевой сокет, ей требуется разрешение --allow-net (или запуск с -A).

import inspector from "node:inspector";

Deno.serve((req) => {
  if (new URL(req.url).pathname === "/debug" && !inspector.url()) {
    inspector.open(9229, "127.0.0.1");
    console.log("Inspector listening on", inspector.url());
  }
  return new Response("hello");
});

deno run --allow-net server.ts

Отправьте запрос на /debug, чтобы запустить сервер инспектора; затем откройте chrome://inspect в браузере на базе Chromium для подключения. Модуль предоставляет несколько связанных функций:

• inspector.open(port, host, true) — если передать true в качестве третьего аргумента, функция будет блокироваться до подключения клиента, как и inspector.waitForDebugger().
• inspector.url() — возвращает URL WebSocket инспектора или undefined, если инспектор не активен.
• inspector.close() — останавливает сервер инспектора.

Также доступен Session для программной отправки команд протокола Chrome DevTools без внешнего клиента.

Запуск инспектора с помощью сигнала

Начиная с Deno 2.9.2, в Linux и macOS можно также активировать инспектор извне процесса, отправив ему сигнал SIGUSR1, как это работает в Node.js. Сервер инспектора запустится на порту 127.0.0.1:9229 по умолчанию, не приостанавливая выполнение, и выведет обычное сообщение в stderr:

$ deno run server.ts &
$ kill -USR1 <pid>
Debugger listening on ws://127.0.0.1:9229/ws/...
Visit chrome://inspect to connect to the debugger.

Это полезно для отладки длительно работающего процесса, например сервера, запущенного без флага --inspect, который сложно перезапустить. В отличие от inspector.open(), для этого не требуются разрешения или содействие со стороны кода программы.

Следует учитывать несколько особенностей:

• Если сервер инспектора уже запущен (с помощью флага --inspect*, inspector.open() или предыдущего SIGUSR1), сигнал не повлияет на его работу.
• Обработчик сигнала устанавливается вскоре после запуска, поэтому этот способ предназначен для программ, работающих дольше примерно половины секунды.
• Обработчик продолжает работать наряду с обработчиками сигналов, добавленными с помощью Deno.addSignalListener("SIGUSR1").
• SIGUSR1 не существует в Windows, поэтому эта возможность там недоступна.

Пример с Chrome DevTools

Давайте попробуем отладить программу с помощью Chrome DevTools. Для этого воспользуемся @std/http/file-server — сервером статических файлов.

Используйте флаг --inspect-brk, чтобы остановить выполнение на первой строке:

$ deno run --inspect-brk -RN jsr:@std/http/file-server
Debugger listening on ws://127.0.0.1:9229/ws/1e82c406-85a9-44ab-86b6-7341583480b1
...

В браузере на базе Chromium, например Google Chrome или Microsoft Edge, откройте chrome://inspect и нажмите Inspect рядом с целью:

После открытия DevTools может потребоваться несколько секунд, чтобы загрузить все модули.

Вы можете заметить, что DevTools приостанавливает выполнение на первой строке _constants.ts, а не file_server.ts. Это ожидаемое поведение, обусловленное тем, как в JavaScript вычисляются ES-модули (_constants.ts — самая левая и нижняя зависимость file_server.ts, поэтому она вычисляется первой).

Теперь весь исходный код доступен в DevTools. Откроем file_server.ts и добавим там точку останова; перейдите на панель «Исходники» и раскройте дерево:

Если внимательно присмотреться, можно заметить повторяющиеся записи для каждого файла: одна отображается обычным шрифтом, а другая — курсивом. Первая — это скомпилированный исходный файл (поэтому для файлов .ts это будет сгенерированный исходный код JavaScript), а вторая — карта исходного кода для файла.

Затем добавьте точку останова в метод listenAndServe:

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

Теперь, когда точки останова установлены, можно продолжить выполнение скрипта и исследовать входящий запрос. Для этого нажмите кнопку «Возобновить выполнение скрипта». Возможно, потребуется нажать её дважды!

Когда скрипт запустится, попробуйте отправить запрос и изучить его в DevTools:

curl http://0.0.0.0:4507/

Теперь можно изучить содержимое запроса и пошагово отладить код.

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

Начиная с Deno 2.8, Chrome DevTools может просматривать сетевой трафик программы так же, как трафик во вкладке браузера. Запустите программу с флагом --inspect-wait (или --inspect / --inspect-brk), откройте chrome://inspect в браузере на базе Chromium, нажмите Inspect у цели Deno и перейдите на вкладку Network.

На вкладке Network отображаются следующие встроенные API:

• fetch() — запросы отображаются с Type: fetch
• node:http и клиентские запросы node:https (http.request, http.get, https.request, https.get) — в столбце Type указывается тип содержимого ответа (например, json, document), поэтому любая библиотека npm, выполняющая HTTP-запросы через node:http, отображается наряду с трафиком fetch()
• WebSocket — клиентские подключения отображаются вместе с HTTP-запросами; доступны состояние рукопожатия и заголовки ответа на обновление протокола, фреймы сообщений и событие закрытия сокета
• Deno.upgradeWebSocket() — обновления соединений WebSocket на стороне сервера также отслеживаются, поэтому можно просматривать обе стороны соединения при рукопожатии Deno-to-Deno

Для каждого запроса можно увидеть URL, метод, код состояния, заголовки и тела запроса и ответа, а также информацию о времени выполнения.

Давайте проверим это на небольшой программе, использующей fetch():

const res = await fetch("https://api.github.com/repos/denoland/deno");
console.log(res.status, (await res.json()).stargazers_count);

Запустите её с --inspect-wait, чтобы программа приостановилась до подключения DevTools:

$ deno run --inspect-wait --allow-net net.ts
Debugger listening on ws://127.0.0.1:9229/...
Visit chrome://inspect to connect to the debugger.
Deno is waiting for debugger to connect.

Откройте chrome://inspect, нажмите Inspect у цели Deno и перейдите на вкладку Network. Запрос fetch() отображается как обычная сетевая запись, а панели запроса и ответа заполнены:

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

То же относится к node:http и node:https, поэтому библиотеки npm, выполняющие HTTP-запросы через встроенный клиент Node (а не через fetch()), также отображаются на вкладке Network. Например:

import https from "node:https";

const options = {
  hostname: "api.github.com",
  path: "/repos/denoland/deno",
  headers: { "User-Agent": "deno-docs-example" },
};

https.get(options, (res) => {
  let body = "";
  res.on("data", (chunk) => body += chunk);
  res.on(
    "end",
    () => console.log(res.statusCode, JSON.parse(body).stargazers_count),
  );
});

$ deno run --inspect-wait --allow-net node-http.ts

Запрос отображается на вкладке Network с теми же заголовками, телом и информацией о времени выполнения, что и запрос fetch(); в столбце Type указывается тип содержимого ответа (в этом примере — json):

Подключения WebSocket также отображаются на вкладке Network; сообщения и событие закрытия появляются по мере развития соединения:

Соединения WebSocket на стороне сервера, созданные с помощью Deno.upgradeWebSocket(), также отслеживаются. Это позволяет просматривать обе стороны соединения — исходящий клиентский WebSocket и обновление соединения на сервере, который его принимает. Например, небольшой эхо-сервер:

Deno.serve({ port: 8000 }, (req) => {
  if (req.headers.get("upgrade") !== "websocket") {
    return new Response("send a WebSocket request", { status: 426 });
  }
  const { socket, response } = Deno.upgradeWebSocket(req);
  socket.onmessage = (e) => socket.send(`echo: ${e.data}`);
  return response;
});

$ deno run --inspect-wait --allow-net ws-server.ts

Подключите DevTools и продолжите выполнение, затем подключитесь к серверу из другого терминала (например, с помощью deno eval):

deno eval 'const ws = new WebSocket("ws://localhost:8000");
  ws.onopen = () => ws.send("hello");
  ws.onmessage = (e) => { console.log(e.data); ws.close(); };'

Обновление соединения и фреймы сообщений отображаются на вкладке Network в сеансе DevTools сервера:

Те же события также доступны через node:inspector для программных клиентов, поэтому инструменты, уже взаимодействующие с Node через протокол Chrome DevTools, могут подключаться к Deno и наблюдать тот же сетевой трафик без каких-либо изменений.

VSCode

Отлаживать Deno можно с помощью VSCode. Лучше всего это делать с помощью официального расширения vscode_deno. Документацию можно найти здесь.

IDE JetBrains

Примечание: убедитесь, что этот плагин Deno установлен и включён в Preferences / Settings | Plugins. Подробнее см. в этой записи в блоге.

Чтобы отладить Deno в IDE JetBrains, щёлкните правой кнопкой мыши файл, который нужно отладить, и выберите параметр Debug 'Deno: <file name>'.

Будет создана конфигурация запуска/отладки без установленных флагов разрешений. Чтобы настроить их, откройте конфигурацию запуска/отладки и добавьте необходимые флаги в поле Command.

--log-level=debug

Если возникли проблемы с подключением к инспектору, используйте флаг --log-level=debug, чтобы получить больше информации о происходящем. Вы увидите сведения, например, о разрешении модулей, сетевых запросах и других проверках разрешений.

deno run --inspect-brk --log-level=debug your_script.ts

--strace-ops

Операции Deno (ops) — это механизм удалённого вызова процедур (RPC) между JavaScript и Rust. Они предоставляют JavaScript такие возможности, как ввод-вывод файлов, работа с сетью и таймеры. Флаг --strace-ops выводит все операции, выполняемые Deno при запуске программы, вместе с длительностью их выполнения.

deno run --strace-ops your_script.ts

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

Профилирование ЦП

В Deno есть встроенный профилировщик ЦП: соберите профиль во время работы программы, а затем просмотрите его в виде отчёта Markdown, интерактивной пламенной диаграммы или в Chrome DevTools. Сведения о флагах, форматах отчётов и анализе приведены в разделе «Профилирование ЦП».

Интеграция с OpenTelemetry

Для производственных приложений или сложных систем OpenTelemetry предоставляет более комплексный подход к наблюдаемости и отладке. В Deno предусмотрена встроенная поддержка OpenTelemetry, которая позволяет:

• Отслеживать запросы в приложении
• Мониторить показатели производительности приложения
• Собирать структурированные журналы
• Экспортировать данные телеметрии в системы мониторинга

OTEL_DENO=true deno run your_script.ts

При этом автоматически собираются и экспортируются данные о наблюдаемости среды выполнения, в том числе:

• Трассировки HTTP-запросов
• Показатели среды выполнения
• Записи консоли и ошибки

Полное описание интеграции Deno с OpenTelemetry, включая пользовательские метрики, трассировки и параметры конфигурации, см. в документации OpenTelemetry.

Отладка Web Workers

Начиная с Deno 2.7, Web Workers можно отлаживать с помощью Chrome DevTools и VS Code. При запуске программы с любым флагом --inspect каждый созданный рабочий поток отображается как отдельная цель в chrome://inspect наряду с основным потоком.

const worker = new Worker(import.meta.resolve("./worker.ts"), {
  type: "module",
});
worker.postMessage("start");

self.onmessage = (e) => {
  console.log("Worker received:", e.data);
  // Set breakpoints here in DevTools
};

deno run --inspect-brk --allow-read main.ts

Откройте chrome://inspect — в списке будут отображаться main.ts и worker.ts как отдельные цели для инспектирования. Нажмите Inspect у цели рабочего потока, чтобы открыть отдельную панель DevTools для этого потока. В ней можно устанавливать точки останова, пошагово выполнять код и исследовать переменные независимо от основного потока.

В VS Code с расширением Deno рабочие потоки отображаются как отдельные потоки на панели отладчика Call Stack.

Отладка сеансов TLS

Задайте переменную среды SSLKEYLOGFILE, чтобы записывать ключи сеансов TLS в файл. Это позволит расшифровывать и анализировать зашифрованный сетевой трафик с помощью таких инструментов, как Wireshark:

SSLKEYLOGFILE=./keys.log deno run -N main.ts

Затем загрузите keys.log в Wireshark (Edit > Preferences > Protocols > TLS > (Pre)-Master-Secret log filename), чтобы расшифровать перехваченный трафик TLS.