Configuration options

All available options for configuring BugSnag with Laravel.

The BugSnag client object has several methods which help you customize the content of error reports, and how the reports are delivered.

Most configuration options can be automatically populated by environment variables or in config/bugsnag.php, to generate it run php artisan vendor:publish.

API key

You can set the BugSnag API key by setting the BUGSNAG_API_KEY environment variable, or by setting api_key within config/bugsnag.php

'api_key' => 'YOUR-API-KEY-HERE',

This setting is the only one which is required in order to use the notifier.

You can find your API key in Project Settings from your BugSnag dashboard.

App type

You can set the type of application executing the current code by using setAppType:

Bugsnag::setAppType('Mailer');

You can also set the BUGSNAG_APP_TYPE environment variable, or set this within config/bugsnag.php:

'app_type' => 'Mailer',

By default this is set to Console, HTTP, or Queue depending on the context.

App version

To track in which versions of your application each exception happens, set the app version:

Bugsnag::setAppVersion('1.2.3');

You can also set the BUGSNAG_APP_VERSION environment variable, or set this within config/bugsnag.php:

'app_version' => '1.2.3',

This is not set by default.

Attach hidden context

BugSnag automatically attaches non-hidden data from Laravel’s Context object to events as metadata.

To also attach hidden Context data, set the BUGSNAG_ATTACH_HIDDEN_CONTEXT environment variable or set this within config/bugsnag.php:

'attach_hidden_context' => true,

By default this is set to false.

Auto capture sessions

Set to true if you would like BugSnag to automatically capture sessions.

Bugsnag::setAutoCaptureSessions(true);

Using this option, BugSnag will report a session each time:

• Laravel processes a request

This can also be set with the environment variable BUGSNAG_CAPTURE_SESSIONS, or within config.bugsnag.php:

'auto_capture_sessions' => true,

This is set to false by default.

Batch sending

If you’d like us to send the errors through to BugSnag when the PHP process shuts down, in order to prevent your app waiting on HTTP requests, this can be set to true. Setting it to false will mean the we send an HTTP request straight away for each error.

Bugsnag::setBatchSending(true);

You can also set the BUGSNAG_BATCH_SENDING environment variable, or set this within config/bugsnag.php:

'batch_sending' => true,

By default, this is set to true.

You can also flush our error buffer by calling the flush function, causing any queued errors to be sent immediately:

Bugsnag::flush(true);

Build endpoint

You can changes the endpoint build notifications will delivered to. This can also be set using the BUGSNAG_BUILD_ENDPOINT environment variable.

Bugsnag::setBuildEndpoint('https://bugsnag-build.example.com');

By default, this is set to https://build.bugsnag.com.

Callbacks

Set a callback attached to the notification pipeline when notifying BugSnag of an error. You can use this to call your own error handling functions or customize the error report.

Bugsnag::registerCallback(function ($report) {
    // Inspect or modify the error report here
});

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

Discard classes

Allows you to specify which events should be automatically discarded based on the class name of the exception.

Accepts both strings and regexes, and comparisons are case sensitive.

Bugsnag::setDiscardClasses([
    \Example\Exception::class,
    '/^Example\\.+/',
]);

You can also set this within config/bugsnag.php:

'discard_classes' => [
    \Example\Exception::class,
    '/^Example\\.+/',
];

By default, no classes are discarded

Endpoint

You can change the BugSnag endpoint by setting the BUGSNAG_ENDPOINT environment variable, or by setting endpoint within config/bugsnag.php:

'endpoint' => 'https://example.com/',

By default, this is set to https://notify.bugsnag.com.

Feature flags

Declare feature flag and experiment usage.

addFeatureFlag

Declare a single feature flag or experiment with variant as an optional second parameter.

Bugsnag::addFeatureFlag('Checkout button color', 'Blue')
Bugsnag::addFeatureFlag('New checkout flow')

addFeatureFlags

Declare multiple feature flags or experiments.

Bugsnag::addFeatureFlags([
    new \Bugsnag\FeatureFlag('Checkout button color', 'Blue'),
    new \Bugsnag\FeatureFlag('Special offer', 'Free Coffee'),
    new \Bugsnag\FeatureFlag('New checkout flow'),
])

If addFeatureFlags is called again, the new data will be merged with any existing feature flags with the newer variant values taking precedence.

Feature flags can also be added in config/bugsnag.php:

'feature_flags' => [
    [
        'name' => 'Checkout button color',
        'variant' => 'Blue',
    ],
    [
        'name' => 'Special offer',
        'variant' => 'Free coffee',
    ],
    [
        'name' => 'New checkout flow',
    ],
],

See the Feature flags & experiments guide for more information.

Filters

Sets the strings to filter out from the metaData arrays before sending them to BugSnag. Use this if you want to ensure you don’t send sensitive data such as passwords, and credit card numbers to our servers. Any keys which contain these strings (ignoring case) will be filtered.

Bugsnag::setFilters(array_merge(Bugsnag::getFilters(), ['credit_card']));

You can also set the BUGSNAG_FILTERS environment variable to a comma separated string such as password,credit_card.

Finally, this could be set within config/bugsnag.php:

'filters' => ['password', 'credit_card'],

By default, this is set to be

['password', 'cookie', 'authorization', 'php-auth-user', 'php-auth-pw', 'php-auth-digest']

Hostname

If you would like to set the hostname of your server to something specific for you to identify it by, then you can call this method with your desired hostname.

Bugsnag::setHostname('your-hostname');

You can also set the BUGSNAG_HOSTNAME environment variable, or set this within config/bugsnag.php:

'hostname' => 'your-hostname',

By default this is set to php_uname('n').

Ignored exceptions

Any exception added to the $dontReport array within app/Exceptions/Handler.php will not be sent to BugSnag. You can change this behavior by adding or removing exception classes from the $dontReport array.

class Handler extends ExceptionHandler
{
    /**
     * A list of the exception types that are not reported.
     *
     * @var array
     */
    protected $dontReport = [
        // Add or remove classes from this array to
        // ignore or receive error reports
    ];
    // ...
}

Logger notify level

The default behaviour of the error-handling laravel logger is to send a notification if a log message with a level of 'notice' or higher is received. This level can be set by calling setNotifyLevel on the bugsnag.logger:

app('bugsnag.logger')->setNotifyLevel(\Psr\Log\LogLevel::INFO);

You can also set the BUGSNAG_LOGGER_LEVEL environment variable in your .env file:

BUGSNAG_LOGGER_LEVEL=info

Or set this within config/bugsnag.php:

'logger_notify_level' => \Psr\Log\LogLevel::INFO,

The logger notify level must be set to a valid \Psr\Log\LogLevel or string equivalent.

Max breadcrumbs

Sets the maximum number of breadcrumbs which will be stored. Once the threshold is reached, the oldest breadcrumbs will be deleted.

By default, 50 breadcrumbs are stored; this can be amended up to a maximum of 100.

Bugsnag::setMaxBreadcrumbs(100);

You can also modify this within config/bugsnag.php:

'max_breadcrumbs' => 100,

Memory limit increase

BugSnag will increase the PHP memory limit when your app runs out of memory to ensure events can be delivered. You can control the number of bytes BugSnag will increase the memory limit by with the setMemoryLimitIncrease method.

Bugsnag::setMemoryLimitIncrease(1024 * 1024 * 10); // 10 MiB

To disable this behaviour, pass null instead.

You can also modify this within config/bugsnag.php:

'memory_limit_increase' => 1024 * 1024 * 10,

By default this is set to 5 MiB (1024 * 1024 * 5)

Metadata

Here you can set additional metadata to send with every bugsnag notification. By default, we merge your new metadata with anything already existing on the config object. You can pass false as the 2nd parameter to disable this behaviour.

Bugsnag::setMetaData([
    'account' => [
        'paying' => true,
        'name' => 'Acme Co'
    ]
]);

To set metadata on error reports individually, see customizing error reports.

Project root

BugSnag marks stacktrace lines as in-project if they come from files inside your “project root”. This can be set by calling setProjectRoot on our client.

Bugsnag::setProjectRoot('/path/to/your/app/app');

If you wish to use regular expressions, you can call setProjectRootRegex on the client.

Bugsnag::setProjectRootRegex('/^\/path\/to\/your\/app\/app[\\/]?/i');

It also trims this path from the start of any filepath. If you want to change the strip path, see strip path.

You can also modify these with the BUGSNAG_PROJECT_ROOT and BUGSNAG_PROJECT_ROOT_REGEX environment variables, or within config/bugsnag.php:

'project_root' => '/path/to/your/app/app',
'project_root_regex' => '/^\/path\/to\/your\/app\/app[\\/]?/i',

By default we’ll set the project root to the app directory.

Proxies

If you’d like to set a proxy for us to use, you can set the HTTP_PROXY or HTTPS_PROXY variables for Guzzle.

Note that HTTP_PROXY is only available in cli, and if HTTPS_PROXY is present, it’ll replace HTTP_PROXY.

You can also set these options within config/bugsnag.php. For example, to set an HTTPS proxy:

'proxy' => ['https' => 'https://example.com'],

Query breadcrumbs

BugSnag automatically captures database queries as breadcrumbs. To turn this off you can set the BUGSNAG_QUERY environment variable to false.

By default, we exclude query bindings from the breadcrumbs. If you’d like to include these, set BUGSNAG_QUERY_BINDINGS to true.

You can also modify these within config/bugsnag.php:

'query' => true,
'bindings' => true,

See automatically captured breadcrumbs for more information.

Redacted keys

Sets which values should be removed from any metadata before sending them to BugSnag. Use this if you want to ensure you don’t transmit sensitive data such as passwords and credit card numbers.

Any property whose key matches a redacted key will be filtered and replaced with [FILTERED].

Accepts both strings and regexes, and string comparisons are case insensitive.

Bugsnag::setRedactedKeys([
    'access_token', // case-insensitive: "access_token", "ACCESS_TOKEN", "AcCeSs_ToKeN"
    '/^cc_/'        // prefix match: "cc_number" "cc_cvv" "cc_expiry"
]);

You can also set the BUGSNAG_REDACTED_KEYS environment variable to a comma separated string such as access_token,/^cc_/.

Finally, this could be set within config/bugsnag.php:

'redacted_keys' => ['access_token', '/^cc_/'],

By default, this is set to be

['password', 'cookie', 'authorization', 'php-auth-user', 'php-auth-pw', 'php-auth-digest']

Release stage

If you would like to distinguish between errors that happen in different stages of the application release process (development, production, etc) you can set the releaseStage that is reported to BugSnag.

Bugsnag::setReleaseStage('development');

You can also set the BUGSNAG_RELEASE_STAGE environment variable, or set this within config/bugsnag.php:

'release_stage' => 'development',

By default, we’ll automatically detect the app environment by calling the environment() function on Laravel’s application instance.

BugSnag is notified of errors that happen in any release stage. If you would like to change which release stages notify BugSnag of errors, you can call setNotifyReleaseStages.

Bugsnag::setNotifyReleaseStages(['development', 'production']);

You can also set the BUGSNAG_NOTIFY_RELEASE_STAGES environment variable to a comma seperated string such as development,production.

Finally, this could be set within config/bugsnag.php:

'notify_release_stages' => ['development', 'production'],

If notify_release_stages are not set notifications will still be delivered.

Sending code

BugSnag automatically sends a small snippet of the code that crashed to help you diagnose even faster from within your dashboard. If you don’t want to send this snippet, you can call setSendCode:

Bugsnag::setSendCode(false);

You can also set the BUGSNAG_SEND_CODE environment variable, or set this within config/bugsnag.php:

'send_code' => true,

By default, this is set to true.

Session endpoint

Set the endpoint to which tracked sessions reports are sent. This defaults to https://sessions.bugsnag.com, but should be overridden if you are using BugSnag On-premise, to point to your own BugSnag endpoint:

Bugsnag::setSessionEndpoint("http://localhost:43000");

Or set to the BUGSNAG_SESSION_ENDPOINT environment variable. It can also be set within config.bugsnag.php:

'session_endpoint' => "http://localhost:43000",

This defaults to https://sessions.bugsnag.com.

Strip path

To make stacktraces clearer, BugSnag can trim file paths using the setStripPath function.

Bugsnag::setStripPath('/path/to/your/app');

If you wish to use regular expressions, you can call setStripPathRegex on the client.

Bugsnag::setStripPathRegex('/^\/path\/to\/your\/app[\\/]?/i');

If the project root is set, the strip path will be set automatically too.

You can also modify these with the BUGSNAG_STRIP_PATH and BUGSNAG_STRIP_PATH_REGEX environment variables, or within config/bugsnag.php:

'strip_path' => '/path/to/your/app',
'strip_path_regex' => '/^\/path\/to\/your\/app[\\/]?/i',

By default we’ll set the strip path one directory above the app folder.