[譯] 在PHP中使用Sentry

GUNN發表於2018-03-02
PHP

Sentry 是一個錯誤記錄和聚合的平臺。Sentry除了提供了PaaS平臺供直接使用，更開放了私有部署方式，關於如何使用Docker快速搭建私有Sentry，可以閱讀我上篇文章[譯] 使用Docker安裝Sentry(一個錯誤記錄和聚合平臺)。

在PHP中使用Sentry非常簡單。在安裝庫之後，您可以直接與客戶端進行互動並開始提交資料。

安裝庫

Sentry的PHP SDK支援PHP 5.3及更高版本。 它可作為BSD許可的開放原始碼庫提供。

有多種方法可以為Sentry安裝PHP整合。 推薦的方法是使用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();
複製程式碼

在Raven_Client例項上呼叫install()將自動註冊這些處理程式。

報告Exceptions

如果您想手動報告異常，可以使用captureException函式。

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

// 利用Exception提供一些額外的資料
$sentryClient->captureException($ex, array(
    'extra' => array(
        'php_version' => phpversion()
    ),
));
複製程式碼

報告其他錯誤

有時候你沒有一個實際的異常物件，但是發生了一些不好的事情，你想報告它。這是CaptureMessage的用處。它會接收一條訊息並將其報告給sentry。

// 捕獲訊息
$sentryClient->captureMessage('my log message');
複製程式碼

請注意，captureMessage具有與captureException稍有不同的API，以支援引數化格式：

$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']
)
複製程式碼

等級

事件的級別。預設為錯誤。 array( 'level' => 'warning' ) sentry支援一下級別:

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

日誌

事件的記錄器名稱。 array( 'logger' => 'default' )

標籤

與此事件相關的標籤。必須是字串的對映

array(
    'tags' => array('key' => 'value')
)
複製程式碼

使用者

array(
    'user' => array(
        'id' => 42,
        'email' => 'clever-girl'
    )
)
複製程式碼

取回事件ID

事件ID是剛剛傳送的事件的全域性唯一ID。此事件ID可用於從Sentry中查詢確切的事件。 這通常用於向使用者顯示並向客戶服務報告錯誤。 $sentryClient->getLastEventID();

使用者反饋

要啟用使用者對崩潰報告的反饋，您需要建立一個能夠識別上次事件ID的錯誤處理程式。

<?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會盡量減少故障發生，當它們發生時總會盡量避免將它們冒泡給您的應用程式。如果您確實想知道事件何時無法記錄，可以使用getLastError幫助器：

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!複製程式碼

相關文章