Configuration - Laravel
Where the configuration lives
Everything sits in config/ray.php, and every value has an .env counterpart.
| Key | Default | Meaning |
|---|---|---|
token, private_key | - | project credentials; without both the package stays silent |
url | https://dockray.io | DockRay instance |
environment | APP_ENV | environment column in the panel |
release | null | version of the deployed application |
sample_rate | 1 | share of error events sent |
traces_sample_rate | 0 | share of transactions sent; 0 disables tracing |
send_default_user | true | attaches the authenticated user's id, e-mail and name |
send_default_pii | false | attaches the IP address and user agent |
ignore_exceptions | [] | exception classes never reported |
ignore_transactions | horizon*, telescope*, _debugbar* | paths never measured, patterns as in Request::is() |
options.max_request_body_size | medium | none, small, medium or always |
options.attach_stacktrace | false | a stack on plain messages as well |
Environments
Every environment should report under an unambiguous name - production, staging, preview. The name is a column in the panel and a filter on the error list, so without it a production outage looks exactly like an error someone triggered in a test. Leave your local environment without credentials: with no token and no key the integration loads and stays silent, so you do not need a separate switch to turn it off.
What to keep out of reporting
ignore_exceptions works on top of Laravel's own dontReport list, so ValidationException, AuthenticationException and HttpException are skipped with no configuration at all. Add the exceptions that are a normal outcome in your application rather than a failure:
'ignore_exceptions' => [
\App\Exceptions\PaymentDeclinedException::class,
\Illuminate\Session\TokenMismatchException::class,
],The rule is single: DockRay gets what someone is meant to act on. An expected declined payment or an expired form token is part of normal operation and only eats into the monthly quota.
Transaction naming
Transactions are named after the route pattern - GET /orders/{order}, not GET /orders/8123. That keeps one route as one row in the panel no matter how many identifiers pass through it. If you see thousands of separate transactions, it almost always means the route is defined without a parameter.
User context
The middleware attaches the authenticated user's id, e-mail address and name. Turn it off with RAY_SEND_DEFAULT_USER=false, or replace it with your own set of fields:
Ray::setUser(['id' => $account->id, 'username' => $account->slug]);The IP address and user agent are attached only when RAY_SEND_DEFAULT_PII=true. That is a separate decision from user identity, because it also covers guests.
Reporting by hand
use Dock\Ray\Laravel\Ray;
use Dock\Ray\Severity;
Ray::message('Nightly import finished late', Severity::warning());Queues and Artisan commands
Both run outside the HTTP middleware stack, so they report errors but produce no transactions. The hub is a singleton for the whole process: a long-running queue worker keeps one client and one connection rather than building one per job.
Protecting the private key
The private key is a project secret, not an identifier. Keep it in environment variables, in a secrets manager or in the server configuration - never in the repository, in logs, in a screenshot or in code sent to the browser. One project can hold many keys, so production and staging should each get their own: either can be revoked on its own without interrupting the others. A suspicion that a key leaked is reason enough to revoke it and generate a new one.