Configuration Reference

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 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_branch

The 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_url

Deprecated (endpoint instead).

The base api url to post to.

Default: https://api.rollbar.com/api/1/

branch

The Git branch you are running.

Default: null

capture_email

Track 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_ip

Track user's IP address.

Default: true

capture_username

Track 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_stacktraces

Record full stacktraces for PHP errors.

Default: true

check_ignore

Function 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
    $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_version

The currently-deployed version of your code/application (e.g. a Git SHA). Should be a string.

Default: empty string

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.

custom_data_method

Allows 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_truncation

A 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_path

The path to the SSL certificate used when communicating with Rollbar API through the CURL sender.

default: null

enabled

Enable 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

endpoint

The API URL to post to. Note: the URL must end with a trailing slash.

Default: https://api.rollbar.com/api/1/

environment

Environment name, e.g. production or development

Default: production

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.

Example usage:

<?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_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.

Example usage:

<?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_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 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; fluent send the requests to a fluentd instance and requires the suggested package fluent/logger.

Default: blocking

host

Server hostname.

Default: null, which will result in a call to gethostname() (or php_uname('n') if that function does not exist)

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)

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

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

Boolean that determines whether backtraces include arguments passed to stack frames.

Default: true

log_payload

Log 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_logger

Use 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_level

The minimum level of occurrences that will be reported to Rolllbar.

Default: 0 which means everything will be reported.

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() can handle) returning an array like the one for 'person'.

Example usage:

<?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';

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

raise_on_error

The 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
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_suppressed

Sets whether errors suppressed with '@' should be reported or not

Default: false

root

Path to your project's root dir

scrub_fields

An 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_whitelist

Array 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.

timeout

Request timeout for posting to rollbar, in seconds.

Default: 3

transmit

Should 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_reporting

Sets whether to respect current error_reporting() level or not

Default: false

send_message_trace

Should backtrace be include with string messages reported to Rollbar

Default: false

transformer

The 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.

verbose

This 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_logger

Use 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_depth

Maximum depth for serialization of payloads. If set to -1, there is no limit.

Default: -1

max_items

Maximum 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