Skip to content

Commit c803936

Browse files
ArturMoczulskiArturMoczulski
authored
Bring configuration reference over from rollbar-php
1 parent 2978206 commit c803936

File tree

1 file changed

+367
-0
lines changed

1 file changed

+367
-0
lines changed

‎README.md

Lines changed: 367 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,3 +101,370 @@ This package supports configuration through the services configuration file loca
101101
```
102102

103103
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.
104+
105+
### Asynchronous Reporting
106+
107+
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](https://github.com/rollbar/rollbar-agent) asynchronously. To turn this on, set the following config params:
108+
109+
```php
110+
<?php
111+
$config = array(
112+
// ... rest of current config
113+
'handler' => 'agent',
114+
'agent_log_location' => '/var/www' // not including final slash. must be writeable by the user php runs as.
115+
);
116+
?>
117+
```
118+
119+
You'll also need to run the agent. See the [rollbar-agent docs](https://github.com/rollbar/rollbar-agent) for setup instructions.
120+
121+
122+
### Centralized Log Aggregation with fluentd
123+
124+
If you have a [fluentd](https://www.fluentd.org/) instance running available you can forward payloads to this instance. To turn this on, set the following config params.
125+
126+
```php
127+
<?php
128+
$config = array(
129+
// ... rest of current config
130+
'handler' => 'fluent',
131+
'fluent_host' => 'localhost', // localhost is the default setting but any other host IP or a unix socket is possible
132+
'fluent_port' => 24224, // 24224 is the default setting, please adapt it to your settings
133+
'fluent_tag' => 'rollbar', // rollbar is the default setting, you can adjust it to your needs
134+
);
135+
?>
136+
```
137+
138+
Also you will have to install a suggested package `fluent/logger`.
139+
140+
141+
### Configuration reference
142+
143+
All of the following options can be passed as keys in the `$config` array.
144+
145+
<dl>
146+
<dt>access_token
147+
</dt>
148+
<dd>Your project access token.
149+
</dd>
150+
151+
<dt>agent_log_location
152+
</dt>
153+
<dd>Path to the directory where agent relay log files should be written. Should not include final slash. Only used when handler is `agent`.
154+
155+
Default: `/var/www`
156+
</dd>
157+
158+
<dt>allow_exec
159+
</dt>
160+
<dd>If the branch option is not set, we will attempt to call out to git to discover the branch name
161+
via the php `exec` function call. If you do not want to allow `exec` to be called, and therefore
162+
possibly to not gather this context if you do not otherwise provide it via the separate
163+
configuration option, then set this option to false.
164+
165+
Default: true
166+
</dd>
167+
168+
<dt>endpoint
169+
</dt>
170+
<dd>The API URL to post to. Note: the URL has to end with a trailing slash.
171+
172+
Default: `https://api.rollbar.com/api/1/`
173+
</dd>
174+
175+
<dt>base_api_url
176+
</dt>
177+
<dd><strong>Deprecated (use <i>endpoint</i> instead).</strong> The base api url to post to.
178+
179+
Default: `https://api.rollbar.com/api/1/`
180+
</dd>
181+
182+
<dt>branch
183+
</dt>
184+
<dd>Name of the current branch.
185+
186+
Default: `master`
187+
</dd>
188+
189+
<dt>capture_error_stacktraces
190+
</dt>
191+
<dd>Record full stacktraces for PHP errors.
192+
193+
Default: `true`
194+
</dd>
195+
196+
<dt>checkIgnore
197+
</dt>
198+
<dd>Function called before sending payload to Rollbar, return true to stop the error from being sent to Rollbar.
199+
200+
Default: `null`
201+
202+
Parameters:
203+
* $isUncaught: boolean value set to true if the error was an uncaught exception.
204+
* $exception: a RollbarException instance that will allow you to get the message or exception
205+
* $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/
206+
207+
```php
208+
$config = array(
209+
'access_token' => '...',
210+
'checkIgnore' => function ($isUncaught, $exception, $payload) {
211+
if (isset($_SERVER['HTTP_USER_AGENT']) && strpos($_SERVER['HTTP_USER_AGENT'], 'Baiduspider') !== false) {
212+
// ignore baidu spider
213+
return true;
214+
}
215+
216+
// no other ignores
217+
return false;
218+
};
219+
);
220+
Rollbar::init($config);
221+
```
222+
223+
</dd>
224+
225+
<dt>code_version
226+
</dt>
227+
<dd>The currently-deployed version of your code/application (e.g. a Git SHA). Should be a string.
228+
229+
Default: `null`
230+
</dd>
231+
232+
<dt>enable_utf8_sanitization
233+
</dt>
234+
<dd>set to false, to disable running iconv on the payload, may be needed if there is invalid characters, and the payload is being destroyed
235+
236+
Default: `true`
237+
</dd>
238+
239+
<dt>environment
240+
</dt>
241+
<dd>Environment name, e.g. `'production'` or `'development'`
242+
243+
Default: `'production'`
244+
</dd>
245+
246+
<dt>custom
247+
</dt>
248+
<dd>An array of key/value pairs which will be merged with the custom data in the final payload of
249+
all items sent to Rollbar. This allows for custom data to be added globally to all payloads. Any key
250+
in this array which is also present in the custom data passed to a log/debug/error/... call will
251+
have the value of the latter.
252+
</dd>
253+
254+
<dt>error_sample_rates
255+
</dt>
256+
<dd>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.
257+
258+
Default: empty array, meaning all errors are reported.
259+
</dd>
260+
261+
<dt>exception_sample_rates
262+
</dt>
263+
<dd>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.
264+
265+
Default: empty array, meaning all exceptions are reported.
266+
</dd>
267+
268+
<dt>fluent_host</dt>
269+
<dd>Either an `IPv4`, `IPv6`, or a `unix socket`.
270+
271+
Default: `'127.0.0.1'`
272+
</dd>
273+
274+
<dt>fluent_port</dt>
275+
<dd>The port on which the fluentd instance is listening on. If you use a unix socket this setting is ignored.
276+
277+
Default: `24224`
278+
</dd>
279+
280+
<dt>fluent_tag</dt>
281+
<dd>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.
282+
283+
Default: `'rollbar'`
284+
</dd>
285+
286+
<dt>handler
287+
</dt>
288+
<dd>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`.
289+
290+
Default: `'blocking'`
291+
</dd>
292+
293+
<dt>host
294+
</dt>
295+
<dd>Server hostname.
296+
297+
Default: `null`, which will result in a call to `gethostname()` (or `php_uname('n')` if that function does not exist)
298+
</dd>
299+
300+
<dt>include_error_code_context
301+
</dt>
302+
<dd>A boolean that indicates you wish to gather code context for instances of PHP Errors.
303+
This can take a while because it requires reading the file from disk, so it's off by default.
304+
305+
Default: `false`
306+
</dd>
307+
308+
<dt>include_exception_code_context
309+
</dt>
310+
<dd>A boolean that indicates you wish to gather code context for instances of PHP Exceptions.
311+
This can take a while because it requires reading the file from disk, so it's off by default.
312+
313+
Default: `false`
314+
</dd>
315+
316+
<dt>included_errno
317+
</dt>
318+
<dd>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`.
319+
320+
Default: `(E_ERROR | E_WARNING | E_PARSE | E_CORE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR)`
321+
</dd>
322+
323+
<dt>logger
324+
</dt>
325+
<dd>An object that has a `log($level, $message)` method. If provided, will be used by RollbarNotifier to log messages.
326+
</dd>
327+
328+
<dt>person
329+
</dt>
330+
<dd>An associative array containing data about the currently-logged in user. Required: `id`, optional: `username`, `email`. All values are strings.
331+
</dd>
332+
333+
<dt>person_fn
334+
</dt>
335+
<dd>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'.
336+
</dd>
337+
338+
<dt>root
339+
</dt>
340+
<dd>Path to your project's root dir
341+
</dd>
342+
343+
<dt>scrub_fields
344+
</dt>
345+
<dd>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.
346+
347+
Default: `('passwd', 'password', 'secret', 'confirm_password', 'password_confirmation', 'auth_token', 'csrf_token')`
348+
</dd>
349+
350+
<dt>scrub_whitelist
351+
</dt>
352+
<dd>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`.
353+
</dd>
354+
355+
<dt>timeout
356+
</dt>
357+
<dd>Request timeout for posting to rollbar, in seconds.
358+
359+
Default: `3`
360+
</dd>
361+
362+
<dt>report_suppressed</dt>
363+
<dd>Sets whether errors suppressed with '@' should be reported or not
364+
365+
Default: `false`
366+
</dd>
367+
368+
<dt>use_error_reporting</dt>
369+
<dd>Sets whether to respect current `error_reporting()` level or not
370+
371+
Default: `false`
372+
</dd>
373+
374+
<dt>proxy</dt>
375+
<dd>Send data via a proxy server.
376+
377+
E.g. Using a local proxy with no authentication
378+
379+
```php
380+
<?php
381+
$config['proxy'] = "127.0.0.1:8080";
382+
?>
383+
```
384+
385+
E.g. Using a local proxy with basic authentication
386+
387+
```php
388+
<?php
389+
$config['proxy'] = array(
390+
'address' => '127.0.0.1:8080',
391+
'username' => 'my_user',
392+
'password' => 'my_password'
393+
);
394+
?>
395+
```
396+
397+
Default: No proxy
398+
</dd>
399+
400+
<dt>send_message_trace</dt>
401+
<dd>Should backtrace be include with string messages reported to Rollbar
402+
403+
Default: `false`
404+
</dd>
405+
406+
407+
<dt>include_raw_request_body</dt>
408+
<dd>Include the raw request body from php://input in payloads.
409+
Note: in PHP < 5.6 if you enable this, php://input will be empty for PUT requests
410+
as Rollbar SDK will read from it
411+
@see http://php.net/manual/pl/wrappers.php.php#refsect2-wrappers.php-unknown-unknown-descriptiop
412+
If you still want to read the request body for your PUT requests Rollbar SDK saves
413+
the content of php://input in $_SERVER['php://input']
414+
415+
Default: `false`
416+
</dd>
417+
418+
<dt>local_vars_dump</dt>
419+
<dd>Should backtraces include arguments passed to stack frames.
420+
421+
Default: `false`
422+
</dd>
423+
424+
</dl>
425+
426+
Example use of error_sample_rates:
427+
428+
```php
429+
<?php
430+
$config['error_sample_rates'] = array(
431+
// E_WARNING omitted, so defaults to 1
432+
E_NOTICE => 0.1,
433+
E_USER_ERROR => 0.5,
434+
// E_USER_WARNING will take the same value, 0.5
435+
E_USER_NOTICE => 0.1,
436+
// E_STRICT and beyond will all be 0.1
437+
);
438+
?>
439+
```
440+
441+
Example use of exception_sample_rates:
442+
443+
```php
444+
<?php
445+
$config['exception_sample_rates'] = array(
446+
// Exception omitted, so defaults to 1
447+
448+
// SometimesException set at 0.1 so only reported 10% of the time
449+
'SometimesException' => 0.1,
450+
);
451+
?>
452+
```
453+
454+
Example use of person_fn:
455+
456+
```php
457+
<?php
458+
function get_current_user() {
459+
if ($_SESSION['user_id']) {
460+
return array(
461+
'id' => $_SESSION['user_id'], // required - value is a string
462+
'username' => $_SESSION['username'], // optional - value is a string
463+
'email' => $_SESSION['user_email'] // optional - value is a string
464+
);
465+
}
466+
return null;
467+
}
468+
$config['person_fn'] = 'get_current_user';
469+
?>
470+
```

0 commit comments

Comments
 (0)