Настройка Error Tracking (Bugsnag) для веб-приложения

Настройка Error Tracking (Bugsnag) для веб-приложения

Bugsnag — коммерческая альтернатива Sentry с акцентом на стабильность релизов. Ключевая метрика — Stability Score: процент сессий без ошибок. Это удобнее, чем сырые счётчики ошибок, когда нужно принять решение «готов ли релиз к раскатке».

Бесплатный план: 7500 ошибок/месяц на 1 проект.

Установка PHP / Laravel

composer require bugsnag/bugsnag-laravel

php artisan bugsnag:install your-api-key-here

В .env:

BUGSNAG_API_KEY=your_32_char_api_key
BUGSNAG_APP_VERSION=1.0.0
BUGSNAG_RELEASE_STAGE=production

config/bugsnag.php после публикации:

return [
    'api_key' => env('BUGSNAG_API_KEY'),
    'app_version' => env('BUGSNAG_APP_VERSION'),
    'release_stage' => env('BUGSNAG_RELEASE_STAGE', 'production'),
    'notify_release_stages' => ['production', 'staging'],
    'filters' => ['password', 'token', 'secret', 'api_key'],
    'notify_endpoint' => 'https://notify.bugsnag.com',
    'sessions_endpoint' => 'https://sessions.bugsnag.com',
    'auto_capture_sessions' => true,
];

Service Provider регистрируется автоматически. В app/Exceptions/Handler.php для Laravel 9-10:

use Bugsnag\BugsnagLaravel\Facades\Bugsnag;

public function register(): void
{
    $this->reportable(function (Throwable $e) {
        Bugsnag::notifyException($e);
    });
}

Контекст и метаданные

use Bugsnag\BugsnagLaravel\Facades\Bugsnag;

// Установить пользователя (автоматически если auth настроен)
Bugsnag::setUser([
    'id' => $user->id,
    'name' => $user->name,
    'email' => $user->email,
]);

// Добавить произвольные вкладки в отчёт
Bugsnag::registerCallback(function ($report) {
    $report->setMetaData([
        'subscription' => [
            'plan' => auth()->user()?->plan,
            'trial_ends' => auth()->user()?->trial_ends_at,
        ],
    ]);
});

// Ручная отправка с доп. данными
Bugsnag::notifyException(
    new \RuntimeException('Stripe webhook failed'),
    function ($report) use ($payload) {
        $report->setSeverity('warning');
        $report->setMetaData(['webhook' => ['event' => $payload['type']]]);
    }
);

JavaScript / React

npm install @bugsnag/js @bugsnag/plugin-react

// src/bugsnag.ts
import Bugsnag from '@bugsnag/js';
import BugsnagPluginReact from '@bugsnag/plugin-react';
import React from 'react';

Bugsnag.start({
  apiKey: import.meta.env.VITE_BUGSNAG_API_KEY,
  plugins: [new BugsnagPluginReact()],
  releaseStage: import.meta.env.MODE,
  enabledReleaseStages: ['production', 'staging'],
  appVersion: import.meta.env.VITE_APP_VERSION,
  onError: (event) => {
    // Добавить user context
    const user = getCurrentUser(); // ваша функция
    if (user) {
      event.setUser(user.id, user.email, user.name);
    }

    // Фильтровать шум
    if (event.errors[0].errorMessage.includes('ResizeObserver')) {
      return false;
    }
  },
});

export const ErrorBoundary = Bugsnag.getPlugin('react')!
  .createErrorBoundary(React);

// src/main.tsx
import { ErrorBoundary } from './bugsnag';

root.render(
  <ErrorBoundary
    FallbackComponent={({ error, clearError }) => (
      <div>
        <h2>Произошла ошибка</h2>
        <button onClick={clearError}>Обновить</button>
      </div>
    )}
  >
    <App />
  </ErrorBoundary>
);

Source Maps

npm install --save-dev @bugsnag/source-maps

# После сборки
npx bugsnag-source-maps upload-browser \
  --api-key $BUGSNAG_API_KEY \
  --app-version $APP_VERSION \
  --directory dist/assets \
  --base-url https://example.com/assets/

Добавить в CI pipeline после npm run build.

Breadcrumbs — хлебные крошки

Bugsnag автоматически записывает клики, навигацию, console.log. Ручные breadcrumbs:

// Пометить пользовательские действия
Bugsnag.leaveBreadcrumb('User initiated checkout', {
  cart_items: cart.length,
  total: cart.total,
}, 'user');

// Помечать API-вызовы
async function apiCall(url: string, options: RequestInit) {
  Bugsnag.leaveBreadcrumb('API request', { url, method: options.method }, 'request');
  try {
    const response = await fetch(url, options);
    Bugsnag.leaveBreadcrumb('API response', { url, status: response.status }, 'request');
    return response;
  } catch (error) {
    Bugsnag.notify(error as Error);
    throw error;
  }
}

Уведомления и интеграции

Bugsnag поддерживает: Slack, PagerDuty, Jira, GitHub Issues, GitLab Issues.

Настройка Slack-нотификаций: Settings → Integrations → Slack → добавить webhook URL. Выбрать события: New error, Error spike, Regression.

Сроки

Установка SDK для PHP и JavaScript, настройка source maps, базовая фильтрация, подключение Slack-нотификаций: 2-4 часа.