Configuration Reference

Configuration options for rollbar-php

All of the following options can be passed as keys in the $config array.

access_tokenYour project access token.
agent_log_locationPath 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_execIf the branch option is not set, we will attempt to call out to git to discover the branch name via the php shell_exec function call. If you do not want to allow shell_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
autodetect_branchThe SDK will automatically detect what Git branch you are running. This is assuming that you use Git branches in your deployment process. This configuration option requires allow_exec to be also set to true.

Default: false
base_api_urlDeprecated (endpoint instead).

The base api url to post to.

Default: https://api.rollbar.com/api/1/
branchThe Git branch you are running.

Default: null
capture_emailTrack user's email address. Pursuant to General Data Protection Regulation (GDPR) (EU) 2016/679 this option is set to false by default. If you want to capture your users' email addresses, make sure you have their consent as required by the regulation.

Default: false
capture_ipTrack user's IP address.

Default: true
capture_usernameTrack user's username. Pursuant to General Data Protection Regulation (GDPR) (EU) 2016/679 this option is set to false by default. If you want to capture your users' username, make sure you have their consent as required by the regulation.

Default: false
capture_error_stacktracesRecord full stacktraces for PHP errors.

Default: true
check_ignoreFunction called before sending payload to Rollbar, return true to stop the error from being sent to Rollbar.

Default: null

Parameters:

* $isUncaught: boolean value set to true if the error was an uncaught exception.
* $toLog: a RollbarException instance that will allow you to get the message or exception; or a string if you're logging a simple message
* $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/

Example::

php <?php $config = array( 'access_token' => '...', 'check_ignore' => function ($isUncaught, $toLog, $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_versionThe currently-deployed version of your code/application (e.g. a Git SHA). Should be a string.

Default: empty string
customAn 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.
custom_data_methodAllows creating dynamic custom data on runtime during error reporting. The callable taking two parameters $toLog (the context of what's being logged) and $context (additional context data provided in the config). You provide $context by adding custom_data_method_context key to the $extra or $context parameters Rollbar::log or RollbarLogger::log. You can see a full example of the application here: https://github.com/rollbar/rollbar-php-examples/tree/master/custom-data-method

Default: null
custom_truncationA fully qualified name of your custom truncation strategy class. It has to inherit from \Rollbar\Truncation\AbstractStrategy. This custom strategy will be applied before the built-in strategies.

Default: null
ca_cert_pathThe path to the SSL certificate used when communicating with Rollbar API through the CURL sender.

default: null
enabledEnable or disable Rollbar in your project. This can be changed at runtime with Rollbar::enable() and Rollbar::disable() or through Rollbar::configure().

If this is false then do absolutely nothing, try to be as close to the scenario where Rollbar did not exist at all in the code.

Default: true
endpointThe API URL to post to. Note: the URL must end with a trailing slash.

Default: https://api.rollbar.com/api/1/
environmentEnvironment name, e.g. production or development

Default: production
error_sample_ratesAssociative 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.

Example usage:

php <?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 );
exception_sample_ratesAssociative 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.

Example usage:

php <?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, );
fluent_hostEither an IPv4, IPv6, or a Unix socket.

Default: 127.0.0.1
fluent_portThe port on which the fluentd instance is listening on. If you use a unix socket this setting is ignored.

Default: 24224
fluent_tagThe tag of your fluentd filter and match sections. It can be any string, please consult the fluentd documentation for valid tags.

Default: rollbar
handlerEither blocking, agent, or fluent. blocking uses curl to send requests immediately; agent writes a relay log to be consumed by rollbar-agent; fluent send the requests to a fluentd instance and requires the suggested package fluent/logger.

Default: blocking
hostServer hostname.

Default: null, which will result in a call to gethostname() (or php_uname('n') if that function does not exist)
included_errnoA 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)
include_error_code_contextA 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_contextA 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
include_raw_request_bodyInclude 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_dumpBoolean that determines whether backtraces include arguments passed to stack frames.

Default: true
log_payloadLog the payload body to the configured log_payload_logger.

If this is true then we output the payload to standard out or a configured logger right before transmitting.

Default: false
log_payload_loggerUse this configuration option to override the default logger used by log_payload. It has to be an object implementing the \Psr\Log\LoggerInterface interface. Keep in mind this is completely independent of the verbose configuration option.

Note: if you're overriding the logger keep in mind the actual log method is invoked at the info level for this (independently from the level set in verbose configuration option).

Default: an instance of \Monolog\Logger with \Monolog\Handler\ErrorLogHandler configured
minimum_levelThe minimum level of occurrences that will be reported to Rolllbar.

Default: 0 which means everything will be reported.
personAn associative array containing data about the currently-logged in user. Required: id, optional: username, email. All values are strings.
person_fnA function reference (string, etc. - anything that call_user_func() can handle) returning an array like the one for 'person'.

Example usage:

php <?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';
proxySend data via a proxy server.

E.g. Using a local proxy with no authentication

php <?php $config['proxy'] = "127.0.0.1:8080";

E.g. Using a local proxy with basic authentication

php <?php $config['proxy'] = array( 'address' => '127.0.0.1:8080', 'username' => 'my_user', 'password' => 'my_password' );

Default: No proxy
raise_on_errorThe SDK can be configured to raise exceptions passed to logging methods after reporting to Rollbar. Thanks to this users can make the code below swallow exceptions in production, but throw them in test and dev environments:

php <?php Rollbar::init(array( "access_token" => $this->getTestAccessToken(), "environment" => $environment, "raise_on_error" => ($environment == "test") )); try { throw new \Exception(); } catch(\Exception $ex) { Rollbar::log(Level::ERROR, $ex); }

Default: false
report_suppressedSets whether errors suppressed with '@' should be reported or not

Default: false
rootPath to your project's root dir
scrub_fieldsAn array of field names to scrub out of the entire payload excluding the top level access_token. 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.

Note: watch out to not overlap scrub fields with the keys of the Rollbar API request format. For example, scrubbing for field request will result in scrubbing all of the request content and API will respond with a 400 error.

Default: ('passwd', 'password', 'secret', 'confirm_password', 'password_confirmation', 'auth_token', 'csrf_token')
scrub_whitelistArray of fields that you do NOT want 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.
timeoutRequest timeout for posting to rollbar, in seconds.

Default: 3
transmitShould the SDK actually perform HTTP requests to Rollbar API. This is useful if you are trying to run Rollbar in dry run mode for development or tests.

If this is false then we do all of the report processing except make the post request at the end of the pipeline.

Default: true
use_error_reportingSets whether to respect current error_reporting() level or not

Default: false
send_message_traceShould backtrace be include with string messages reported to Rollbar

Default: false
transformerThe class to be used to transform the payload before it gets prepared for sending to Rollbar API. It has to implement \Rollbar\TransformerInterface.

For a detailed example, check out our examples repository.
verboseThis configuration option controls the verbosity of the internal logs of the SDK.

Acceptable values are the levels outlined by The Syslog Protocol and PSR-3 plus none level for silent:
none
debug
info
notice
warning
error
critical
alert
* emergency

Default: none
verbose_loggerUse this configuration option to override the default logger used by verbose configuration option. It has to be an object implementing the \Psr\Log\LoggerInterface interface.

Default: an instance of \Monolog\Logger with \Monolog\Handler\ErrorLogHandler configured
max_nesting_depthMaximum depth for serialization of payloads. If set to -1, there is no limit.

Default: -1
max_itemsMaximum number of items sent in a single app request/response cycle. Currently there is no "unlimited" option, set a high value for this number if you want to allow all occurrences to be sent. PHP network activity will block the main app thread so the default limit is low for this setting.

Default: 10

📘

For more information on rollbar-php, please see the docs here.