Customizing error reports

Add diagnostic data to every error report, conditionally adjust error reports, or indeed, skip notifying Bugsnag of the error.

Adding callbacks

If you’d like to add diagnostic data to every error report, or adjust error reports conditionally, you can add callbacks which will be invoked each time a report will be sent.

In Laravel callbacks should be registered within the boot function of your app/providers/AppServiceProvider class:

public function boot()
{
    Bugsnag::registerCallback(function ($report) {
        $report->setMetaData([
        'account' => [
            'name' => 'Acme Co.',
            'paying_customer' => true,
        ]
    ]);
}

To cancel the error report, return false from the function.

See $report object for methods available within the callback.

The $report object

The following properties and methods are available on the $report object.

addMetaData

Add additional metadata to the error report, or delete existing metadata. Properties with a value of null will be deleted.

$report->addMetaData([
    'account' => [
        'paying' => true,
        'name' => 'Acme Co',
        'contact' => null # Will be deleted
    ]
])

Conflicting properties will be merged recursively, favouring the newest values. For example:

$report->addMetaData([
    'account' => array(
        'id' => '0001',
        'name' => 'Acme Co'
    )
])

$report->addMetaData([
    'account' => array(
        'name' => 'ACME'
    )
])

Results in:

[
    'account' => [
        'id' => '0001',
        'name' => 'ACME'
    ]
]

getContext

Gets the current context of the report.

$context = $report->getContext();

getStacktrace

Gets the Stacktrace object attached to the error report. The stacktrace can be filtered or otherwise modified as needed.

This behavior is useful when there is a designated error handling function within application code, and error reports are being grouped by that function on your Bugsnag dashboard. The frames of a stacktrace are ordered such that index 0 is the frame most recently called.

$stacktrace = $report->getStacktrace();
$frames = $stacktrace->getFrames();

if ($frames[0]['method'] == 'log_error') {
    $stacktrace->removeFrame(0);
}

getUser

Gets the associated user on the error.

$user = $report->getUser();

setContext

Providing context for where the error occurred, context is given high visual prominence in the dashboard helping you to track specific issues quickly. This is typically set to a filename or request path automatically, depending on the framework and application type.

$report->setContext('myCustomContext');

setGroupingHash

Sets the grouping hash of the error report. All errors with the same grouping hash are grouped together. This is an advanced usage of the library and mis-using it will cause your errors not to group properly in your dashboard.

$report->setGroupingHash($report->getName() . $report->getMessage());

setMessage

Set the error message sent in the error report

$report->setMessage('This was a mistake.');

setMetaData

Set additional metadata to send with this error report, or replace existing metadata.

$report->setMetaData([
    'account' => array(
        'paying' => true,
        'name' => 'Acme Co'
    )
]);

If a conflict occurs while merging, the conflicting values will be placed into an array under the same key. For example:

$report->setMetaData([
    'account' => array(
        'id' => '0001',
        'name' => 'Acme Co'
    )
])

$report->setMetaData([
    'account' => array(
        'name' => 'ACME'
    )
])

Results in:

[
    'account' => [
        'id' => '0001',
        'name' => [
            'Acme Co',
            'ACME'
        ]
    ]
]

You can also pass a 2nd paramater of false stop us merging your metadata, and force us to completely replace it. For example:

$report->setMetaData([
    'account' => array(
        'id' => '0001',
        'name' => 'Acme Co'
    ),
    'diagnostics' => 'Failure'
])

$report->setMetaData([
    'account' => array(
        'name' => 'ACME'
    )
], false)

Results in:

[
    'account' => [
        'name' => 'ACME'
    ]
]

setName

Set the error name sent in the error report

$report->setName('OopsError');

setSeverity

Set the severity of the error report. Valid severities are error, warning, and info.

By default, all unhandled exceptions are set to severity error and all handled exceptions are set to severity warning.

$report->setSeverity('info');

setUser

You can set the associated user on the error.

$report->setUser([
    'id' => '123456',
    'name' => 'Leeroy Jenkins',
    'email' => 'leeeeroy@jenkins.com',
]);