Содержание

1. Аккаунт

• Способы входа
• Настройки аккаунта
  • Язык интерфейса
  • Общие настройки
  • Уведомления Хоука

2. Организация рабочего пространства

• Воркспейсы
• Настройки воркспейса
• Управление командой
  • Приглашение в команду
    • по email
    • по ссылке
  • Управление доступом
    • Роли
• Покинуть воркспейс
• Платежи
  • Оплата картой (рекомендуемый способ)
    • Автопродление
    • Разовые платежи
    • Оплата по СБП
  • Оплата по счету
    • История операций

3. Проекты

• Настройки проекта
• Интеграции
  • Интеграционный Токен
  • Sentry DSN
• Уведомления
  • Настройка сценариев
    • Где получать
      • Telegram
      • Slack
      • Email
    • Что получать
      • Только новые
      • По частоте появления
    • Фильтры
      • Включить события с текстом
      • Исключить события с текстом
• Группировка событий
  • Паттерны для группировки ошибок

4. Список событий

• График здоровья приложения
• Фильтрация и сортировка
  • Все
  • Избранные
  • Исправленные
  • Не исправленные
  • Игнорируемые
• Сортировка
  • По дате
  • По количеству повторений
  • По количеству затронутых пользователей
• Поиск
  • По заголовку ошибки
  • По именам файлов в Стектрейсе
  • По контексту
  • По Addons
• Группировка по дням

5. События в Хоуке

• Информация о событии
  • Заголовок (текст, сообщение) ошибки
  • Файл и строка
  • Даты появления
  • Количество повторений
  • Количество затронутых пользователей
  • Стек трейс
  • Фрагмент кода
  • Addons
  • Context
  • Список пользователей, которые видели ошибку
• Addons — данные, собранные SDK
• Контекст события — ручное прикрепление данных к событию
• Список повторений ошибки
• Статистика по дням
• Действия с событием
  • Пометить как исправленное
  • Игнорировать
  • Добавить в избранное
  • Назначить исполнителя

6. Фильтрация чувствительных данных

• Фильтрация на стороне кэтчера
• Фильтрация на стороне бэкенда
  • Авторизация и сессии
  • API ключи и секреты
  • Пароли
  • Ключи шифрования
  • Платёжные данные
  • Конфигурации и подключения
  • Персональные данные

7. Хранение событий

8. Лимиты, квоты и тарифы

• Бесплатный план
• Тарифные планы
• Период обновления
• Превышение лимитов
• Стратегии управления лимитами

9. Rate Limits

• На воркспейс
• На проект

10. Релизы

• Как использовать релизы
• Source Maps
  • Webpack Plugin
  • Vite Plugin
• Commits
  • Ручная отправка коммитов в Хоук
  • Отправка коммитов через GitHub Actions

11. Возможности SDK

• Глобальный отлов ошибок
• Ручная отправка ошибок и логов
• Отправка аддонов
• Отправка событий с контекстом
  • Прикрепление контекста глобально
  • Прикрепление контекста к конкретному событию
• Прикрепление пользователя
  • Автоматический трекинг пользователя
• Stack Trace
• Привязка релиза
• Уровень критичности события
• Фильтрация чувствительных данных

12. Интеграции с логгерами

13. Трекинг консоли браузера

14. Поддержка Sentry SDK

15. Существующие SDK

• JavaScript/TypeScript (Browser)
• Node.js
• React
• Vue
• Nuxt
• Webpack
• Vite
• Python
• Flask
• FastAPI
• PHP
• Symfony
• Laravel
• Go
• Android
• Kotlin
• Java
• Что делать, если нет SDK для вашего фреймворка?
• Как самому сделать SDK для вашего фреймворка

16. Self-hosted версия

• Как использовать
• Почему это дороже и сложнее
• Ограничения

17. Hawk Desktop

18. В будущих версиях

• Performance monitoring
• Аналитика крашей на мобильных платформах (iOS и Android)
• AI filtering

19. Заключение

---

1. Аккаунт

Способы входа

Хоук поддерживает вход только по email. После регистрации пароль приходит на указанную почту. В дальнейшем его можно изменить в настройках аккаунта.

Настройки аккаунта

В настройках аккаунта доступны:

• Выбор языка интерфейса: поддерживаются русский и английский;

• Общие настройки: имя, email, пароль;

• Уведомления Хоука: можно включить или отключить email-уведомления о событиях и лимитах.

---

2. Организация рабочего пространства

Воркспейсы

Рабочее пространство (воркспейс) — это логическая единица, в которой ведется работа над проектами (разными интеграциями). Например, воркспейс представляет собой компанию или команду, а проекты — frontend, backend, внутренние сервисы. Каждый пользователь может создать несколько воркспейсов.

Настройки воркспейса

В настройках можно задать название воркспейса и управлять участниками команды. Доступ к управлению тарифами, оплатами и лимитами находится в разделе «Платежи».

Управление командой

В команду можно приглашать участников по email или ссылке. Члены команды имеют два уровня доступа:

• Администратор: управляет платежами и назначает новых администраторов.

• Обычный участник: просматривает проекты и события, приглашает новых участников, назначает исполнителей, ставит отметки о исправленных/игнорируемых ошибках.

Покинуть воркспейс

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

Платежи

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

• Картой или СБП — подходит для юрлиц и физлиц. Удобна для малых тарифов.

• Оплатой по счету — подходит для юрлиц. Больше подходит для крупных тарифов.

Оплата картой (рекомендуемый способ)

Преимущества оплаты картой:

• Активация плана происходит моментально после оплаты.

• Чек об оплате приходит на email. Его можно использовать для бухгалтерии. По запросу можно получить акт.

• Все операции отображаются в истории операций, что удобно для бухгалтерии.

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

Автопродление

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

Разовые платежи

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

Оплата по СБП

В окне выбора способа можно выбрать "СБП" и получить QR-код для оплаты. В этом варианте также доступно автоматическое продление плана и разовая оплата.

Оплата по счету

Для более крупных тарифов компаниям иногда удобнее проводить оплату по счету. Для выставления счета обратитесь в поддержку по почте team@hawk.so или в Telegram и пришлите данные о компании, воркспейсе и тарифном плане.

Активация плана происходит в течение 48 часов после оплаты счета. Закрывающие документы присылаются по запросу.

История операций

В истории операций можно посмотреть платежи, связанные с воркспейсом.

---

3. Проекты

Проект — единичная интеграция внутри воркспейса для отслеживания событий от одного приложения или его части (например, «Frontend» или «Auth API»). Создайте столько проектов, сколько разных частей системы есть в вашей архитектуре.

Настройки проекта

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

В настройках проекта можно:

• Изменить название проекта;

• Загрузить иконку проекта;

• Использовать лейблы в названии: например, [prod] Auth API — в интерфейсе будет отображён бейдж prod.

Интеграции

В этом разделе:

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

• Доступен Sentry DSN, совместимый с оригинальным Sentry SDK — удобно для миграции или если у Хоука пока нет SDK для нужного фреймворка.

Уведомления

Очень важно включить уведомления об ошибках и сделать это правильно, чтобы не пропустить важные события, и в то же время не получать спам.

Работа над уведомлениями осуществляется с помощью Сценариев — правил, которые определяют, когда и как будут отправляться уведомления. Можно создать один или несколько сценариев уведомлений, основанных на разных критериях:

• Где получать: Telegram, Slack, Email;

• Что получать: Только новые, по частоте появления;

• Фильтры: по тексту ошибки, включить или исключить ключевые слова;

Примеры сценариев:

• Если произошла новая ошибка со словом "Payment", отправить уведомление на Email

• Если ошибка на бэкенде выпала больше 500 раз за 5 минут, отправить уведомление в чат с разработчиками в Telegram

• Ошибки со словами "Auth" отправлять в специальный канал

Группировка событий

События в Хоуке группируются только в двух случаях:

• При наличии идентичного заголовка ошибки

• По пользовательским паттернам

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

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

SyntaxError: Unexpected token .* in JSON at position .*

---

4. Список событий

Если в проекте еще нет ни одного события, вы увидите каталог интеграций:

График здоровья приложения

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

Фильтрация и сортировка

Доступны следующие фильтры событий:

• Все

• Избранные

• Исправленные

• Не исправленные

• Игнорируемые

И сортировки:

• По дате

• По количеству повторений

• По количеству затронутых пользователей

Поиск

В списке событий работает поиск, который ищет совпадения по:

• Заголовку ошибки;

• Именам файлов в Стектрейсе;

• Прикрепленным к событию данным (контексту);

• Addons (sdk-specific данным).

Пример: найти все ошибки, связанные с пользователем userId: 12345.

{"userId":12345}

Группировка по дням

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

---

5. События в Хоуке

Информация о событии

Каждое событие содержит следующую информацию:

• Заголовок (текст, сообщение) ошибки

• В каком файле и строке возникла ошибка

• Дату первого появления

• Дату текущего просматриваемого повторения

• Общее число повторений

• Количество уникальных пользователей, столкнувшихся с ошибкой

• Стек трейс вызова функции, в которой возникла ошибка

• Фрагмент кода, в котором возникла ошибка по каждому файлу в стектрейсе

• Addons — дополнительные данные, автоматически собранные SDK (например, URL, браузер, версия ОС);

• Context — данные, прикрепленные вручную (например, ID пользователя, текущий экран);

• Список пользователей, столкнувшихся с ошибкой

Addons

Аддоны — это дополнительные данные, автоматически собранные SDK. Например, Hawk JavaScript SDK добавляет информацию об URL, браузере, версии ОС, устройстве.

Каждый кэтчер (SDK) добавляет свои аддоны в зависимости от платформы.

Контекст события

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

• глобально (прикрепляется к каждому событию)

• конкретно для одного события

См. раздел Возможности SDK.

Список повторений ошибки

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

Статистика по дням

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

Действия с событием

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

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

Игнорировать

Игнорирование ошибки полезно, когда она не является критической и ее исправление не планируется. У таких ошибок есть следующие особенности:

• В списке событий они будут полупрозрачными

• Уведомления о таких ошибках не будут приходить

Добавить в избранное

Такие ошибки будут выделяться в списке событий. Это поможет быстрее найти и обратить на них внимание.

Назначить исполнителя

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

---

6. Фильтрация чувствительных данных

Иногда в событиях могут оказаться данные, которые не должны покидать ваш сервер или устройство пользователя. Фильтрация помогает скрыть такие поля и не отправлять их в Хоук. <anchor>data-filtering</anchor>

Фильтрация работает на двух уровнях:

• На стороне кэтчера (в вашем приложении, до отправки события).

• На стороне бэкенда Хоука.

Фильтрация на стороне кэтчера

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

Он принимает объект события, в котором можно удалить или модифицировать данные. Вы можете вернуть false, тогда событие не будет отправлено вовсе.

const hawk = new HawkCatcher({
  token: 'ВАШ_ТОКЕН_ИНТЕГРАЦИИ',
  beforeSend(event) {
     
    // Удаляем заголовок авторизации  
    if (event.payload.context.request?.headers?.Authorization) {
      delete event.payload.context.headers.Authorization;
    }

    // Для отмены отправки, вернем false
    if (event.title.startsWith('Script Error.')) {
      return false;
    }

    return event;
  }
});

Фильтрация на стороне бэкенда

Дополнительно Хоук фильтрует потенциально опасные данные на своей стороне.

Следующие данные будут заменены на [filtered]:

• значения, которые выглядят как номера банковских карт (по регулярным выражениям);

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

?️ Авторизация и сессии

? API ключи и секреты

?‍? Пароли

? Ключи шифрования

? Платёжные данные

? Конфигурации и подключения

? Персональные данные

Такая защита снижает риск утечки конфиденциальных данных даже если вы не отфильтровали их на клиентской стороне.

---

7. Хранение событий

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

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

---

8. Лимиты, квоты и тарифы

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

Бесплатный план

По умолчанию Хоук бесплатный. Ограничение — 1000 событий в месяц. Ограничений по функциональности нет.

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

Тарифные планы

Актуальные характеристики и стоимость тарифов опубликованы на сайте Хоука: https://hawk-tracker.ru

Способы оплаты:

• Привязка карты

• Разовый платеж с карты

• СБП (разовый и подписка)

• Выставление счета

Все способы подходят как для физических, так и для юридических лиц. Подробнее в разделе "Платежи".

Преимущества платных планов:

• Увеличенный лимит событий

• Помощь с интеграцией и настройкой

• Приоритетная техническая поддержка

• Возможность установить Рейт Лимиты (см. раздел Rate Limits), чтобы защититься от спайков ошибок.

• Возможность доработки функциональности Хоука по запросу, влияние на Roadmap, заказ новых SDK.

• Закрывающие документы, чеки, акты.

Период обновления

Он же Платежный период. Составляет 1 месяц. Отсчитывается с момента регистрации или обновления тарифного плана.

В конце периода счетчик событий обнуляется.

Для платных тарифов:

• Если активна подписка, в конце периода происходит списание денег за следующий период.

• В случае разового платежа за 3, 2, 1, 0 дней до конца периода команда получает email-уведомление о необходимости оплаты следующего месяца.

• В случае отсутствия оплаты, 3 дня воркспейс остается незаблокированным. Если оплата не была произведена, воркспейс блокируется.

Превышение лимитов

Что происходит при достижении лимита:

• Уведомления: команда получает email-уведомление при исчерпании 95% лимита. Также уведомление приходит в момент блокировки воркспейса.

• Момент блокировки: события перестают приниматься в течение часа после достижения лимита

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

Стратегии управления лимитами

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

• Мониторинг использования: в интерфейсе Хоука отображается текущее потребление событий. Позволяет следить за использованием лимитов и планировать расходы.

• Исправление ошибок: конечно, главное — вовремя исправлять самые критичные ошибки.

• Фильтрация событий: для исключения неважных ошибок используйте хук beforeSend на стороне Кэтчера. Подробнее в разделе "Возможности SDK".

• Rate Limiting: настройка ограничений на количество событий за единицу времени. Подробнее в разделе "Rate Limits".

---

9. Rate Limits

Rate limits позволяют защититься от спайков — резкого увеличения количества событий в единицу времени, которое может быть вызвано:

• Критической ошибкой, выпавшей разово в большом количестве пользователей;

• Злонамеренными действиями пользователей, например, накрутки, DDOS-атаками, массовыми действиями.

• Зацикливанием ошибок

• Падением внешних и внутренних сервисов

С помощью Рейт-лимитов можно установить максимальное количество событий за единицу времени, которое будет принимать Хоук. Остальные события будут отброшены. Благодаря этому, вы защищаетесь от рисков исчерпания объема тарифного плана из-за спайков.

Особенности:

• Можно установить как на воркспейс, так и на проект.

• Доступно только для платных тарифов.

---

10. Релизы

Релизы в Хоуке — это механизм, который связывает события (ошибки, логи) с конкретной версией вашего приложения. <anchor>releases</anchor>

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

Это позволяет:

• связать ошибки именно с той версией кода, где они возникли;

• корректно отобразить stack trace по исходным картам (source maps);

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

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

Что входит в релиз:

• Название версии (например, 1.0.3);

• Список коммитов (опционально);

• Source Maps

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

Для того, чтобы релизы заработали, нужно сделать два шага:

• Настроить отправку релизов с помощью Webpack или Vite плагинов (см. ниже)

• Передать id релиза при инициализации SDK Хоука. Id генерируется автоматически плагинами или задается вручную.

Source Maps

Для клиентских (JavaScript, TypeScript, React, Vue, и т.д.) рекомендуется настроить отправку Source Maps. Так при просмотре информации об ошибке, вы увидите исходный код и названия функций.

Webpack Plugin

Плагин отправляет релизы с Source Maps и коммитами при сборке проекта.

const HawkWebpackPlugin = require('@hawk.so/webpack-plugin');

module.exports = {
  // ... other webpack options
  plugins: [
    new HawkWebpackPlugin({
      integrationToken: '' // Your project's Integration Token
    })
  ],
  devtool: 'source-map',
}

Читайте подробную инструкцию в readme @hawk.so/webpack-plugin

Vite Plugin

Инструкция по использованию плагина для Vite: @hawk.so/vite-plugin

import hawkVitePlugin from '@hawk.so/vite-plugin';

export default defineConfig({
  plugins: [
    ...,
    hawkVitePlugin({
      token: '' // Your project's Integration Token
    })
  ]
})

Commits

Коммиты — это информация о последних git-коммитах в релизе. Подозрительные коммиты будут отображаться в обзоре события. Так у вас будет больше информации о причине появления ошибки.

Отправлять коммиты можно следующими способами:

• С помощью @hawk.so/webpack-plugin

• Вручную

• Через GitHub Actions

Ручная отправка коммитов в Хоук

Отправить коммиты для релиза можно, например, с помощью shell-скрипта из репозитория hawk.releases: hawk.releases

$ ./commits.sh --release="Version 2.0.1" --token=eyJ...integrationToken...

Отправка коммитов через GitHub Actions

У Хоука есть специальный Action для GitHub Actions, который отправляет коммиты для релиза: codex-team/hawk.releases@v1

- name: Get package info
  id: package
  uses: codex-team/action-nodejs-package-info@v1

- name: Send release data
  uses: codex-team/hawk.releases@v1
  with:
    release: ${{ steps.package.outputs.name }}-${{ steps.package.outputs.version }}
    token: ${{ secrets.HAWK_TOKEN }}

---

11. Возможности SDK

SDK в Хоуке называются Кэтчерами. Это небольшие библиотеки, которые вы интегрируете в код приложения для отправки событий в Хоук. <anchor>sdk-features</anchor>

Глобальный отлов ошибок

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

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

Ручная отправка ошибок и логов

Все Кэтчеры также поддерживают ручную отправку событий. С помощью нее можно трекать обработанные в try-catch ошибки, отправлять логи, отслеживать события вручную.

Например, можно с помощью Хоука слать себе в Telegram уведомление (см. раздел "Уведомления"), когда пользователь осуществил заказ на сайте:

import HawkCatcher from '@hawk.so/javascript';

// Экземпляр кэтчера можно сохранить и использовать в виде синглтона
const hawk = new HawkCatcher({
  token: 'YOUR_INTEGRATION_TOKEN',
});

// Функция, которая вызывается при создании заказа
function onOrderCreated() {
    hawk.send('? Создан новый заказ', {
        orderId: 123,
        amount: 100,
        user: {
            id: 111,
            name: 'John Doe',
            email: 'john.doe@example.com',
        },
        url: 'https://example.com/order/123',
    });
}

Отправка аддонов

Аддоны — это данные, собранные Кэтчером в конкретном фреймворке и окружении. Например, в браузере это будет информация о браузере, ОС, URL, версии приложения и др. На сервере это могут быть заголовки, параметры запроса, и т.д.

Каждый Кэтчер имеет свой набор аддонов.

Отправка событий с контекстом

Контекст — дополнительная информация, которую вы вручную прикрепляете к событию.

Бывает двух видов:

• Глобальный контекст

• Контекст конкретного события

Прикрепление контекста глобально

Глобальный контекст отправляется со всеми событиями. Он устанавливается после инициализации SDK. Например, сюда можно прикрепить информацию о текущей конфигурации приложения.

Пример из JavaScript SDK:

const hawk = new HawkCatcher({
  token: 'YOUR_INTEGRATION_TOKEN',
  context: {
    appName: 'My App',
    appEnvironment: 'development',
    isAdblockEnabled: true,
  },
});

Прикрепление контекста к конкретному событию

Можно передавать уникальный контекст при вызове hawk.send().

hawk.send('❌ Ошибка при создании заказа', {
    amount: 100,
    user: {
        id: 111,
        name: 'John Doe',
        email: 'john.doe@example.com',
    },
    url: 'https://example.com/order/123',
});

Прикрепление пользователя

Позволяет передавать информацию о текущем пользователе: id, имя, email.

Пример из Hawk PHP SDK:

\Hawk\Catcher::get()
    ->setUser([
        'name' => 'John Doe',
        'photo' => 'https://example.com/s3/users/john-doe.jpg',
    ]);

Автоматический трекинг пользователя

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

Stack Trace

Стек трейс (Stack Trace) — это детальная информация о последовательности вызовов функций, которая привела к возникновению ошибки. Hawk SDK собирает и передаёт полный стек вызовов вместе с дополнительной информацией для максимально точной диагностики проблем.

Что включает в себя стек трейс в Хоуке:

1. Информация о файлах и строках кода:

   • Путь к файлу, где произошла ошибка

   • Номер строки и колонки, где возникла проблема

   • Имя функции или метода, в котором произошла ошибка

2. Исходный код:

   • Фрагмент кода вокруг проблемной строки (обычно 5-8 строк выше и ниже)

   • Это помогает понять контекст, в котором произошла ошибка

3. Аргументы функций:

   • Значения всех параметров, переданных в функцию на момент ошибки

   • Имена параметров (когда доступны через рефлексию)

   • Сериализованные значения переменных для анализа

4. Цепочка вызовов:

   • Полная последовательность функций от точки возникновения ошибки до корневого вызова

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

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

Привязка релиза

При инициализации SDK можно явно указать версию приложения, к которой относится событие. Это позволяет:

• Соотнести ошибку с конкретной версией приложения

• Отслеживать "качество" релизов и регрессии

• Анализировать, помог ли релиз исправить существующую ошибку

Подробнее в разделе "Релизы".

Уровень критичности события

Некоторые SDK позволяют указать уровень критичности события, которые должны отлавливаться. Это позволяет исключать неважные события из отправки.

Пример из Hawk PHP SDK:

\Hawk\Catcher::init([
  'error_types' => E_ALL & ~E_DEPRECATED
]);

Фильтрация чувствительных данных

С помощью хука beforeSend можно:

• Удалить чувствительные данные из события

• Отменить отправку события

Подробности в разделе "Фильтрация чувствительных данных".

---

12. Интеграции с логгерами

Некоторые SDK поддерживают интеграцию с логгерами. Это позволяет встроить Хоук в уже существующую логирующую систему.

Например, SDK для PHP поддерживает Monolog и другие логгеры.

---

13. Трекинг консоли браузера

JavaScript SDK имеет возможность отлавливать вывод логов в консоль браузера и прикреплять их к событиям. Это расширяет возможности отладки и помогает понять, что происходило в браузере пользователя незадолго до сбоя.

Возможности:

• Следит за console.log, console.info, console.warn, console.error

• Сохраняет до 20 последних сообщений

• Прикрепляет логи консоли к каждому событию

• Поддерживает отметки времени и тип сообщений

• Поддерживает форматирование

Мы недавно подробно рассказывали об этой фиче на Хабре.

---

14. Поддержка Sentry SDK {#sentry-support}

Хоук совместим с Sentry SDK. Это значит, что вы можете не менять уже настроенную интеграцию с Sentry, но слать ошибки в Хоук.

Для этого достаточно поменять DSN в настройках Sentry на DSN Хоука.

import * as Sentry from '@sentry/browser';

Sentry.init({
- dsn: 'https://1234567890abcdef1234567890abcdef@o123456.ingest.sentry.io/9876543',
+ dsn: 'https://3c59d1984e6646849ff59cd5e230627f7385883f29c645ae8e2a94afb2b8a281@k1.hawk.so/0'
  // ...
});

Свой DSN можно скопировать в настройках проекта на вкладке «Интеграции».

---

15. Существующие SDK

Вот список существующих SDK для различных фреймворков и языков программирования:

• JavaScript/TypeScript (Browser)

• Node.js

• React

• Vue

• Nuxt

• Webpack

• Vite

• Python

• Flask

• FastAPI

• PHP

• Symfony

• Laravel

• Go

• Android

• Kotlin

• Java

Что делать, если нет SDK для вашего фреймворка?

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

1. Использовать соответствующий Sentry SDK и поменять DSN на DSN Хоука (см. раздел "Поддержка Sentry SDK")

2. Написать команде Хоука и они помогут вам сделать SDK для вашего фреймворка

3. Самому сделать SDK для вашего фреймворка

Как самому сделать SDK для вашего фреймворка

Если нужного языка или фреймворка пока нет, вы можете написать собственный SDK (Catcher) — библиотеку, которая перехватывает ошибки и отправляет их в Хоук.

Что должен уметь кэтчер

1. Перехватывать ошибки

Подключаться к глобальным обработчикам (например, window.onerror, sys.excepthook, set_exception_handler).

2. Отправлять события в Хоук

Использовать универсальный формат события (Event Format): сообщение, стек, окружение, пользователь, контекст.

3. Передавать фрагменты кода

Если возможно, добавлять строки исходника вокруг каждой позиции стека.

4. Поддерживать ручную отправку

Метод вроде hawk.captureException(error, context) для отправки событий вручную.

5. Передавать контекст и пользователя

Контекст можно задать глобально и локально; если оба указаны — объединять.
Если пользователь не задан, генерировать user-.

6. Добавлять дополнительные данные

Через поле addons — язык, версия, PID, фреймворк и т. п.

7. Передавать версию и коммиты

Отправлять версию кэтчера, а для бэкендов — список последних коммитов из git.

8. Поддерживать уровни ошибок

Например: fatal, error, warning, info, debug.

9. Интегрироваться с логгерами

Например, Monolog (PHP), Logging (Python), Winston (JS).

Минимальный пример

import { sendEvent } from './transport.js';

export function captureException(error, context = {}) {
  const event = formatEvent(error, context);
  sendEvent(event);
}

window.onerror = (msg, src, line, col, err) => {
  captureException(err || new Error(msg));
};

Рекомендации

• Тестируйте как синхронные, так и асинхронные ошибки.

• Следите, чтобы сам кэтчер не создавал бесконечные циклы.

• Формируйте события строго по Event Format.

---

16. Self-hosted версия

Как использовать

Исходный код всех частей Хоука открыт и доступен на GitHub. Можно развернуть Хоук на своём сервере или VPS. Для удобства все сервисы собраны в моно-репозитории Hawk Mono. Инструкцию по развертыванию можно найти там же.

Почему это дороже и сложнее

На ваши плечи ложатся расходы на:

• Настройку и менеджмент базы данных, backend, frontend

• Обновление компонентов и контроль за безопасностью

• Мониторинг и поддержка работоспособности всех сервисов

• Оплату ресурсов сервера

• Оплату работы инженеров DevOps

Ограничения

Self-hosted версия не поддерживается активно — команда сосредоточена на облачном решении. На практике это может выражаться в отсутствии каких-то инструкций по определенным компонентам — придется самостоятельно изучать код и решать проблемы.

---

17. Hawk Desktop

Hawk Desktop — кроссплатформенное приложение для разработчиков. Доступно для macOS, Windows и Linux.

• Скачать: github.com/codex-team/hawk.desktop

• Проект в стадии тестирования, но уже можно использовать в повседневной работе

---

18. В будущих версиях

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

Performance monitoring

Performance Monitoring — это система мониторинга производительности приложений, которая позволяет отслеживать время выполнения операций и выявлять узкие места в работе.

Основные возможности:

1. Транзакции (Transactions) — отслеживание высокоуровневых операций. Например:

   • Загрузка страниц

   • API-вызовы

   • Маршрутизация в SPA

   • Любые пользовательские операции

2. Спаны (Spans) — детализация транзакций:

   • Время выполнения отдельных этапов операции

   • Вложенные операции внутри транзакции

   • Анализ узких мест

Группировка и агрегация транзакций:

Транзакции автоматически группируются и отправляются батчами для оптимизации:

• Транзакции с одинаковыми именами объединяются

• Рассчитываются статистические метрики (p50, p95, максимальная длительность)

• Спаны агрегируются по всем транзакциям

• Отслеживается процент неудачных операций

Можно настроить, какой процент транзакций отправлять в Hawk:

const hawk = new HawkCatcher({
  token: 'INTEGRATION_TOKEN',
  performance: {
    sampleRate: 0.2,        // Отправлять 20% транзакций
    thresholdMs: 50         // Отправлять только транзакции длиннее 50мс
  }
});

Автоматическая фильтрация транзакций:

• Порог длительности — транзакции короче thresholdMs игнорируются

• Критический порог — транзакции длиннее criticalDurationThresholdMs всегда отправляются

• Сэмплинг — случайная выборка на основе sampleRate

• Критичность — критические транзакции всегда отправляются

• Статус — неудачные транзакции всегда отправляются

API для работы с транзакциями:

// Запуск транзакции
const transaction = hawk.startTransaction('operation-name', 'critical');

// Создание спана внутри транзакции
const span = transaction.startSpan('sub-operation');

// Завершение спана
span.finish('success'); // или 'failure'

// Завершение транзакции
transaction.finish('success'); // или 'failure'

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

Аналитика крашей на мобильных платформах (iOS и Android)

Сейчас Хоук умеет отлавливать ошибки в рантайме мобильных приложений. Однако, в будущих версиях появится возможность собирать отчёты о крашах (по аналогии с Crashlytics).

Эта функция позволит:

• фиксировать аварийные завершения работы приложений на iOS и Android;

• получать подробные стектрейсы и окружение (версия ОС, модель устройства, версия приложения);

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

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

AI filtering

В будущих версиях Хоука появится AI-фильтрация событий. Она поможет командам не тратить время на шум и сосредоточиться на действительно важных ошибках.

Планируется:

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

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

• Группировка и подсветка важных — система будет объединять схожие ошибки и выводить их в приоритетный список для быстрого реагирования.

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

---

19. Заключение

Техническую реализацию всех описанных функций можно найти в репозиториях Хоука на GitHub. Если у вас есть вопросы по текущей функциональности или предложения по новым функциям, напишите письмо на почту команды Хоука. Если вам интересно следить за развитием проекта — новости публикуются в Telegram канале.

Сайт Хоука: hawk-tracker.ru
Новости проекта: https://t.me/hawk_tracker

Спасибо за внимание и желаем успехов в разработке!