Как создать свой кэтчер для Хоука

Если вы читаете эту статью, значит хотите создать собственный модуль Catcher — библиотеку для отправки ошибок в Хоук. Это может понадобиться, если:

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

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

Требования к функциональности

Ниже перечислены базовые возможности, которые должен поддерживать любой кэтчер.

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

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

Например:

в JavaScript это window.onerror, window.onunhandledrejection;
в Python — sys.excepthook;
в PHP — set_exception_handler и register_shutdown_function.

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

Все события отправляются в Хоук в универсальном формате события (Event Format).

Это JSON-структура, включающая:

описание ошибки (тип, сообщение, стек);
окружение (версия, платформа, язык);
пользователя;
контекст (произвольные данные).

Документация по Event Format описывает обязательные и дополнительные поля, которые должен формировать кэтчер.

3. Отправка фрагментов кода для каждой строки Stacktrace

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

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

4. Ручная отправка событий

Кэтчер должен предоставлять публичный метод для ручной отправки событий, например:

hawk.captureException(error, context)

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

5. Контекстные данные

Пользователь должен иметь возможность передать объект контекста с произвольными данными (например, ID запроса, тип клиента, состояние приложения).

Контекст может быть задан:

глобально при инициализации кэтчера;
локально при ручной отправке события.

Если контекст указан в обоих случаях, они должны объединяться.

Для прикрепления глобального контекста удобно предоставить метод setContext(), который можно вызвать после инициализации Кэтчера.

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

Если пользователь не указан, кэтчер должен сгенерировать уникальный идентификатор (например, user-<uuid>), чтобы Хоук мог считать метрику Affected Users.

Пример:

"user": { "id": "42", "email": "admin@example.com", "name": "Admin" }

7. Поле adding

Кэтчер может добавлять в событие языкоспецифичные данные через поле addons.

Например:

версия библиотеки,
путь к исходному файлу,
информация о процессе (PID, uptime),
версия фреймворка и т. д.

8. Значения переменных

Если возможно, кэтчер должен извлекать значения локальных переменных из стека и передавать их в Хоук. Это особенно полезно для бэкенд-языков (Python, Go, PHP).

9. Отправка собственной версии кэтчера

Кэтчер должен передавать свою версию в каждом событии.

Это используется для связывания событий с исходными картами (source maps) и подозрительными коммитами (suspected commits).

10. Подозрительные коммиты

Если кэтчер работает на стороне сервера, он может автоматически отправлять список подозрительных коммитов, используя git diff.

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

11. Уровни ошибок

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

fatal, error, warning, info, debug.

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

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

Примеры:

PHP — Monolog
Python — Logging
Go — Zerolog
JavaScript — Winston, Bunyan

Это позволит отправлять сообщения в Хоук прямо из логгера, без ручного вызова API.

Пример структуры проекта Catcher

my-catcher/ ├── src/ │ ├── index.js │ ├── transport.js │ ├── context.js │ └── utils/ │ └── stacktrace.js ├── package.json ├── README.md └── LICENSE

Заключение

Создание собственного кэтчера — это способ добавить поддержку Хоука в любой язык или систему.

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