leads-su / sentry-php-client

Sentry-Client object implementation for PHP

Объектная реализация Sentry клиента

Поддерживает:

• установку тегов
• установку пользователя/клиента затронутого проблемой
• добавление breadcrumbs - событий, которые привели к проблеме
• захват и передачу в Sentry исключения или сообщения
• включение/отключение автоматичекой обработки ошибок
• 2 способа транспортировки: http и fluentd/td-agent

Несмотря на объектный подход, инициализация нескольких одновременных Sentry клиентов недопустима.

Диаграмма классов клиентов Sentry:

classDiagram
direction BT
class SentryAbstract
class SentryFluentd
class SentryHttp
class SentryInterface
SentryAbstract  ..>  SentryInterface
SentryFluentd  -->  SentryAbstract
SentryHttp  -->  SentryAbstract

Loading

Транспортировка событий в Sentry

Доступно 2 вида транспортировки событий:

• через HTTP - стандартный способ (поддерживается из коробки sentry/sdk):

use Leads\Sentry\Implementations\SentryHttp;
use Leads\Sentry\Entities\IntegrationsOptions;

$dsn = '';
$environment = 'production';
$release = 'my-project@1.0.0';

$sentryClient = new SentryHttp(
    $dsn,
    new IntegrationsOptions(),
    $environment,
    $release,
);

• через fluentd/td-agent - реализован через пакет fluent/logger в данном проекте как более быстрое для клиентского кода и более устойчивое для сервера Sentry в одном инстансе:

use Fluent\Logger\FluentLogger;
use Leads\Sentry\Implementations\SentryHttp;
use Leads\Sentry\Entities\IntegrationsOptions;

$dsn = '';
$environment = 'production';
$release = 'my-project@1.0.0';
$fluentHost = 'unix:///var/run/td-agent/fluentd.sock';
$fluentPort = '24224';

$sentryClient = new SentryFluentd(
    $dsn,
    new IntegrationsOptions(),
    new FluentLogger($fluentHost, $fluentPort),
    $environment,
    $release
);

Реализация Sentry клиента SentryFluentd отправляет fluentd запись с тегом sentry.store.{project_id}.{sentry_key} где:

• project_id - идентификатор проекта в Sentry
• sentry_key - авторизационный ключ (часть DSN)

Узел fluentd, который осуществляет отправку события в Sentry должен использовать store endpoint, например так (localhost:9000 - адрес сервера Sentry):

<match sentry.store.**>
  @type http
  @log_level debug
  
  endpoint http://localhost:9000/api/${tag[2]}/${tag[1]}/?sentry_version=7&sentry_client=td-agent&sentry_key=${tag[3]}
  open_timeout 2
  http_method post
  content_type application/json

  <buffer tag>
    @type file
    path /var/log/td-agent/sentry.store.buffer
    retry_forever true
    flush_mode immediate
    chunk_limit_size 32MB
    retry_type periodic
    retry_wait 10s
    retry_randomize true
    compress text
  </buffer>
</match>

Для fluentd >=1.12.1 можно использовать авторизацию через заголовки запроса.

Способы обработки ошибок

Так как этот код оборачивает sentry/sdk, то ему также присущи 2 способа обработки ошибок:

• автоматически при помощи обработчиков ошибок, реализованных интеграциями
• вручную, например в блоке catch:

try {
  //...
} catch (\Throwable $e) {
  $sentryClient->captureException($e);
}

Включение или отключение производится через объект класса IntegrationsOptions при иницилазиции Sentry клиента:

use Leads\Sentry\Implementations\SentryHttp;
use Leads\Sentry\Entities\IntegrationsOptions;

$dsn = '';
$environment = 'production';
$release = 'my-project@1.0.0';

$intOptions = new IntegrationsOptions();
$intOptions->setAutoHandler(true);

$sentryClient = new SentryHttp(
    $dsn,
    new IntegrationsOptions(),
    $environment,
    $release,
);

При автоматической обработке ошибок средствами Sentry клиента необходимо инициализировать этого клиента как можно раньше в коде приложения!

Дополнительные функции

Установить тег:

$sentryClient->setTag('tagName', 'tagValue');

Отправить сообщение:

$sentryClient->captureMessage('', Leads\Sentry\Entities\SeverityLevel::ERROR);

Установить пользователя получившего ошибку:

use Leads\Sentry\Entities\User;

$userId = 4687;
$userName = 'username';
$sentryClient->setUser(
    new User($id, $name)
);

Установить хлебные крошки:

use Leads\Sentry\Entities\Breadcrumb;
use Leads\Sentry\Entities\SeverityLevel;

$metadata = [
    'key' => 'value',
];

$sentryClient->addBreadcrumb(
    new Breadcrumb(
        SeverityLevel::INFO,
        'category',
        'message',
        $metadata
    )
);