# Hawk — open-source error tracker f Allows you to track errors in web applications, APIs, and mobile services. This document describes the functionality currently available to Hawk users — from registration to advanced SDK features and the roadmap. --- ## Table of Contents 1. Account - Sign-in methods - Account settings - Interface language - General settings - Hawk notifications 2. Organizing your workspace - Workspaces - Workspace settings - Team management - Inviting to a team - via email - via link - Access management - Roles - Leave a workspace - Payments - Card payment (recommended) - Auto-renewal - One-time payments - SBP payment - Invoice payment - Transaction history 3. Projects - Project settings - Integrations - Integration Token - Sentry DSN - Notifications - Scenario configuration - Where to receive - Telegram - Slack - Email - What to receive - Only new - By frequency of occurrence - Filters - Include events containing text - Exclude events containing text - Event grouping - Patterns for grouping errors 4. Event list - Application health chart - Filters and sorting - All - Favorites - Resolved - Unresolved - Ignored - Sorting - By date - By number of occurrences - By number of affected users - Search - By error title - By file names in stack trace - By context - By Addons - Grouping by day 5. Events in Hawk - Event information - Error title (text, message) - File and line - First seen / date - Number of occurrences - Number of affected users - Stack trace - Code snippet - Addons - Context - List of users who encountered the error - Addons — data collected by SDK - Event context — attach data manually to an event - List of event occurrences - Daily stats - Actions with an event - Mark as resolved - Ignore - Add to favorites - Assign assignee 6. Sensitive data filtering - Client-side (catcher) filtering - Backend-side filtering - Authorization and sessions - API keys and secrets - Passwords - Encryption keys - Payment data - Configurations and connections - Personal data 7. Event retention 8. Limits, quotas, and plans - Free plan - Paid plans - Billing period - Exceeding limits - Strategies for managing limits 9. Rate Limits - Per workspace - Per project 10. Releases - How to use releases - Source Maps - Webpack Plugin - Vite Plugin - Commits - Manually sending commits to Hawk - Sending commits via GitHub Actions 11. SDK capabilities - Global error capturing - Manual sending of errors and logs - Sending addons - Sending events with context - Attaching context globally - Attaching context to a specific event - Attaching a user - Automatic user tracking - Stack Trace - Release attachment - Event severity level - Sensitive data filtering 12. Logger integrations 13. Browser console tracking 14. Sentry SDK support 15. Existing SDKs - JavaScript/TypeScript (Browser) - Node.js - React - Vue - Nuxt - Webpack - Vite - Python - Flask - FastAPI - PHP - Symfony - Laravel - Go - Android - Kotlin - Java - What if there's no SDK for your framework? - How to build your own SDK for your framework 16. Self-hosted version - How to use - Why it is more expensive and complex - Limitations 17. Hawk Desktop 18. In future versions - Performance monitoring - Mobile crash analytics (iOS and Android) - AI filtering 19. Conclusion --- ## 1. Account ### Sign-in methods Hawk supports sign-in via email only. After registration, a password is sent to the specified email. You can change it later in account settings. ### Account settings Available in account settings: * **Interface language**: Russian and English are supported; * **General settings**: name, email, password; * **Hawk notifications**: enable or disable email notifications about events and limits. --- ## 2. Organizing your workspace ### Workspaces A workspace is a logical unit where you work on projects (different integrations). For example, a workspace represents a company or team, and projects represent frontend, backend, internal services. Each user can create multiple workspaces. ### Workspace settings In settings, you can set the workspace name and manage team members. Access to plan management, payments, and limits is in the “Payments” section. ### Team management You can invite members by email or via a link. Team members have two roles: * **Administrator**: manages payments and assigns new administrators. * **Member**: views projects and events, invites new members, assigns assignees, marks errors as resolved/ignored. **Important**: if there is only one administrator in the workspace, they cannot leave the team until another administrator is assigned. ### Leave a workspace A user can leave a workspace if they are not the only administrator. ### Payments The “Payments” section is used to manage the workspace plan. If the free plan is insufficient, choose a suitable plan and pay in one of two ways: - Card or SBP — suitable for businesses and individuals. Convenient for smaller plans. - Invoice — suitable for businesses. Better for larger plans. #### Card payment (recommended) Advantages of card payment: - Plan activation happens instantly after payment. - A receipt is sent by email. It can be used for accounting. An act can be provided upon request. - All operations are displayed in the transaction history, which is convenient for accounting. - Plan renewal occurs automatically, so the workspace will not be blocked unexpectedly. ##### Auto-renewal On the first payment, the card is stored by the CloudPayments payment provider. Hawk does not store card data. You can disable Auto-renewal at any time in payment settings, which unlinks the card. ##### One-time payments With a one-time card payment, the plan will be activated for 1 month; after that, you will need to pay again. ##### SBP payment In the payment method window, select “SBP” to get a QR code for payment. Auto-renewal and one-time payments are also available with this option. #### Invoice payment For larger plans, invoice payment may be more convenient. To request an invoice, contact support at [team@hawk.so](mailto:team@hawk.so) or via [Telegram](https://t.me/hawk_tracker) and send your company, workspace, and plan details. Plan activation occurs within 48 hours after the invoice is paid. Closing documents are provided upon request. ##### Transaction history You can view payments related to the workspace in the transaction history. --- ## 3. Projects A **project** is a single integration within a workspace for tracking events from one application or its part (for example, “Frontend [production]” or “Auth API”). Create as many projects as there are different parts in your system architecture. ### Project settings To open project settings, switch to the desired project using the left column with recent errors, then click the project name at the top of the page. You can: * Change the project **name**; * Upload a project **icon**; * Use **labels** in the name: for example, `[prod] Auth API` — a `prod` badge will be displayed in the interface. ### Integrations In this section: * The **Integration Token** is displayed — a unique key used in SDKs to send events. It can be **revoked and regenerated** if needed. * The **Sentry DSN** is available and compatible with the original Sentry SDK — useful for migration or if Hawk does not yet have an SDK for your framework. ### Notifications {#notifications} It is very important to enable error notifications properly so as not to miss critical events while avoiding noise. Notifications are configured via **Scenarios** — rules that determine when and how notifications are sent. You can create one or multiple notification scenarios based on different criteria: * **Where to receive**: Telegram, Slack, Email; * **What to receive**: Only new events, by frequency of occurrence; * **Filters**: by error text, include or exclude keywords; Examples: - If a **new** error occurs containing the word "Payment", send a notification to Email - If a backend error occurs more than 500 times within 5 minutes, send a notification to the developers' Telegram chat - Send errors containing "Auth" to a special channel ### Event grouping Events in Hawk are grouped only in two cases: - When the error titles are identical - By custom patterns To configure pattern-based grouping, go to project settings and in the “Event grouping” section add patterns using regular expressions. Example regular expression for grouping errors with different titles caused by the same issue: ``` SyntaxError: Unexpected token .* in JSON at position .* ``` --- ## 4. Event list ### Application health chart At the top, there is a chart of the number of errors by day. It allows you to visually assess the dynamics of project updates. ### Filters and sorting The following event filters are available: - All - Favorites - Resolved - Unresolved - Ignored Sorting options: - By date - By number of occurrences - By number of affected users ### Search Search in the event list matches by: * Error title; * File names in the stack trace; * Data attached to the event (context); * Addons (SDK-specific data). **Example**: find all errors related to user `userId: 12345`. ``` {"userId":12345} ``` ### Grouping by day Events in the list are grouped by day. That is, one error can be displayed on several days if it recurred across multiple days. Counters here show the number of occurrences and affected users per day. --- ## 5. Events in Hawk ### Event information Each event contains the following information: * Error title (text, message) * File and line where the error occurred * First seen date * Date of the currently viewed occurrence * Total number of occurrences * Number of unique users who encountered the error * Stack trace of the function calls where the error occurred * Code snippet around the error for each file in the stack trace * **Addons** — additional data automatically collected by the SDK (for example, URL, browser, OS version); * **Context** — data attached manually (for example, user ID, current screen); * List of users who encountered the error ### Addons Addons are additional data automatically collected by the SDK. For example, the Hawk JavaScript SDK adds information on URL, browser, OS version, device. Each catcher (SDK) adds its own addons depending on the platform. ### Event context Events can be enriched with your own data, attached manually in two ways: - globally (attached to every event) - specific to a single event See [SDK capabilities](#sdk-features). ### List of event occurrences Here you can view all data for each event occurrence and navigate to a specific occurrence. Useful for understanding error patterns. ### Daily statistics Displays a chart of error frequency by day. Helps evaluate regression and whether a fix helped. ### Actions with an event #### Mark as resolved If an error has been fixed, it can be marked as resolved. This way you know that the work is complete. New errors may still come for some time — it depends on how quickly the new version of your service rolls out to all users. If errors continue after some time, the update likely did not fix the issue. #### Ignore Ignoring an error is useful when it is not critical and will not be addressed. Such errors have the following characteristics: - They will appear semi-transparent in the event list - Notifications about such errors will not be sent #### Add to favorites These errors will be highlighted in the event list to make them easier to find and focus on. #### Assign assignee You can assign a team member to a specific error. The user will receive an email notification about the assignment. --- ## 6. Sensitive data filtering {#data-filtering} Sometimes events may contain data that should not leave your server or a user's device. Filtering helps hide such fields and prevents them from being sent to Hawk. Filtering works on two levels: - On the catcher (client) side — in your application, before sending the event. - On Hawk's backend side. ### Client-side filtering If you need to remove or modify sensitive fields before sending an event, use the `beforeSend` hook in the catcher's configuration. It receives the event object, where you can delete or modify data. You can return `false` to drop the event entirely. ```js const hawk = new HawkCatcher({ token: 'YOUR_INTEGRATION_TOKEN', beforeSend(event) { // Remove Authorization header if (event.payload.context.request?.headers?.Authorization) { delete event.payload.context.headers.Authorization; } // To cancel sending, return false if (event.title.startsWith('Script Error.')) { return false; } return event; } }); ``` ### Backend-side filtering Additionally, Hawk filters potentially dangerous data on its side. The following data will be replaced with `[filtered]`: - Values that look like credit card numbers (by regular expressions); - Fields whose names or values contain the following keywords: #### 🛡️ Authorization and sessions | Key | Description | |-------------------|----------------------------------------------------------------------------| | `auth` | General key for authorization-related information. | | `authorization` | HTTP header or field containing an authorization token. | | `access_token` | Access token issued for API authorization. | | `accesstoken` | Variation of `access_token`. | | `token` | General name for various types of tokens. | | `jwt` | JSON Web Token containing authorization and session data. | | `session` | User session identifier. | | `sessionid` | Alternate spelling of session identifier. | | `session_id` | Alternative style of writing `sessionid`. | #### 🔑 API keys and secrets | Key | Description | |--------------------|----------------------------------------------------------------------------| | `api_key` | API access key. | | `apikey` | Variation of `api_key`. | | `x-api-key` | HTTP header with API key. | | `x-auth-token` | HTTP header with authorization token. | | `bearer` | Often found in `Authorization: Bearer ` headers. | | `client_secret` | OAuth client secret or other auth system secrets. | | `secret` | General key for confidential information. | | `credentials` | Login credentials: username/password, tokens, etc. | #### 👨‍🔧 Passwords | Key | Description | |--------------------|----------------------------------------------------------------------------| | `password` | User password. | | `passwd` | Abbreviated variant of `password`, often used in CLI or APIs. | | `mysql_pwd` | Password for connecting to MySQL. | #### 🔒 Encryption keys | Key | Description | |--------------------|----------------------------------------------------------------------------| | `private_key` | Private key (e.g., RSA, SSH). | | `ssh_key` | SSH key used for server authorization. | #### 💳 Payment data | Key | Description | |---------------------------|----------------------------------------------------------------------| | `card` | General object or string with card data. | | `cardnumber` | Full card number. | | `card[number]` | Card number passed in an object (e.g., Stripe SDK). | | `creditcard` | General key for a credit card number. | | `credit_card` | Alternative style of writing `creditcard`. | | `pan` | Primary Account Number (card number). | | `pin` | Card PIN code. | | `security_code` | Security code (CVV, CVC). | | `stripetoken` | Card token from Stripe API. | | `cloudpayments_public_id` | Public ID for CloudPayments. | | `cloudpayments_secret` | Secret key for CloudPayments. | #### 🔌 Configurations and connections | Key | Description | |--------|------------------------| | `dsn` | Data Source Name | #### 👤 Personal data | Key | Description | |-------|----------------------------------------------| | `ssn` | Social Security Number. | This protection reduces the risk of confidential data leakage even if you did not filter it on the client side. --- ## 7. Event retention Events are stored for **31 days**, after which they are archived. The period is fixed and does not depend on the plan. Archiving means events are deleted, but they continue to be counted in metrics and the first-seen date. --- ## 8. Limits, quotas, and plans Hawk provides a flexible system of plans to choose the optimal option depending on project scale and error monitoring needs. ### Free plan By default, Hawk is free. The limit is 1000 events per month. There are no feature limitations. Suitable for most startups, educational projects, pet projects, experiments, and integration testing. ### Paid plans Current plan specs and pricing are published on the Hawk website: [https://hawk-tracker.ru](https://hawk-tracker.ru?utm_source=big-guide) Payment methods: - Linked card - One-time card payment - SBP (one-time and subscription) - Invoice All methods are suitable for individuals and legal entities. See the "Payments" section for details. **Advantages of paid plans:** - Increased event limits - Help with integration and setup - Priority technical support - Ability to set Rate Limits (see the Rate Limits section) to protect against spikes - Ability to request feature improvements, influence the roadmap, request new SDKs - Closing documents, receipts, acts ### Billing period Also known as the Payment period. It is 1 month. It starts from the moment of registration or plan update. At the end of the period, the event counter resets. **For paid plans:** - If a subscription is active, the next period is charged at the end of the current one. - In case of a one-time payment, 3, 2, 1, and 0 days before the end of the period, the team receives an email notification to pay for the next month. - If payment is not made, the workspace remains unblocked for 3 days. If payment is still not made, the workspace is blocked. ### Exceeding limits **What happens when the limit is reached:** - **Notifications**: the team receives an email when 95% of the limit is consumed. A notification is also sent at the moment the workspace is blocked. - **Blocking moment**: events stop being accepted within an hour after reaching the limit. - **Restoration**: events start being accepted again either when switching to a higher plan, or when paying again for the current plan (resetting the counter and updating the billing period), or at the start of the next month (for the free plan). ### Strategies for managing limits To avoid workspace blocking, we recommend the following strategies: - **Usage monitoring**: the current event consumption is displayed in Hawk's interface, helping track usage and plan costs. - **Fixing errors**: of course, the main thing is to fix critical errors in time. - **Event filtering**: to exclude unimportant errors, use the `beforeSend` hook on the catcher side. See "SDK capabilities" for details. - **Rate Limiting**: set limits on the number of events per unit of time. See "Rate Limits" for details. --- ## 9. Rate Limits Rate limits help protect against spikes — a sharp increase in the number of events per unit of time, which can be caused by: - A critical error occurring for many users at once - Malicious user actions, e.g., botting, DDoS, mass actions - Error loops - Failures of external or internal services With rate limits, you can set the maximum number of events per unit of time that Hawk will accept. The rest will be dropped. This protects you from consuming your plan due to spikes. Features: - Can be set per workspace and per project. - Available only for paid plans. --- ## 10. Releases {#releases} Releases in Hawk link events (errors, logs) to a specific version of your application. You should send release information to Hawk every time you roll out a new version of your application — for example, after deployment or build. This allows you to: - Link errors to the exact code version where they occurred - Correctly display stack traces using source maps - Show a list of recent commits in the event overview to help find the cause faster Linking events to specific releases is an important debugging tool. For client integrations, this is practically mandatory — otherwise you'll see minified code and shortened function names, which makes debugging very difficult. A release includes: * Version name (e.g., `1.0.3`) * List of commits (optional) * Source Maps ### How to use releases To enable releases, follow two steps: - Configure sending releases using the Webpack or Vite plugins (see below) - Pass the release id when initializing Hawk SDK. The id is generated automatically by the plugins or set manually. ### Source Maps For client projects (JavaScript, TypeScript, React, Vue, etc.), configure sending Source Maps. This way, when viewing error information, you'll see the original code and function names. #### Webpack Plugin The plugin sends releases with Source Maps and commits during project build. ```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', } ``` See detailed instructions in the readme [@hawk.so/webpack-plugin](https://github.com/codex-team/hawk.webpack.plugin) #### Vite Plugin Usage instructions for the Vite plugin: [@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 Commits contain information about recent git commits in the release. Suspicious commits are displayed in the event overview, giving you more context on the cause. You can send commits using: - [@hawk.so/webpack-plugin](https://github.com/codex-team/hawk.webpack.plugin) - Manually - GitHub Actions #### Manually sending commits to Hawk You can send commits for a release using a shell script from the hawk.releases repo: [hawk.releases](https://github.com/codex-team/hawk.releases) ``` $ ./commits.sh --release="Version 2.0.1" --token=eyJ...integrationToken... ``` #### Sending commits via GitHub Actions Hawk provides a GitHub Action to send release commits: [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 capabilities {#sdk-features} Hawk SDKs are called Catchers. These are small libraries that you integrate into your application's code to send events to Hawk. ### Global error capturing The primary function of an SDK is to capture errors globally in your application and send them to Hawk along with additional information that can help with debugging. Some Hawk SDKs allow disabling global error capturing, for example, when there is a custom error handling mechanism. ### Manual sending of errors and logs All Catchers also support manually sending events. Use this to track errors handled in try-catch, send logs, and track custom events. For example, you can use Hawk to send yourself a Telegram notification (see the "[Notifications](#notifications)" section) when a user places an order on the website: ```js import HawkCatcher from '@hawk.so/javascript'; // You can store the catcher instance as a singleton const hawk = new HawkCatcher({ token: 'YOUR_INTEGRATION_TOKEN', }); // Function called when an order is created function onOrderCreated() { hawk.send('💰 New order created', { orderId: 123, amount: 100, user: { id: 111, name: 'John Doe', email: 'john.doe@example.com', }, url: 'https://example.com/order/123', }); } ``` ### Sending addons Addons are the data collected by a Catcher for a specific framework and environment. For example, in the browser, this includes browser, OS, URL, app version, etc. On the server, it may include headers, request parameters, etc. Each Catcher has its own set of addons. ### Sending events with context Context is additional information that you manually attach to an event. There are two types: - Global context - Event-specific context #### Attaching context globally Global context is sent with all events. It is set after initializing the SDK. For example, you can attach current app configuration information. JavaScript SDK example: ```js const hawk = new HawkCatcher({ token: 'YOUR_INTEGRATION_TOKEN', context: { appName: 'My App', appEnvironment: 'development', isAdblockEnabled: true, }, }); ``` #### Attaching context to a specific event You can pass unique context when calling `hawk.send()`. ```js hawk.send('❌ Error creating order', { amount: 100, user: { id: 111, name: 'John Doe', email: 'john.doe@example.com', }, url: 'https://example.com/order/123', }); ``` ### Attaching a user Allows you to pass information about the current user: id, name, email. Example from Hawk PHP SDK: ```php \Hawk\Catcher::get() ->setUser([ 'name' => 'John Doe', 'photo' => 'https://example.com/s3/users/john-doe.jpg', ]); ``` #### Automatic user tracking Some SDKs can distinguish unique users even without manual attachment. This anonymized information is used to count the number of unique affected users. ### Stack Trace **Stack Trace** is detailed information about the sequence of function calls that led to an error. Hawk SDK collects and transmits the full call stack along with additional information for accurate diagnostics. **What Hawk stack traces include:** 1. **File and line information:** - Path to the file where the error occurred - Line and column numbers - Function or method name where the error occurred 2. **Source code:** - A code snippet around the problematic line (usually 5-8 lines above and below) - Helps understand the context of the error 3. **Function arguments:** - Values of parameters passed to the function at error time - Parameter names (when available via reflection) - Serialized variable values for analysis 4. **Call chain:** - Full sequence of functions from the error to the root call - Helps trace the entire execution path This information is critical for quick diagnosis and fixing of errors as it shows not only where the problem occurred, but under what conditions. ### Release attachment When initializing the SDK, you can explicitly specify the application version related to the event. This allows you to: - Associate the error with a specific app version - Track the "quality" of releases and regressions - Analyze whether a release helped fix an existing error See the "[Releases](#releases)" section for details. ### Event severity level Some SDKs allow you to specify the severity level of events to be captured. This helps exclude unimportant events from being sent. Example from Hawk PHP SDK: ```php \Hawk\Catcher::init([ 'error_types' => E_ALL & ~E_DEPRECATED ]); ``` ### Sensitive data filtering Using the `beforeSend` hook you can: - Remove sensitive data from an event - Cancel sending the event Details in the "[Sensitive data filtering](#data-filtering)" section. --- ## 12. Logger integrations Some SDKs support integration with loggers. This allows you to embed Hawk into existing logging systems. For example, the PHP SDK supports [Monolog](https://github.com/codex-team/hawk.symfony?tab=readme-ov-file#configuration) and other loggers. --- ## 13. Browser console tracking The JavaScript SDK can intercept browser console output and attach it to events. This extends debugging capabilities and helps understand what happened in the user's browser shortly before the failure. **Capabilities:** - Monitors console.log, console.info, console.warn, console.error - Stores up to 20 latest messages - Attaches console logs to each event - Supports timestamps and message types - Supports formatting --- ## 14. Sentry SDK support {#sentry-support} Hawk is compatible with the Sentry SDK. This means you can keep your existing Sentry integration but send errors to Hawk. To do this, just change the DSN in Sentry settings to Hawk's 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' // ... }); ``` You can copy your DSN in the project settings on the “Integrations” tab. --- ## 15. Existing SDKs Here is a list of existing SDKs for various frameworks and programming languages: - [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) ### What if there's no SDK for your framework? If you did not find an SDK for your framework, you can: 1. Use the corresponding Sentry SDK and change DSN to Hawk's DSN (see "[Sentry SDK support](#sentry-support)") 2. Write to the Hawk team — they will help create an SDK for your framework 3. Build your own SDK for your framework ### How to build your own SDK for your framework If the required language or framework is not available, you can write your own SDK (Catcher) — a library that intercepts errors and sends them to Hawk. #### What a catcher should be able to do 1. **Capture errors** Connect to global handlers (e.g., window.onerror, sys.excepthook, set_exception_handler). 2. **Send events to Hawk** Use a universal event format: message, stack, environment, user, context. 3. **Provide code snippets** If possible, include lines of source around each stack position. 4. **Support manual sending** Provide a method like hawk.captureException(error, context) to send events manually. 5. **Pass context and user** Context can be set globally and locally; if both are specified — merge them. If the user is not specified, generate user-. 6. **Add additional data** Via the addons field — language, version, PID, framework, etc. 7. **Send version and commits** Send the catcher version and, for backends, a list of recent git commits. 8. **Support error levels** For example: fatal, error, warning, info, debug. 9. **Integrate with loggers** For example, Monolog (PHP), Logging (Python), Winston (JS). #### Minimal example ```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)); }; ``` #### Recommendations - Test both synchronous and asynchronous errors. - Ensure the catcher does not cause infinite loops. - Form events strictly according to the [Event Format](https://docs.hawk.so/event-format). --- ## 16. Self-hosted version ### How to use The source code of all Hawk components is open and available on GitHub. You can deploy Hawk on your own server or VPS. For convenience, all services are collected in the mono-repository [Hawk Mono](https://github.com/codex-team/hawk.mono). Deployment instructions are available there. ### Why it is more expensive and complex You will bear costs for: * Setting up and managing the database, backend, frontend * Updating components and maintaining security * Monitoring and maintaining service uptime * Paying for server resources * Paying DevOps engineers ### Limitations The self-hosted version is **not actively supported** — the team is focused on the cloud solution. In practice, this may mean the absence of some instructions for certain components — you will need to study the code and solve issues yourself. --- ## 17. Hawk Desktop **Hawk Desktop** is a cross-platform application for developers. Available for macOS, Windows, and Linux. * **Download**: [github.com/codex-team/hawk.desktop](https://github.com/codex-team/hawk.desktop) * The project is in testing, but already usable for daily work --- ## 18. In future versions The Hawk team actively collects feedback on current capabilities and requests for new features. Most user requests have already been implemented in recent months. Below are new features already planned on the roadmap. ### Performance monitoring **Performance Monitoring** is a system that tracks application performance, allowing you to measure operation times and identify bottlenecks. **Main capabilities:** 1. **Transactions** — tracking high-level operations. For example: - Page loads - API calls - Routing in SPAs - Any custom operations 2. **Spans** — transaction details: - Execution time of individual operation stages - Nested operations within a transaction - Bottleneck analysis **Grouping and aggregating transactions:** Transactions are automatically grouped and sent in batches for optimization: - Transactions with identical names are grouped - Statistical metrics are calculated (p50, p95, max duration) - Spans are aggregated across all transactions - The percentage of failed operations is tracked You can configure what percentage of transactions to send to Hawk: ```javascript const hawk = new HawkCatcher({ token: 'INTEGRATION_TOKEN', performance: { sampleRate: 0.2, // Send 20% of transactions thresholdMs: 50 // Send only transactions longer than 50ms } }); ``` **Automatic transaction filtering:** - **Duration threshold** — transactions shorter than `thresholdMs` are ignored - **Critical threshold** — transactions longer than `criticalDurationThresholdMs` are always sent - **Sampling** — random sampling based on `sampleRate` - **Criticality** — critical transactions are always sent - **Status** — failed transactions are always sent **API for working with transactions:** ```javascript // Start a transaction const transaction = hawk.startTransaction('operation-name', 'critical'); // Create a span within the transaction const span = transaction.startSpan('sub-operation'); // Finish the span span.finish('success'); // or 'failure' // Finish the transaction transaction.finish('success'); // or 'failure' ``` Performance Monitoring will help identify slow operations, optimize application performance, and improve user experience. ## Mobile crash analytics (iOS and Android) Currently, Hawk can capture runtime errors in mobile apps. However, future versions will add crash reporting (similar to Crashlytics). This feature will allow you to: - Record app crashes on iOS and Android - Receive detailed stack traces and environment (OS version, device model, app version) - See the distribution of crashes by users and releases to highlight the most critical ones - Analyze dynamics and priorities to fix the most widespread failures faster ### AI filtering AI-based event filtering will appear in future versions of Hawk. It will help teams avoid noise and focus on truly important errors. Planned: - **Automatic prioritization** — algorithms will highlight critical events affecting many users or key product scenarios. - **Hiding irrelevant errors** — repeated, minor, or known safe events can be automatically marked as secondary. - **Grouping and highlighting important ones** — the system will group similar errors and show them in a prioritized list for quick response. This filtering will reduce the workload on support and development teams and speed up the resolution of errors that truly affect users. --- ## 19. Conclusion You can find the technical implementation of all described features in Hawk's GitHub repositories. If you have questions about current functionality or suggestions for new features, email the Hawk team. If you are interested in following the project's progress — news is published in the [Telegram channel](https://t.me/hawk_tracker).