Налаштування Error Tracking (Sentry) для веб-застосунку

Налаштування Error Tracking (Sentry) для вашого веб-застосунку

Sentry — це стандарт де факто для відслідковування помилок у веб-застосунках. Він фіксує виключення з повним стеком вызовів, контекстом запиту, змінними оточення та breadcrumbs — ланцюгом подій, які передували помилці. На відміну від логів, Sentry групує однакові помилки, показує частоту та перше вхождення, може призначити відповідальних.

Варіанти використання

Sentry SaaS (sentry.io) — без інфраструктури, безплатний tier (5000 помилок/місяць). Self-hosted — на базі Docker, потребує ~4 GB RAM, підходить для команд з вимогами до даних або великими обсягами помилок.

Встановлення SDK

PHP / Laravel:

composer require sentry/sentry-laravel
php artisan sentry:publish --dsn=https://[email protected]/project-id

config/sentry.php створюється автоматично. У .env:

SENTRY_LARAVEL_DSN=https://[email protected]/project-id
SENTRY_TRACES_SAMPLE_RATE=0.1
SENTRY_PROFILES_SAMPLE_RATE=0.1

У bootstrap/app.php (Laravel 11) або app/Exceptions/Handler.php (Laravel 9-10) — SDK реєструється автоматично через service provider.

Ручна отправка з контекстом:

use Sentry\State\Scope;

\Sentry\withScope(function (Scope $scope) use ($user, $order): void {
    $scope->setUser(['id' => $user->id, 'email' => $user->email]);
    $scope->setContext('order', [
        'id' => $order->id,
        'amount' => $order->total,
        'status' => $order->status,
    ]);
    $scope->setTag('payment_provider', 'stripe');
    \Sentry\captureException(new \RuntimeException('Payment gateway timeout'));
});

JavaScript / React:

npm install @sentry/react

// src/main.tsx
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_VERSION,
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration({
      maskAllText: false,
      blockAllMedia: false,
    }),
  ],
  tracesSampleRate: 0.1,
  replaysSessionSampleRate: 0.05,
  replaysOnErrorSampleRate: 1.0,  // 100% при помилці
});

Error Boundary для React:

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

const App = () => (
  <Sentry.ErrorBoundary
    fallback={({ error, resetError }) => (
      <div>
        <p>Щось пішло не так</p>
        <button onClick={resetError}>Спробувати ще раз</button>
      </div>
    )}
    onError={(error, componentStack) => {
      console.error('React error boundary caught:', error);
    }}
  >
    <Router />
  </Sentry.ErrorBoundary>
);

Source Maps для JavaScript

Без source maps стек вызовів в Sentry показує мініфіцирований код. Налаштування через Sentry Vite Plugin:

npm install @sentry/vite-plugin --save-dev

// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default defineConfig({
  build: { sourcemap: true },
  plugins: [
    react(),
    sentryVitePlugin({
      org: 'your-org',
      project: 'your-project',
      authToken: process.env.SENTRY_AUTH_TOKEN,
      sourcemaps: {
        assets: './dist/**',
        ignore: ['node_modules'],
        filesToDeleteAfterUpload: ['./dist/**/*.map'],
      },
    }),
  ],
});

Source maps завантажуються в Sentry при збірці та видаляються з публічної директорії — вони недоступні в браузері користувача.

Налаштування оточень та відслідковування release

У CI/CD при розгортуванні:

# Створення release та прив'язування коммітів
sentry-cli releases new "$VERSION"
sentry-cli releases set-commits "$VERSION" --auto
sentry-cli releases finalize "$VERSION"
sentry-cli releases deploys "$VERSION" new -e production

Це дозволяє бачити в Sentry: який комміт вперше викликав помилку, в якому релізі вона з'явилася, чи була вона в попередніх версіях.

Фільтрування шуму

За умовчанням Sentry ловить все — включаючи очікувані 404, ботів, краші з розширень браузера. Фільтрування:

// config/sentry.php
'before_send' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
    $exception = $hint?->exception;

    // Ігнорувати очікувані виключення
    if ($exception instanceof \Illuminate\Auth\AuthenticationException) {
        return null;
    }
    if ($exception instanceof \Symfony\Component\HttpKernel\Exception\NotFoundHttpException) {
        return null;
    }

    // Ігнорувати помилки від ботів
    $userAgent = request()->header('User-Agent', '');
    if (str_contains(strtolower($userAgent), 'bot')) {
        return null;
    }

    return $event;
},

// JavaScript: ігнорувати помилки розширень браузера
Sentry.init({
  denyUrls: [
    /extensions\//i,
    /^chrome:\/\//i,
    /^chrome-extension:\/\//i,
  ],
  ignoreErrors: [
    'ResizeObserver loop limit exceeded',
    'Non-Error promise rejection captured',
  ],
});

Алерти та сповіщення

У Sentry: Settings → Alerts → Create Alert Rule:

• New issue — негайно при першому вхожденні нового типу помилки
• Error frequency — якщо помилка трапляється > 100 раз за 1 годину
• Regression — помилка повернулася після того як була позначена resolved

Інтеграції: Slack, Telegram (через webhook), PagerDuty, Jira (автостворення задач).

Розклад

Встановлення та базове налаштування SDK для backend + frontend, налаштування source maps, первинна фільтрація шуму, alert-правила: 2-4 години.