Rollbar error monitoring integration for Laravel projects. This library adds a listener to Laravel's logging component. Laravel's session information will be sent in to Rollbar, as well as some other helpful information such as 'environment', 'server', and 'session'.
Install using composer:
composer require rollbar/rollbar-laravel
Add Project Access Token post_server_item from Rollbar.com → Settings → Project Access Tokens to .env:
ROLLBAR_TOKEN=[your Rollbar project access token]
Add the service provider to the 'providers' array in config/app.php (this package also supports Laravel 5.5's auto-discovery, which allows you to skip this step):
Rollbar\Laravel\RollbarServiceProvider::class,If you only want to enable Rollbar reporting for certain environments you can conditionally load the service provider in your AppServiceProvider:
public function register()
{
if ($this->app->environment('production')) {
$this->app->register(\Rollbar\Laravel\RollbarServiceProvider::class);
}
}This package will automatically send to Rollbar every logged message whose level is higher than the ROLLBAR_LEVEL you have configured.
You can log your own messages anywhere in your app. For example, to log a debug message:
\Log::debug('Here is some debug information');You can pass user information as context like this:
\Log::error('Something went wrong', [
'person' => ['id' =>(string) 123, 'username' => 'John Doe', 'email' => '[email protected]']
]);Or pass some extra information:
\Log::warning('Something went wrong', [
'download_size' => 3432425235
]);NOTE: Fatal exceptions will always be sent to Rollbar.
Any exceptions that are not listed as $dontReport in your app/Exceptions/Handler.php or its parent will be sent to Rollbar automatically.
If you wish to override this to do more Rollbar reporting, you may do so using the Log facade in your error handler in app/Exceptions/Handler.php. For example, to log every exception add the following:
public function report(Exception $exception)
{
\Log::error($exception);
return parent::report($exception);
}For Laravel 4 installations, this is located in app/start/global.php:
App::error(function(Exception $exception, $code)
{
Log::error($exception);
});Setting up ROLLBAR_TOKEN in .env should be enough for basic configuration.
This package supports configuration through the services configuration file located in config/services.php. All rollbar configuration variables will be directly passed to Rollbar:
'rollbar' => [
'access_token' => env('ROLLBAR_TOKEN'),
'level' => env('ROLLBAR_LEVEL'),
],The level variable defines the minimum log level at which log messages are sent to Rollbar. If not specified, the default is debug. For development you could set this either to debug to send all log messages, or to none to send no messages at all. For production you could set this to error so that all info and debug messages are ignored.
By default, payloads (batched or not) are sent as part of script execution. This is easy to configure but may negatively impact performance. With some additional setup, payloads can be written to a local relay file instead; that file will be consumed by rollbar-agent asynchronously. To turn this on, set the following config params:
<?php
$config = array(
// ... rest of current config
'handler' => 'agent',
'agent_log_location' => '/var/www' // not including final slash. must be writeable by the user php runs as.
);
?>You'll also need to run the agent. See the rollbar-agent docs for setup instructions.
If you have a fluentd instance running available you can forward payloads to this instance. To turn this on, set the following config params.
<?php
$config = array(
// ... rest of current config
'handler' => 'fluent',
'fluent_host' => 'localhost', // localhost is the default setting but any other host IP or a unix socket is possible
'fluent_port' => 24224, // 24224 is the default setting, please adapt it to your settings
'fluent_tag' => 'rollbar', // rollbar is the default setting, you can adjust it to your needs
);
?>Also you will have to install a suggested package fluent/logger.
All of the following options can be passed as keys in the $config array.
- access_token
- Your project access token.
- agent_log_location
- Path to the directory where agent relay log files should be written. Should not include final slash. Only used when handler is `agent`.
Default:
/var/www - allow_exec
- If the branch option is not set, we will attempt to call out to git to discover the branch name
via the php `exec` function call. If you do not want to allow `exec` to be called, and therefore
possibly to not gather this context if you do not otherwise provide it via the separate
configuration option, then set this option to false.
Default: true
- endpoint
- The API URL to post to. Note: the URL has to end with a trailing slash.
Default:
https://api.rollbar.com/api/1/ - base_api_url
- Deprecated (use endpoint instead). The base api url to post to.
Default:
https://api.rollbar.com/api/1/ - branch
- Name of the current branch.
Default:
master - capture_error_stacktraces
- Record full stacktraces for PHP errors.
Default:
true - checkIgnore
- Function called before sending payload to Rollbar, return true to stop the error from being sent to Rollbar.
Default:
nullParameters:
- $isUncaught: boolean value set to true if the error was an uncaught exception.
- $exception: a RollbarException instance that will allow you to get the message or exception
- $payload: an array containing the payload as it will be sent to Rollbar. Payload schema can be found at https://rollbar.com/docs/api/items_post/
$config = array( 'access_token' => '...', 'checkIgnore' => function ($isUncaught, $exception, $payload) { if (isset($_SERVER['HTTP_USER_AGENT']) && strpos($_SERVER['HTTP_USER_AGENT'], 'Baiduspider') !== false) { // ignore baidu spider return true; } // no other ignores return false; }; ); Rollbar::init($config);
- code_version
- The currently-deployed version of your code/application (e.g. a Git SHA). Should be a string.
Default:
null - enable_utf8_sanitization
- set to false, to disable running iconv on the payload, may be needed if there is invalid characters, and the payload is being destroyed
Default:
true - environment
- Environment name, e.g. `'production'` or `'development'`
Default:
'production' - custom
- An array of key/value pairs which will be merged with the custom data in the final payload of all items sent to Rollbar. This allows for custom data to be added globally to all payloads. Any key in this array which is also present in the custom data passed to a log/debug/error/... call will have the value of the latter.
- error_sample_rates
- Associative array mapping error numbers to sample rates. Sample rates are ratio out of 1, e.g. 0 is "never report", 1 is "always report", and 0.1 is "report 10% of the time". Sampling is done on a per-error basis.
Default: empty array, meaning all errors are reported.
- exception_sample_rates
- Associative array mapping exception classes to sample rates. Sample rates are ratio out of 1, e.g. 0 is "never report", 1 is "always report", and 0.1 is "report 10% of the time". Sampling is done on a per-exception basis. It also respects class inheritance meaning if Exception is at 1.0 then ExceptionSublcass is also at 1.0, unless explicitly configured otherwise. If ExceptionSubclass is set to 0.5, but Exception is at 1.0 then Exception and all its' subclasses run at 1.0, except for ExceptionSubclass and its' subclasses which run at 0.5. Names of exception classes should NOT be prefixed with additional `\` for global namespace, i.e. Rollbar\SampleException and NOT \Rollbar\SampleException.
Default: empty array, meaning all exceptions are reported.
- fluent_host
- Either an `IPv4`, `IPv6`, or a `unix socket`.
Default:
'127.0.0.1' - fluent_port
- The port on which the fluentd instance is listening on. If you use a unix socket this setting is ignored.
Default:
24224 - fluent_tag
- The tag of your fluentd filter and match sections. It can be any string, please consult the [fluentd documentation](http://docs.fluentd.org/) for valid tags.
Default:
'rollbar' - handler
- Either `'blocking'`, `'agent'`, or `'fluent'`. `'blocking'` uses curl to send requests immediately; `'agent'` writes a relay log to be consumed by [rollbar-agent](https://github.com/rollbar/rollbar-agent); `'fluent'` send the requests to a [fluentd](https://www.fluentd.org/) instance and requires the suggested package `fluent/logger`.
Default:
'blocking' - host
- Server hostname.
Default:
null, which will result in a call togethostname()(orphp_uname('n')if that function does not exist) - include_error_code_context
- A boolean that indicates you wish to gather code context for instances of PHP Errors.
This can take a while because it requires reading the file from disk, so it's off by default.
Default:
false - include_exception_code_context
- A boolean that indicates you wish to gather code context for instances of PHP Exceptions.
This can take a while because it requires reading the file from disk, so it's off by default.
Default:
false - included_errno
- A bitmask that includes all of the error levels to report. E.g. (E_ERROR \| E_WARNING) to only report E_ERROR and E_WARNING errors. This will be used in combination with `error_reporting()` to prevent reporting of errors if `use_error_reporting` is set to `true`.
Default:
(E_ERROR | E_WARNING | E_PARSE | E_CORE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR) - logger
- An object that has a `log($level, $message)` method. If provided, will be used by RollbarNotifier to log messages.
- person
- An associative array containing data about the currently-logged in user. Required: `id`, optional: `username`, `email`. All values are strings.
- person_fn
- A function reference (string, etc. - anything that [call_user_func()](http://php.net/call_user_func) can handle) returning an array like the one for 'person'.
- root
- Path to your project's root dir
- scrub_fields
- Array of field names to scrub out of \_POST and \_SESSION. Values will be replaced with asterisks. If overriding, make sure to list all fields you want to scrub, not just fields you want to add to the default. Param names are converted to lowercase before comparing against the scrub list.
Default:
('passwd', 'password', 'secret', 'confirm_password', 'password_confirmation', 'auth_token', 'csrf_token') - scrub_whitelist
- Array of fields that you do NOT to be scrubbed even if they match entries in scrub_fields. Entries should be provided in associative array dot notation, i.e. `data.person.username`.
- timeout
- Request timeout for posting to rollbar, in seconds.
Default:
3 - report_suppressed
- Sets whether errors suppressed with '@' should be reported or not
Default:
false - use_error_reporting
- Sets whether to respect current `error_reporting()` level or not
Default:
false - proxy
- Send data via a proxy server.
E.g. Using a local proxy with no authentication
<?php $config['proxy'] = "127.0.0.1:8080"; ?>
E.g. Using a local proxy with basic authentication
<?php $config['proxy'] = array( 'address' => '127.0.0.1:8080', 'username' => 'my_user', 'password' => 'my_password' ); ?>
Default: No proxy
- send_message_trace
- Should backtrace be include with string messages reported to Rollbar
Default:
false - include_raw_request_body
- Include the raw request body from php://input in payloads.
Note: in PHP < 5.6 if you enable this, php://input will be empty for PUT requests
as Rollbar SDK will read from it
@see http://php.net/manual/pl/wrappers.php.php#refsect2-wrappers.php-unknown-unknown-descriptiop
If you still want to read the request body for your PUT requests Rollbar SDK saves
the content of php://input in $_SERVER['php://input']
Default:
false - local_vars_dump
- Should backtraces include arguments passed to stack frames.
Default:
false
Example use of error_sample_rates:
<?php
$config['error_sample_rates'] = array(
// E_WARNING omitted, so defaults to 1
E_NOTICE => 0.1,
E_USER_ERROR => 0.5,
// E_USER_WARNING will take the same value, 0.5
E_USER_NOTICE => 0.1,
// E_STRICT and beyond will all be 0.1
);
?>Example use of exception_sample_rates:
<?php
$config['exception_sample_rates'] = array(
// Exception omitted, so defaults to 1
// SometimesException set at 0.1 so only reported 10% of the time
'SometimesException' => 0.1,
);
?>Example use of person_fn:
<?php
function get_current_user() {
if ($_SESSION['user_id']) {
return array(
'id' => $_SESSION['user_id'], // required - value is a string
'username' => $_SESSION['username'], // optional - value is a string
'email' => $_SESSION['user_email'] // optional - value is a string
);
}
return null;
}
$config['person_fn'] = 'get_current_user';
?>This project is a Laravel wrapper of Rollbar PHP: Rollbar PHP
A CakePHP-specific package is avaliable for integrating Rollbar PHP with CakePHP 2.x: CakeRollbar
A Flow-specific package is available for integrating Rollbar PHP with Neos Flow: m12/flow-rollbar
Yii package: baibaratsky/yii-rollbar
Yii2 package: baibaratsky/yii2-rollbar
If you run into any issues, please email us at [email protected]
You can also find us in IRC: #rollbar on chat.freenode.net
For bug reports, please open an issue on GitHub.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Added some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Tests are in tests.
To run the tests: composer test
To fix code style issues: composer fix