diff --git a/static/llms.txt b/static/llms.txt new file mode 100644 index 0000000..23a7f5c --- /dev/null +++ b/static/llms.txt @@ -0,0 +1,1172 @@ +# Хоук — open-source трекер ошибок в ПО + +Позволяет отслеживать ошибки в веб-приложениях, API и мобильных сервисах. В этом документе описана функциональность, которая сегодня доступна пользователям Хоука — от регистрации до продвинутых SDK-функций и планов на будущее. + +--- + +## Содержание + +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](mailto:team@hawk.so) или в [Telegram](https://t.me/hawk_tracker) и пришлите данные о компании, воркспейсе и тарифном плане. + +Активация плана происходит в течение 48 часов после оплаты счета. Закрывающие документы присылаются по запросу. + +##### История операций + +В истории операций можно посмотреть платежи, связанные с воркспейсом. + +--- + +## 3. Проекты + +**Проект** — единичная интеграция внутри воркспейса для отслеживания событий от одного приложения или его части (например, «Frontend \[production]» или «Auth API»). Создайте столько проектов, сколько разных частей системы есть в вашей архитектуре. + +### Настройки проекта + +Для перехода к настройкам проекта переключитесь на нужный проект с помощью левой колонки с последними ошибками, а затем нажмите на название проекта в верхней части страницы. + +В настройках проекта можно: + +* Изменить **название** проекта; +* Загрузить **иконку** проекта; +* Использовать **лейблы** в названии: например, `[prod] Auth API` — в интерфейсе будет отображён бейдж `prod`. + +### Интеграции + +В этом разделе: + +* Отображается **Интеграционный токен** — уникальный ключ, используемый в SDK для отправки событий. Его можно **отозвать и сгенерировать заново** при необходимости. +* Доступен **Sentry DSN**, совместимый с оригинальным Sentry SDK — удобно для миграции или если у Хоука пока нет SDK для нужного фреймворка. + +### Уведомления {#notifications} + +Очень важно включить уведомления об ошибках и сделать это правильно, чтобы не пропустить важные события, и в то же время не получать спам. + +Работа над уведомлениями осуществляется с помощью **Сценариев** — правил, которые определяют, когда и как будут отправляться уведомления. Можно создать один или несколько сценариев уведомлений, основанных на разных критериях: + +* **Где получать**: 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](#sdk-features). + +### Список повторений ошибки + +Здесь можно посмотреть все данные о каждом повторении события и перейти в конкретное повторение. Полезно, когда нужно понять закономерности появления ошибки. + +### Статистика по дням + +Тут выводится график частоты появления ошибки по дням. Позволяет оценить, есть ли регрессия, помог ли фикс ошибки. + +### Действия с событием + +#### Пометить как исправленное + +Если ошибка исправлена, ее можно пометить как исправленную. Так вы будете понимать, что работы по ней закончены. Какое-то время новые ошибки еще могут приходить — это зависит от скорости разворачивания новой версии вашего сервиса на всех пользователей. Если спустя некоторое время ошибки продолжают приходить, значит, обновление не исправило проблему. + +#### Игнорировать + +Игнорирование ошибки полезно, когда она не является критической и ее исправление не планируется. У таких ошибок есть следующие особенности: + +- В списке событий они будут полупрозрачными +- Уведомления о таких ошибках не будут приходить + +#### Добавить в избранное + +Такие ошибки будут выделяться в списке событий. Это поможет быстрее найти и обратить на них внимание. + +#### Назначить исполнителя + +Можно отметить члена команды исполнителем для конкретной ошибки. Пользователь получит уведомление о назначении на почту. + +--- + +## 6. Фильтрация чувствительных данных {#data-filtering} + +Иногда в событиях могут оказаться данные, которые не должны покидать ваш сервер или устройство пользователя. Фильтрация помогает скрыть такие поля и не отправлять их в Хоук. + +Фильтрация работает на двух уровнях: + +- На стороне кэтчера (в вашем приложении, до отправки события). +- На стороне бэкенда Хоука. + +### Фильтрация на стороне кэтчера + +Если нужно удалить или изменить чувствительные поля перед отправкой события, используйте хук `beforeSend` в конфигурации кэтчера. + +Он принимает объект события, в котором можно удалить или модифицировать данные. Вы можете вернуть `false`, тогда событие не будет отправлено вовсе. + +```js +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]`: + +- значения, которые выглядят как номера банковских карт (по регулярным выражениям); +- поля, чьи названия или значения содержат следующие ключевые слова: + +#### 🛡️ Авторизация и сессии + +| Ключ | Описание | +|-------------------|--------------------------------------------------------------------------| +| `auth` | Общий ключ для авторизационной информации. | +| `authorization` | HTTP-заголовок или поле, содержащее токен авторизации. | +| `access_token` | Токен доступа, выдаваемый для авторизации в API. | +| `accesstoken` | Вариация записи `access_token`. | +| `token` | Общее название для различных типов токенов. | +| `jwt` | JSON Web Token, содержащий данные авторизации и сессии. | +| `session` | Идентификатор пользовательской сессии. | +| `sessionid` | Вариант написания идентификатора сессии. | +| `session_id` | Альтернативный стиль написания `sessionid`. | + + +#### 🔑 API ключи и секреты + +| Ключ | Описание | +|--------------------|--------------------------------------------------------------------------| +| `api_key` | Ключ для доступа к API. | +| `apikey` | Вариант записи `api_key`. | +| `x-api-key` | HTTP-заголовок с API-ключом. | +| `x-auth-token` | HTTP-заголовок с токеном авторизации. | +| `bearer` | Часто встречается в `Authorization: Bearer ` заголовках. | +| `client_secret` | Секрет клиента OAuth или других систем авторизации. | +| `secret` | Общий ключ для конфиденциальной информации. | +| `credentials` | Данные для входа: логин и пароль, токены и т. п. | + + +#### 👨‍🔧 Пароли + +| Ключ | Описание | +|--------------------|--------------------------------------------------------------------------| +| `password` | Пароль пользователя. | +| `passwd` | Сокращённый вариант `password`, часто используется в CLI или API. | +| `mysql_pwd` | Пароль для подключения к MySQL. | + + +#### 🔒 Ключи шифрования + +| Ключ | Описание | +|--------------------|--------------------------------------------------------------------------| +| `private_key` | Закрытый ключ (например, RSA, SSH). | +| `ssh_key` | SSH-ключ, используемый для авторизации на серверах. | + + +#### 💳 Платёжные данные + +| Ключ | Описание | +|--------------------|--------------------------------------------------------------------------| +| `card` | Общий объект или строка с данными карты. | +| `cardnumber` | Полный номер карты. | +| `card[number]` | Номер карты, передаваемый в объекте (например, Stripe SDK). | +| `creditcard` | Общий ключ для номера кредитной карты. | +| `credit_card` | Альтернативный стиль написания `creditcard`. | +| `pan` | Primary Account Number (номер карты). | +| `pin` | ПИН-код карты. | +| `security_code` | Код безопасности (CVV, CVC). | +| `stripetoken` | Токен карты из Stripe API. | +| `cloudpayments_public_id` | Публичный ID для CloudPayments. | +| `cloudpayments_secret` | Секретный ключ для CloudPayments. | + +#### 🔌 Конфигурации и подключения + +| Ключ | Описание | +|--------------------------|---------------------------------------------------| +| `dsn` | Data Source Name | + +#### 👤 Персональные данные + +| Ключ | Описание | +|----------|---------------------------------------------------| +| `ssn` | Social Security Number — номер соц. страхования. | + +Такая защита снижает риск утечки конфиденциальных данных даже если вы не отфильтровали их на клиентской стороне. + +--- + +## 7. Хранение событий + +События хранятся **31 день**, после чего архивируются. Срок фиксированный и не зависит от тарифа. + +Архивирование означачает, что события удалены, но продолжают учитываться в счетчиках и дате первого появления. + +--- + +## 8. Лимиты, квоты и тарифы + +Хоук предоставляет гибкую систему тарифных планов, которая позволяет выбрать оптимальный вариант в зависимости от масштаба проекта и потребностей в мониторинге ошибок. + +### Бесплатный план + +По умолчанию Хоук бесплатный. Ограничение — 1000 событий в месяц. Ограничений по функциональности нет. + +Подходит для большинства стартапов, учебных проектов, пет-проектов, экспериментов и тестирования интеграции. + +### Тарифные планы + +Актуальные характеристики и стоимость тарифов опубликованы на сайте Хоука: [https://hawk-tracker.ru](https://hawk-tracker.ru?utm_source=big-guide) + +Способы оплаты: + +- Привязка карты +- Разовый платеж с карты +- СБП (разовый и подписка) +- Выставление счета + +Все способы подходят как для физических, так и для юридических лиц. Подробнее в разделе "Платежи". + +**Преимущества платных планов:** + +- Увеличенный лимит событий +- Помощь с интеграцией и настройкой +- Приоритетная техническая поддержка +- Возможность установить Рейт Лимиты (см. раздел 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. Релизы {#releases} + +Релизы в Хоуке — это механизм, который связывает события (ошибки, логи) с конкретной версией вашего приложения. + +Информацию о новом релизе нужно отправлять в Хоук каждый раз, когда вы выкатываете новую версию приложения — например, после деплоя или сборки. + +Это позволяет: + +- связать ошибки именно с той версией кода, где они возникли; +- корректно отобразить 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 и коммитами при сборке проекта. + +```js +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](https://github.com/codex-team/hawk.webpack.plugin) + +#### Vite Plugin + +Инструкция по использованию плагина для Vite: [@hawk.so/vite-plugin](https://github.com/codex-team/hawk.vite.plugin) + +```js +import hawkVitePlugin from '@hawk.so/vite-plugin'; + +export default defineConfig({ + plugins: [ + ..., + hawkVitePlugin({ + token: '' // Your project's Integration Token + }) + ] +}) +``` + +### Commits + +Коммиты — это информация о последних git-коммитах в релизе. Подозрительные коммиты будут отображаться в обзоре события. Так у вас будет больше информации о причине появления ошибки. + +Отправлять коммиты можно следующими способами: + +- С помощью [@hawk.so/webpack-plugin](https://github.com/codex-team/hawk.webpack.plugin) +- Вручную +- Через GitHub Actions + +#### Ручная отправка коммитов в Хоук + +Отправить коммиты для релиза можно, например, с помощью shell-скрипта из репозитория hawk.releases: [hawk.releases](https://github.com/codex-team/hawk.releases) + +``` +$ ./commits.sh --release="Version 2.0.1" --token=eyJ...integrationToken... +``` + +#### Отправка коммитов через GitHub Actions + +У Хоука есть специальный Action для GitHub Actions, который отправляет коммиты для релиза: [codex-team/hawk.releases@v1](https://github.com/marketplace/actions/hawk-release-sender) + +``` +- 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-features} + +SDK в Хоуке называются Кэтчерами. Это небольшие библиотеки, которые вы интегрируете в код приложения для отправки событий в Хоук. + +### Глобальный отлов ошибок + +Основная функция SDK — это глобальный отлов ошибок в приложении и отправка их в Хоук вместе с дополнительно собранной информацией, которая может помочь в отладке. + +Некоторые SDK Хоука позволяют отключить глобальный отлов ошибок. Например, когда у них есть свой механизм отлова ошибок. + +### Ручная отправка ошибок и логов + +Все Кэтчеры также поддерживают ручную отправку событий. С помощью нее можно трекать обработанные в try-catch ошибки, отправлять логи, отслеживать события вручную. + +Например, можно с помощью Хоука слать себе в Telegram уведомление (см. раздел "[Уведомления](#notifications)"), когда пользователь осуществил заказ на сайте: + +```js +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: + +```js +const hawk = new HawkCatcher({ + token: 'YOUR_INTEGRATION_TOKEN', + context: { + appName: 'My App', + appEnvironment: 'development', + isAdblockEnabled: true, + }, +}); +``` + +#### Прикрепление контекста к конкретному событию + +Можно передавать уникальный контекст при вызове `hawk.send()`. + +```js +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: + +```php +\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 можно явно указать версию приложения, к которой относится событие. Это позволяет: + +- Соотнести ошибку с конкретной версией приложения +- Отслеживать "качество" релизов и регрессии +- Анализировать, помог ли релиз исправить существующую ошибку + +Подробнее в разделе "[Релизы](#releases)". + +### Уровень критичности события + +Некоторые SDK позволяют указать уровень критичности события, которые должны отлавливаться. Это позволяет исключать неважные события из отправки. + +Пример из Hawk PHP SDK: + +```php +\Hawk\Catcher::init([ + 'error_types' => E_ALL & ~E_DEPRECATED +]); +``` + +### Фильтрация чувствительных данных + +С помощью хука `beforeSend` можно: + +- Удалить чувствительные данные из события +- Отменить отправку события + +Подробности в разделе "[Фильтрация чувствительных данных](#data-filtering)". + +--- + +## 12. Интеграции с логгерами + +Некоторые SDK поддерживают интеграцию с логгерами. Это позволяет встроить Хоук в уже существующую логирующую систему. + +Например, SDK для PHP поддерживает [Monolog](https://github.com/codex-team/hawk.symfony?tab=readme-ov-file#configuration) и другие логгеры. + +--- + +## 13. Трекинг консоли браузера + +JavaScript SDK имеет возможность отлавливать вывод логов в консоль браузера и прикреплять их к событиям. Это расширяет возможности отладки и помогает понять, что происходило в браузере пользователя незадолго до сбоя. + +**Возможности:** + +- Следит за console.log, console.info, console.warn, console.error +- Сохраняет до 20 последних сообщений +- Прикрепляет логи консоли к каждому событию +- Поддерживает отметки времени и тип сообщений +- Поддерживает форматирование + +--- + +## 14. Поддержка Sentry SDK {#sentry-support} + +Хоук совместим с Sentry SDK. Это значит, что вы можете не менять уже настроенную интеграцию с Sentry, но слать ошибки в Хоук. + +Для этого достаточно поменять DSN в настройках Sentry на DSN Хоука. + +```js +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)](https://github.com/codex-team/hawk.javascript) +- [Node.js](https://github.com/codex-team/hawk.nodejs) +- [React](https://github.com/codex-team/hawk.javascript?tab=readme-ov-file#usage-in-react-project) +- [Vue](https://github.com/codex-team/hawk.javascript?tab=readme-ov-file#integrate-to-vue-application) +- [Nuxt](https://github.com/codex-team/hawk.nuxt) +- [Webpack](https://github.com/codex-team/hawk.webpack.plugin) +- [Vite](https://github.com/codex-team/hawk.vite.plugin) +- [Python](https://github.com/codex-team/hawk.python) +- [Flask](https://github.com/codex-team/hawk.python/blob/master/docs/flask.md) +- [FastAPI](https://github.com/codex-team/hawk.python/blob/master/docs/fastapi.md) +- [PHP](https://github.com/codex-team/hawk.php) +- [Symfony](https://github.com/codex-team/hawk.symfony) +- [Laravel](https://github.com/codex-team/hawk.laravel) +- [Go](https://github.com/codex-team/hawk.go) +- [Android](https://github.com/codex-team/hawk.android.catcher/) +- [Kotlin](https://github.com/codex-team/hawk.kotlin) +- [Java](https://github.com/codex-team/hawk.java) + +### Что делать, если нет SDK для вашего фреймворка? + +Если вы не нашли SDK для вашего фреймворка, можно действовать тремя способами: + +1. Использовать соответствующий Sentry SDK и поменять DSN на DSN Хоука (см. раздел "[Поддержка Sentry SDK](#sentry-support)") +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). + +#### Минимальный пример + +```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](https://docs.hawk.so/event-format). + +--- + + +## 16. Self-hosted версия + +### Как использовать + +Исходный код всех частей Хоука открыт и доступен на GitHub. Можно развернуть Хоук на своём сервере или VPS. Для удобства все сервисы собраны в моно-репозитории [Hawk Mono](https://github.com/codex-team/hawk.mono). Инструкцию по развертыванию можно найти там же. + +### Почему это дороже и сложнее + +На ваши плечи ложатся расходы на: + +* Настройку и менеджмент базы данных, backend, frontend +* Обновление компонентов и контроль за безопасностью +* Мониторинг и поддержка работоспособности всех сервисов +* Оплату ресурсов сервера +* Оплату работы инженеров DevOps + +### Ограничения + +Self-hosted версия **не поддерживается активно** — команда сосредоточена на облачном решении. На практике это может выражаться в отсутствии каких-то инструкций по определенным компонентам — придется самостоятельно изучать код и решать проблемы. + +--- + +## 17. Hawk Desktop + +**Hawk Desktop** — кроссплатформенное приложение для разработчиков. Доступно для macOS, Windows и Linux. + +* **Скачать**: [github.com/codex-team/hawk.desktop](https://github.com/codex-team/hawk.desktop) +* Проект в стадии тестирования, но уже можно использовать в повседневной работе + +--- + +## 18. В будущих версиях + +Команда Хоука активно собирает фидбэк по текущим возможностям и пожелания по новым функциям. Большинство пожеланий пользователей уже было реализовано за последние месяцы. Ниже перечислены новые фичи, которые уже запланированы в дорожной карте. + +### Performance monitoring + +**Performance Monitoring** — это система мониторинга производительности приложений, которая позволяет отслеживать время выполнения операций и выявлять узкие места в работе. + +**Основные возможности:** + +1. **Транзакции (Transactions)** — отслеживание высокоуровневых операций. Например: + - Загрузка страниц + - API-вызовы + - Маршрутизация в SPA + - Любые пользовательские операции + +2. **Спаны (Spans)** — детализация транзакций: + - Время выполнения отдельных этапов операции + - Вложенные операции внутри транзакции + - Анализ узких мест + +**Группировка и агрегация транзакций:** + +Транзакции автоматически группируются и отправляются батчами для оптимизации: + +- Транзакции с одинаковыми именами объединяются +- Рассчитываются статистические метрики (p50, p95, максимальная длительность) +- Спаны агрегируются по всем транзакциям +- Отслеживается процент неудачных операций + +Можно настроить, какой процент транзакций отправлять в Hawk: + +```javascript +const hawk = new HawkCatcher({ + token: 'INTEGRATION_TOKEN', + performance: { + sampleRate: 0.2, // Отправлять 20% транзакций + thresholdMs: 50 // Отправлять только транзакции длиннее 50мс + } +}); +``` + +**Автоматическая фильтрация транзакций:** + +- **Порог длительности** — транзакции короче `thresholdMs` игнорируются +- **Критический порог** — транзакции длиннее `criticalDurationThresholdMs` всегда отправляются +- **Сэмплинг** — случайная выборка на основе `sampleRate` +- **Критичность** — критические транзакции всегда отправляются +- **Статус** — неудачные транзакции всегда отправляются + +**API для работы с транзакциями:** + +```javascript +// Запуск транзакции +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 канале](https://t.me/hawk_tracker). +