Отчеты пользователей с Diagnostics: более быстрое устранение ошибок с помощью ИИ

Пользовательские диагностические отчёты помогают одновременно исправлять ошибки и улучшать поддержку пользователей. Я разрабатываю приложения с 2009 года, и репозиторий Diagnostics стал результатом всего этого опыта. Его используют крупные приложения, в том числе продукты компаний вроде WeTransfer, и он снова и снова доказывает свою ценность.

Во многих компаниях я постоянно видел одну и ту же неэффективность: пользователь сообщает об ошибке, а первое, что приходится спрашивать, — какая версия приложения у него установлена. И это лишь один из типичных уточняющих вопросов. Я заметно повысил качество поддержки своего инструмента для разработчиков RocketSim, внедрив диагностические отчёты. А благодаря поддержке агентской разработки в Diagnostics анализ пользовательских проблем становится ещё проще.

Распространённая проблема каналов поддержки приложений

Вы создали приложение, настроили канал поддержки и получаете всё больше обратной связи. Это хорошо: обратная связь даёт возможности для улучшения. Однако многие обращения касаются редких ошибок, которые сложно воспроизвести. Чтобы разобраться, вам нужна дополнительная информация.

Вместо того чтобы сразу исправлять ошибку, сначала приходится вести переписку с пользователем и уточнять детали. Скорее всего, вы задаёте вопросы вроде:

• Какая у вас версия операционной системы?
• Вы обновились до последней версии приложения?

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

Представляем open source-библиотеку Diagnostics

Я рад представить вам свою библиотеку с открытым исходным кодом — Diagnostics. Она основана на моём опыте разработки приложений и поддержки исправления ошибок с 2009 года. Библиотека добавляет в приложение встроенный способ сообщать о проблемах и прикрепляет к обращению так называемый диагностический отчёт — подробный HTML-файл.

Пример диагностического HTML-отчёта, открытого в браузере

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

Пример окна создания письма с диагностическим отчётом во вложении

Подробный взгляд на стандартный HTML-отчёт

Стандартный HTML-отчёт содержит ответы на типичные вопросы, например о версии операционной системы и версии приложения. Также он даёт сведения о системе: языке, объёме свободного места, типе устройства и других параметрах.

По-настоящему полезная часть — это журналы сессии. Их можно воспринимать как консоль Xcode: там собраны системные и отладочные логи, к которым вы привыкли при отладке. Для разработчика это крайне полезно, потому что позволяет подробно сузить область поиска проблемы. HTML-отчёт даже поддерживает фильтрацию системных журналов на JavaScript, поэтому можно сразу посмотреть только ошибки.

Фильтрация только по ошибкам позволяет быстро сделать вывод о проблеме пользователя.

В случае RocketSim я смог сразу сообщить пользователю, что мы пока не поддерживаем Stage Manager. Одного ответа по электронной почте хватило, чтобы объяснить ситуацию и сослаться на соответствующую задачу на GitHub.

Более эффективное взаимодействие с командой поддержки

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

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

Это приносит пользу всем сторонам:

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

Но это ещё не всё. Нам всё равно приходилось сообщать сотрудникам поддержки об известных проблемах. Если команда поддержки большая, такой процесс быстро становится неудобным. Поэтому мы добавили возможность под названием Smart Insights.

Использование Smart Insights

Smart Insights — это, по сути, полезные выводы, полученные после обработки логов. Diagnostics позволяет обработать каждую строку лога и вернуть соответствующий Smart Insight:

struct SmartInsightsProvider: SmartInsightsProviding {
    func smartInsights(for chapter: DiagnosticsChapter) -> [SmartInsightProviding] {
        guard let html = chapter.diagnostics as? HTML else { return [] }
        if html.errorLogs.contains(where: { $0.contains("Window is too small, likely due to Stage Manager switch") }) {
            return [
                SmartInsight(
                    name: "Stage Manager Issue Detected",
                    result: .warn(message: "An error was found regarding missing support for Stage Manager. Inform the user about this if needed.")
                )
            ]
        }
        return []
    }
}

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

По умолчанию доступны стандартные Smart Insights:

• UpdateAvailableInsight использует идентификатор пакета приложения, чтобы получить последнюю доступную версию. Вывод будет показан независимо от того, доступно ли пользователю обновление.
• DeviceStorageInsight показывает, не закончилось ли у пользователя свободное место на устройстве.

Пример раздела со Smart Insights может выглядеть так:

Пример раздела Smart Insights в диагностическом отчёте.

Более быстрое исправление ошибок с помощью агентов

Навык для диагностических отчётов позволяет эффективно разбирать пользовательские отчёты

Диагностический отчёт пользователя становится ещё полезнее, когда агент может читать его напрямую. Diagnostics 7.0 сохраняет тот же единый HTML-файл во вложении, который и раньше можно было отправлять команде поддержки, но теперь внутри отчёта также встроены структурированные JSON-данные.

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

Навык агента для разбора отчётов Diagnostics

Для эффективного с точки зрения токенов разбора отчётов я создал отдельный агентский навык. Он умеет работать с HTML-отчётами, читая встроенный структурированный JSON, а не разбирая отрисованную HTML-страницу. Агенты становятся гораздо полезнее, когда у них есть доступ и к коду вашего проекта, и к диагностическому отчёту. В этом случае они могут напрямую сопоставлять пользовательские журналы с конкретной реализацией.

Для самой простой установки добавьте навык анализатора через npx skills:

npx skills add https://github.com/AvdLee/Diagnostics --skill diagnostics-report-analyzer-skill

Инструкции для Claude, Cursor, OpenAI-совместимых инструментов, pi и ручной установки смотрите в файле agent-skill-install-instructions.md.

Экспорт в JSON вместо HTML

Стандартный API по-прежнему создаёт удобный для пользователя HTML-отчёт:

let report = await DiagnosticsReporter.create()

Если ваш процесс поддержки напрямую работает со структурированными данными, можно создать отдельный JSON-отчёт:

let report = await DiagnosticsReporter.create(format: .json)

Это позволяет отправлять пользовательский отчёт на основе Diagnostics на собственный сервер или в Linear и прикреплять его к задаче. Отправлять HTML-отчёт по электронной почте уже не обязательно: можно сразу работать со структурированным JSON.

Поэтому Diagnostics хорошо подходит для процессов поддержки и отладки, оптимизированных под искусственный интеллект.

Можно ли увидеть Diagnostics в работе?

Да. Если вы разработчик приложений, установите RocketSim из Mac App Store и отправьте сообщение о проблеме через меню в строке состояния. Diagnostics поддерживает iOS, iPadOS и macOS.

Это выгодно всем: RocketSim предлагает более 30 утилит для симулятора Xcode.

Заключение

Diagnostics серьёзно меняет подход к поддержке пользователей внутри приложений. HTML-отчёт сразу отвечает на типичные вопросы и уменьшает количество лишней переписки.

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

Если хотите узнать больше приёмов отладки, посмотрите раздел, посвящённый debugging. А если у вас есть дополнительные советы или обратная связь, можно связаться со мной или написать мне в Twitter.

Источник