Плагины для IntelliJ Platform Marketplace

Пользователь сообщает, что IDE перестала отвечать, и ваш плагин — главный подозреваемый. Вы пытаетесь повторить те же действия, но все работает. Без дополнительных деталей, таких как дамп потоков, снятый во время зависания, трудно понять, с чего начать.

JetBrains Marketplace теперь предоставляет авторам плагинов доступ к отчетам о зависании UI, связанных с их плагинами. Чтобы увидеть их, откройте страницу управления вашим плагином и выберите вкладку Freezes.

Есть один нюанс: сначала вам нужно включить отчетность Marketplace в вашем плагине. Надеемся, что вкладка останется пустой, но стоит настроить это заранее, прежде чем возникнет необходимость.

Что содержится в отчете о зависании?

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

Автоматически сгенерированный фрагмент дампа потоков дает вам отправную точку, показывая потоки, которые были определены как участвующие в зависании. Это также хороший первый ввод для AI-ассистента по программированию: короткий фрагмент помогает ему сориентироваться, используя меньше токенов, чем полные дампы. Для более глубокого расследования используйте навык analyze-freeze, а затем добавьте полные дампы, чтобы ассистент мог отследить связи между потоками или корутинами.

Файлы dump-N.txt содержат полные дампы потоков, снятые каждые пять секунд во время зависания. В зависимости от того, что IDE удалось зафиксировать, отчет может также включать:

snapshot.jfr, CPU-снимок.
report.txt, анализ захваченных стеков потоков.
open-telemetry-metrics.csv, показатели производительности, охватывающие такие области, как активность VFS и отзывчивость UI.

Начните с одного отчета

Откройте отчет и найдите поток диспетчеризации событий (EDT) в его фрагменте. Обычно он называется AWT-EventQueue-0 или содержит EDT. Сначала проверьте, занят ли EDT выполнением ресурсоемкой работы или ожидает завершения чего-то другого.

Для дальнейшего расследования скачайте полный дамп и используйте Search Everywhere в IDE, чтобы открыть Analyze Stack Trace или Thread Dump. Вставьте текст дампа и изучите результаты. Отслеживая, что мешает EDT продолжить работу, обращайтесь к исходным данным потока. Если доступно несколько дампов, сравните их, чтобы увидеть, остается ли одна и та же операция в стеке во всех выборках.

В примере ниже анализатор определяет ввод-вывод файла в EDT в org.xml.sax.helpers.XMLFilterImpl.parse.

Причина также может быть в фоновом потоке. Длительное, неотменяемое действие чтения (read action) может удерживать блокировку, необходимую для действия записи, из-за чего UI ожидает, даже если ресурсоемкая работа выполняется в другом месте. Статья «UI Freezes and the Dangers of Non-Cancellable Read Actions in Background Threads» подробно описывает этот паттерн и объясняет, как его исправить.

Попробуйте навык freeze-analysis

Наш коллега Патрик Шайбе создал навык analyze-freeze, чтобы помочь AI-ассистентам исследовать дампы потоков IntelliJ Platform. Он включает рекомендации по поведению корутин, нехватке ресурсов Dispatchers.Default и другим распространенным паттернам зависаний, а также советы по их исправлению.

Чтобы попробовать его:

Сохраните SKILL.md из gist в папку вашего расследования.
Добавьте скачанные полные дампы потоков вместе с report.txt и текстом coroutine-dump, если они доступны.
Попросите вашего ассистента прочитать навык и проанализировать эти файлы с помощью этого промпта:

Перед тем как делиться дампами с AI-сервисом, следуйте процессу обработки диагностических данных в вашем проекте. Используйте объяснения ассистента для руководства вашим расследованием и сверяйте указанные кадры с полным дампом и вашим кодом перед внесением изменений.

Включите отчетность Marketplace

Чтобы использовать встроенную отчетность Marketplace, зарегистрируйте ее обработчик ошибок в plugin.xml:

Этот обработчик доступен начиная с IntelliJ Platform 2023.3 и не требует пользовательской реализации. Для плагинов, поддерживающих Split Mode, зарегистрируйте его во фронтенд- или общем модуле плагина. Регистрация только в бэкенде не сделает его доступным для фронтенда.

Пользователи могут отправлять отчеты через UI отчетности об ошибках IDE или включить «Send error reports to JetBrains automatically», чтобы отправлять их в фоновом режиме. Если вкладка Freezes пуста, проверьте регистрацию вашего обработчика. Отчеты также зависят от настроек пользователя и того, определила ли IDE ваш плагин как причастный к проблеме.

Если вы поддерживаете собственный бэкенд для отчетности, руководство по SDK error reporting объясняет API ErrorReportSubmitter, ориентированный на пользователя, и экспериментальный API ErrorReportSink для автоматических фоновых отчетов. Вам не нужен собственный приемник для встроенной настройки Marketplace, описанной здесь.

Для видеообзора посмотрите «How IntelliJ Plugin Error Reporting Actually Works» Патрика Шайбе, где сравнивается отчетность Marketplace с пользовательским ErrorReportSubmitter. Также рассматривается, что именно отправляется и почему вложения важны для отчетов о зависаниях.

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

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

Как только вы нашли вероятную причину, сосредоточьтесь на операции, мешающей UI продолжить работу. Для длительного фонового действия чтения это может означать сокращение времени доступа к модели или выбор API для отменяемого действия чтения. Держите блокирующий ввод-вывод вне действия чтения и убедитесь, что любые вычисления, которые могут быть перезапущены, безопасны для повтора.

Протестируйте изменение, повторив затронутую операцию и изучив свежие диагностические данные. Если вы все еще в тупике, спросите на форуме JetBrains Platform, указав сборку IDE, версию плагина (если известна), соответствующие доказательства из дампа и то, что вы уже проверили.

Даже если вы не можете воспроизвести зависание, его полные дампы показывают, что делали потоки IDE во время задержки, и дают вам поле для исследования. Если отчетность Marketplace включена для вашего плагина, посетите страницу Freezes и проверьте наличие отчетов; короткие фрагменты помогут вам решить, где искать в первую очередь. Удачи в расследовании и приятной отладки!