[Перевод] Использование Sentry в PHP

PHP Программа перевода самородков
[Перевод] Использование Sentry в PHP

Sentry — это платформа регистрации и агрегирования ошибок. В дополнение к предоставлениюПлатформа PaaSДля прямого использования, более открыты для частного развертывания о том, как использовать Docker быстро построить частное Sentry, вы можете прочитать мою последнюю статью[Перевод] Использование Docker для установки Sentry (платформа регистрации и агрегирования ошибок).

Использовать Sentry в PHP очень просто. После установки библиотеки вы можете напрямую взаимодействовать с клиентом и начать отправку данных.

Установить библиотеку

Sentry PHP SDK поддерживает PHP 5.3 и выше. Он доступен как библиотека с открытым исходным кодом под лицензией BSD.

Существуют различные способы установки интеграции PHP для Sentry. Рекомендуемый способ - использовать Composer:

composer require "sentry/sentry"

Кроме того, вы можете установить его вручную:

  1. Загрузите и извлеките последнююsentry-phpфайл в ваш проект PHP.
  2. Требовать автозагрузчик в вашем приложении:
require_once '/path/to/Raven/library/Raven/Autoloader.php';
Raven_Autoloader::register();

База

Самая важная часть — это создание клиента Sentry. Создайте его один раз и ссылайтесь на него из любого места, где вы хотите взаимодействовать с Sentry:

$sentryClient = new Raven_Client('https://<key>:<secret>@sentry.io/<project>');

поймать ошибки

Sentry содержит основные функции для сообщения о любых неиспользованных исключениях или ошибках PHP. Это делается обработчиком ошибок и предоставляет соответствующий хук для каждого встроенного отчета PHP:

$error_handler = new Raven_ErrorHandler($sentryClient);
$error_handler->registerExceptionHandler();
$error_handler->registerErrorHandler();
$error_handler->registerShutdownFunction();

Вызов install() для экземпляра Raven_Client автоматически зарегистрирует эти обработчики.

Сообщить об исключениях

Если вы хотите сообщать об исключениях вручную, вы можете использовать функцию captureException.

// 基本报告
$sentryClient->captureException($ex);

// 利用Exception提供一些额外的数据
$sentryClient->captureException($ex, array(
    'extra' => array(
        'php_version' => phpversion()
    ),
));

сообщать о других ошибках

Иногда у вас нет фактического объекта исключения, но произошло что-то плохое, и вы хотите сообщить об этом. Здесь на помощь приходит CaptureMessage. Он получит сообщение и сообщит об этом часовому.

// 捕获消息
$sentryClient->captureMessage('my log message');

Обратите внимание, что API захвата Message немного отличается от API захватаException для поддержки параметризованных форматов:

$sentryClient->captureMessage('my %s message', array('log'), array(
    'extra' => array(
        'foo' => 'bar',
    ),
));

необязательный атрибут

Дополнительные данные можно предоставить, вызвав метод captureException или CaptureMessage:

$sentryClient->captureException($ex, array(
    'attr' => 'value',
));

дополнительный

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

отпечаток пальца

Отпечаток пальца, используемый для группировки этого события.

array(
    'fingerprint' => ['{{ default }}', 'other value']
)

оценка

Уровень мероприятия. Значение по умолчанию — ложь. множество( 'уровень' => 'предупреждение' ) sentry поддерживает следующие уровни:

  • debug (the least serious)
  • info
  • warning
  • error
  • fatal (the most serious)

бревно

Имя регистратора события. множество( 'регистратор' => 'По умолчанию' )

Этикетка

Ярлык, связанный с этим событием. Должна быть карта строк

array(
    'tags' => array('key' => 'value')
)

Пользователь

array(
    'user' => array(
        'id' => 42,
        'email' => 'clever-girl'
    )
)

Получить идентификатор события

Идентификатор события — это глобально уникальный идентификатор только что отправленного события. Этот идентификатор события можно использовать для поиска точного события от Sentry. Обычно это используется для отображения пользователям и сообщения об ошибках в службу поддержки клиентов.$sentryClient->getLastEventID();

Обратная связь с клиентом

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

<?php

$sentry = new \Raven_Client(https://<key>:<secret>@sentry.io/<project>);

public class App {
    function error500($exc) {
        $event_id = $sentry->captureException($exc);

        return $this->render('500.html', array(
            'sentry_event_id' => $event_id,
        ), 500);
    }
}

Затем в своем шаблоне вы можете загрузить виджет обратной связи:

<!-- Sentry JS SDK 2.1.+ required -->
<script src="https://cdn.ravenjs.com/2.3.0/raven.min.js"></script>

{% if sentry_event_id %}
  <script>
  Raven.showReportDialog({
    eventId: '{{ sentry_event_id }}',

    // use the public DSN (dont include your secret!)
    dsn: 'https://<key>@sentry.io/<project>'
  });
  </script>
{% endif %}

Дополнительные сведения об этой функции см.Руководство по обратной связи с пользователями.

Ручка

SDK попытается уменьшить неудачу, когда они возникают, они всегда стараются избегать пузыринга к вашему приложению. Если вы действительно хотите знать, когда событие не может быть записано, вы можете использовать HetLasterror Helper:

if ($sentryClient->getLastError() !== null) {
    echo "Something went very, very wrong";
    // $sentryClient->getLastError() contains the error that occurred
} else {
    // Give the user feedback
    echo "Sorry, there was an error!";
    echo "Your reference ID is " . $event_id;
}

Панировочные сухари

Sentry поддерживает захват хлебных крошек — событий, которые происходят до события.

$sentryClient->breadcrumbs->record(array(
    'message' => 'Authenticating user as ' . $username,
    'category' => 'auth',
    'level' => 'info',
));

ошибки фильтра

Как правило, вы можете захотеть запретить автоматический захват определенных областей. В идеале в такой ситуации лучше просто не звонить в Sentry, но часто это легче сказать, чем сделать. Вместо этого вы можете предоставить функции, которые SDK вызывает перед отправкой каких-либо данных, что позволит вам изменить данные и предотвратить их отправку на сервер.

$sentryClient->setSendCallback(function($data) {
    $ignore_types = array('Symfony\Component\HttpKernel\Exception\NotFoundHttpException');

    if (isset($data['exception']) && in_array($data['exception']['values'][0]['type'], $ignore_types))
    {
        return false;
    }
});

оператор контроля ошибок

В PHP очень часто используется оператор подавления, чтобы избежать всплывающих ошибок обработки:

$my_file = @file('non_existent_file');

В этих случаях Sentry никогда не будет захватывать ошибки. Если вы хотите запечатлеть его на этом этапе, вам нужно позвонить на клиент PHP вручную:

$my_file = @file('non_existent_file');
if (!$my_file) {
    // ...
    $sentryClient->captureLastError();
}

Проверьте свое соединение

PHP-клиент включает простой вспомогательный скрипт для проверки вашего подключения и учетных данных к основному серверу Sentry:

$ bin/sentry test https://<key>:<secret>@sentry.io/<project>
Client configuration:
-> server: [https://sentry.io]
-> project: ___PROJECT_ID___
-> public_key: <key>
-> secret_key: <secret>

Sending a test event:
-> event ID: f1765c9aed4f4ceebe5a93df9eb2d34f

Done!
Категории